External files 1.0.1 Tools 4.2 Community

Submitted by user mathrick; MIT; 2024-11-07

Godot External Files plugin is a partial substitute for symlinks, allowing referencing files outside of the project dir.

The intended use-case is a pretty specific situation, where some assets might live outside of the Godot project directory, but still need to be accessed by Godot, such as for example when porting a game from Ren'Py in parallel to the Ren'Py version still being actively worked on.

Unlike just copying the files, the referenced external files will be kept up to date, and will also not bloat your repository. And unlike symlinks, the plugin doesn't need OS support and thus can be run easily on Windows, or with version control systems like Mercurial, which do not support symlinks at all (again, due to their lack of portability).

For full documentation, click "View files" and visit the plugin's home page.

Changes:
* Version 1.0.1
- Minor documentation and icon fixes
* Version 1.0
- Initial release

Usage
=====

> **IMPORTANT**: Make sure to enable the plugin under Project → Project Settings... → Plugin after installing!

Quick start
-----------

To use the plugin, you will need to create some files which will instruct it what files to copy whenever your Godot project is opened.

First determine what assets need to be shared. For example, let's assume your project's repository looks like this:


my_game/
├── godot/
│   ├── assets/
│   │   └── sprites/
│   └── project.godot
└── renpy/
   └── game/
   └── images/
   └── sprites/
   ├── some_sprite.png
   ├── other_sprite.png
   └── ...


And you'd like to have all PNG files from `renpy/game/images/sprites/` available under `godot/assets/sprites/`.

To do that, create a file called `godot/assets/sprites/.external_files`, then put the following lines in it:

## root: ../renpy/game/images/sprites
syntax: glob

*.png

> **NOTE**: Godot's editor limits what kinds of files it will let you create, and will NOT allow you to make or edit `.external_files`. You will need to use a different text editor, and they will not show up in the filesystem dock inside Godot.

Now reload your Godot project, or click Project → Tools → External files → Re-scan. You will see that `godot/assets/sprites/some_sprite.png` and `godot/assets/sprites/other_sprite.png` have been automatically copied and imported by Godot.

Depending on the number of files, it might take a while for all the files to be copied and imported. This is a one-time operation; the next time the project will open instantly and not copy anything, unless some files have changed.

For full usage information and description of the syntax, click "View files" and visit the plugin's home page.