A link file is a json file with the ending extension .link
and its used to redirect to another real asset file path.
They are also used to deduplicate (remove copies) of the same asset and also redirect an old path towards a new path of the asset, hence solving the problem with mods that reference assets where we need to keep the path unchanged.
They behave more or less like symlinks in Windows.
Inside the link file there is information about the path redirected by the link file, with additional info about the asset and what the link is supposed to represent.
Lets say we have an example link file:
levels/Gridmap/art/brick.dds.link
You use the link in the game (scripts or editor) as a normal path, but without the .link
extension:
levels/Gridmap/art/brick.dds
The VFS will check first to see if a real .dds
file is existing, otherwise it will check if that path with an appended .link
exists, if so, it loads the link file and does the redirection to the new path.
Lets analyze:
path
- this is the redirect path for the link, so this path/file will be actually loaded by the game
assetUuid
- this is the asset’s UUID, used as a failsafe to search for the asset in the whole data folder, if that path is not existing (not implemented, TBD)
assetVersion
- (optional) what version of the asset to use (not implemented, TBD)
type
- (optional) this is the type of the link, which can be:
Usually link files should be used for the /levels
folders, all the assets that can be put in the common /assets
folder, not related to a specific level, should be moved there, and in-place of that path, you should place a link with the old file’s name.
Levels should ideally only contain link files for the assets and specific level files (scene tree folders and files, terrain etc.).
Link files can also solve the problem where multiple mods are overriding the same (global) asset. If you place the common asset to lets say 3 levels into /assets
folder and create link files to it in each of the level folders, then if the mods override that for the specific level they want to modify, the asset would remain unchanged in the other levels.
Then, in every level, we want to use their specific paths to load that asset:
For example in the Industrial level we will use the following in the editor or lua scripts: /levels/Industrial/art/red_brick.dds
If a mod will override /levels/Industrial/art/red_brick.dds
it will practically replace the link with an actual asset or even the same link file but with a different redirection path.
All this, while the other levels will still use the unchanged red_brick.dds
asset from /assets
.
If official assets need to move/migrate and we want to emphasize that to the modders, we create a link in its place and use the migrated
type for it:
When we want to remove an asset from the official asset files, we can put a link file in its place, with the same name and of course the .link
extension and give it the removed
type, this way tools and modders know what happened to that asset and act accordingly:
Keep in mind that the materials, models and other json assets that use this /levels/Industrial/art/red_brick.dds
path would need to be inside the level folder so everything is to be local to that level. That is needed because if for example a material is in the global /assets
common folder and its used in several levels and this material uses the path to that specific level, then if this material is overridden by a mod, it will change for all levels and we might not want that.
This would need duplication of things in the level folders, for the json-based assets, in essence we cannot have a common materials folder.
Ideally, link files should mainly point to assets that dont reference other assets, like textures, sounds, raw mesh data, etc.
The mods overriding files will work with the link files, since when you override a link file, you would just add a real asset without the .link
extension, which has priority in the VFS, over the link files.
Link files support file change notifications, when a link file content (json) is changed, there will be a notification for that. When an asset which is targeted by a link file is changed it will be added to the file change notification list along with all the link files that are pointing to it, so this should work while editing the game data in editor and game.
Was this article helpful?