Runtime Path Roots And Packaged Asset Resolution

Runtime path roots decide where the engine reads assets, writes local config, stores state, stores cache, and resolves packaged executable assets.

Purpose

Use this page when local saves go to the wrong place, packaged builds cannot find assets, smoke tests fail on path normalization, or a feature needs a new local file root.

Required Inputs

Important inputs include AETHER_ASSET_ROOT, AETHER_LOCAL_CONFIG_ROOT, AETHER_LOCAL_STATE_ROOT, AETHER_LOCAL_CACHE_ROOT, runtime mode, executable location, platform user directories, and canonical asset or scene reference paths.

Procedure

Prefer explicit env roots in tests and automation. In debug and test runs, resolve assets from the repo or configured asset root. In packaged release, verify assets are beside the executable or in the expected packaged asset root. Normalize asset paths and scene references before storing them in durable content.

Failure Modes

Packaged executables often fail when assets are assumed to live at repo root. Bad path normalization appears as missing scenes, dialogue, UI layouts, or smoke fixtures. Platform user-dir fallback issues can send saves or cache files to unexpected locations.

Verification

Run doctor, local playtest, or world-entry smoke with explicit roots. Confirm the path root report, asset host path, and canonical scene references match the intended environment.