Link Files

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.

Normal Links

Normal link files diagram Normal link files diagram

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:

  • normal - just a normal link to a file (used to deduplicate), this is the default type, if type is not specified
  • migrated - its a link to a moved file, this way mod makers know that file moved, but they can still use the old path, but recommended they should use the new path
  • removed - this is a link with an empty path, meaning the asset was actually removed, used as a placeholder for people to know an asset was deleted for good

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.

Asset Migration Links

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:

Asset Removal Links

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.

Last modified: August 26, 2025

Any further questions?

Join our discord
Our documentation is currently incomplete and undergoing active development. If you have any questions or feedback, please visit this forum thread.