Skip to content

Authoring Mods: VFS and Asset Overrides

The virtual file system (VFS) resolves read-only game assets from loose development overrides, enabled package layers, shared data, and the original installation. A mod can replace a complete asset or an individual LBX entry without modifying the original files.

Public and private package paths

Only files below a package's data/ directory become public assets:

data/mods/visual_mod/
  mod.json5
  config/main.cfg
  data/
    INTRO.LBX
    music/theme.dat

The virtual paths supplied by this package are INTRO.LBX and music/theme.dat. In a ZIP package, the equivalent entries are also data/INTRO.LBX and data/music/theme.dat.

Files beside mod.json5, including CFG, Lua, modules, and migrations, remain in the package-private namespace. An INTRO.LBX placed at package root does not replace the game asset.

Supported asset reads

The VFS is used for read-only data including:

  • LBX resources and streamed LBX-backed audio;
  • animations loaded through normal resource loaders;
  • Smacker video assets; and
  • generic assets opened through the VFS.

It does not redirect save games, ORION2RE.SET, language.ini, orioncd.ini, temporary files, or other write paths. A mod must not expect a file placed under its public data/ subtree to become a writable save or settings location.

Resolution order

For each virtual asset, version 2.00 searches:

  1. loose data/overrides/;
  2. enabled package data/ projections, highest-priority package first;
  3. optional data/base.zip;
  4. loose files under data/;
  5. original files in the game directory; and
  6. original files in the configured fallback installation path, if present.

The first match wins. A loose development override hides every mod version. The first enabled package wins a collision with later packages. All enabled packages win over shared data and original assets.

data/base.zip is the only archive mounted automatically from data/. Mod archives belong under data/mods/ and still require an enable statement.

Whole-file replacement

Reproduce the virtual path below the package's public data/ directory:

data/mods/visual_mod/data/INTRO.LBX

Use the path expected by the game, not the local path of an unrelated installation. Asset matching is case-insensitive, but distribute one canonical spelling. Archive entries that normalize to the same virtual path are invalid.

Individual LBX entry replacement

To replace only one entry, use the LBX filename as a directory and a zero-padded three-digit entry number:

data/mods/visual_mod/data/COLBLDG0.LBX/000
data/mods/visual_mod/data/COLBLDG0.LBX/012

The override file contains only that entry's payload, not an LBX header or table. When entry 12 is requested, the VFS first searches COLBLDG0.LBX/012 through the normal source order. If it finds no entry override, it finds the highest-priority complete COLBLDG0.LBX and reads entry 12 from that file.

An entry override therefore wins for its one entry even when another visible layer provides a complete replacement LBX. Unchanged entries continue to come from the highest-priority complete file.

Development overrides

data/overrides/ is useful for discovering paths and testing a replacement quickly. It is not a package:

  • it needs no manifest or enable statement;
  • it has higher priority than all packages;
  • it has no package identity, dependencies, version, or save compatibility declaration; and
  • it should not be used for distribution.

Before publishing, move every required override into the package's data/ subtree and remove the loose development copy. Otherwise a local file may make the package appear to work while the ZIP is incomplete.

ZIP requirements

ZIP assets are read directly without extraction. Use ordinary non-encrypted entries and safe relative paths. Package activation rejects malformed archives, unsafe traversal paths, unsupported or encrypted entries, and duplicate normalized paths.

Archive root should look like:

mod.json5
config/main.cfg
data/INTRO.LBX
data/COLBLDG0.LBX/012

Do not archive the containing visual_mod/ directory itself.

Collision testing

Test both resource and CFG collisions because they use the same package priority in opposite processing directions: the first package is searched first for assets and applied last for configuration.

When the wrong asset appears:

  1. Remove or inspect data/overrides/.
  2. Confirm the package is enabled.
  3. Confirm the asset is below the package's data/ directory.
  4. Confirm the first enabled package is intended to win.
  5. Check case-insensitive duplicate paths in the directory or ZIP.
  6. For an LBX entry, confirm the three-digit entry number and payload-only format.