Module paths 

Project state root: where the engine’s state tree is anchored, and the names of the directories hanging off it.

Everything the engine writes for a project lives under one state directory: the compiled blobs (data/), the payload cache (cache/), fetched source assets (assets/), named worlds (worlds/), the runtime save files (saves/), and the mutable settings file (settings).

Nothing here has a default. A host installs the state directory via set_state_dir before anything reads the tree, and until it does every path below resolves to None. The naming of that directory is the host’s business, not this crate’s: the dev CLI hides it inside the project, a shipped application puts it beside its executable, and an embedder points it wherever its own layout implies. Reads that cannot proceed without a state tree report CnResult::NoStateRoot; the caches and the settings file simply do nothing.

The read-only content of the tree (data/) and the runtime-writable state (saves/ + settings) usually share one root, but a shipped application installed in a read-only location (Program Files) cannot write beside its data. Such an application installs a separate writable root via set_writable_state_dir so only saves/ and settings relocate to a per-user directory while data/ stays beside the executable.

Resolution touches no files: these functions compute paths. Reading the tree is super::source (finding a source asset) and super::blob (the compiled blob).

Functions

assets_dir

The state root’s assets/ directory.

bundled_shader_cache_dir

Directory holding shader binaries shipped inside a bundle, read-only. cn export warms this so a player’s first launch does not pay the compile; because the artifacts are backend IR (DXBC / SPIR-V) rather than machine code, one warmed at package time is valid on any machine.

cache_dir

The state root’s cache/ directory.

clear_state_dir

Remove an installed state dir, leaving the process with no state tree.

clear_writable_state_dir

Remove an installed writable-state dir, restoring writable state to the content root beside data/.

crashes_dir

Directory holding crash reports (and minidumps) written by the crash reporting machinery. Resolves under the writable-state dir like saves/, since a shipped install’s content root may be read-only. Created on first write; capped by the writer’s retention pruning, never by a build.

data_dir

The state root’s data/ directory.

pipeline_cache_dir

Directory the renderer persists driver pipeline blobs to (a serialized VkPipelineCache, a D3D12 pipeline library), keyed per adapter. Unlike shader_cache_dir artifacts these are machine code tied to one GPU and driver, so they resolve under the writable-state dir only and never ship in a bundle. A sibling of shader-cache/ rather than a subdirectory, since the shader cache prunes its directory by age and would reclaim these.

preview_saves_dir

Sandboxed sibling of saves_dir for preview sessions (see the TransientSaves protocol resource): the save UI keeps working against this directory, but the real saves are never touched and the sandbox is wiped at each session start.

saves_dir

Directory holding the runtime save files (auto, save1 ..). Created on first write by the running application, never by a build. Resolves under the writable-state dir, which is the content root unless an application redirected it.

set_state_dir

Anchor the state tree at dir for the rest of the process, so data/, saves/, and settings resolve under it. Every host installs one before reading project state: the dev CLI its project directory, a shipped application the directory beside its executable (or inside its app bundle), an embedder whatever its own layout implies.

set_writable_state_dir

Anchor the runtime-writable state (saves/ + settings) at dir, leaving the read-only content (data/) at the installed state dir. A shipped application installs this when its content dir is not writable (a read-only install such as Program Files), redirecting only what it writes at runtime to a per-user directory. When unset, writable state stays beside data/.

settings_path

The mutable settings file (CBOR). Written by the in-engine settings menu, never by a build. A sibling of data/ in the common case, or under the writable-state dir when a read-only install redirected it.

shader_cache_dir

Directory the renderer writes compiled built-in shader binaries to, keyed by a hash of their compile inputs. Resolves under the writable-state dir, since a shipped install’s content root may be read-only. Distinct from cache_dir, which holds cooked asset payloads: these artifacts belong to the machine’s shader compiler, not to the build.

state_dir

The state directory, or None when no host installed one.

thumbnails_dir

Directory holding baked asset thumbnails: content-addressed <sha256>.png files plus an index.json mapping asset names to keys. Deterministic products of the build like cache_dir’s payloads, but kept apart so they can be listed and cleared independently (and never ship: cn export copies neither).

worlds_dir

The state root’s worlds/ directory.

writable_state_dir

The directory holding runtime-writable state (saves/ + settings): the writable override when one is installed, otherwise the state dir (writable state sits beside data/).