Crate pite_scene 

pite-scene: TOML schema, instantiation, validation, migration.

Depends on pite-core only. TOML is canonical; binary is a later export cache, not a source format.

Re-exports

pub use cache::CacheStatus;

pub use cache::CACHE_VERSION;

Modules

cache

Binary scene cache: TOML stays source of truth; _cache/ holds content-hash-keyed, version-stamped binaries.

Structs

SceneDoc

Canonical .pitescene document.

SceneInstance

An instantiation entry: load the referenced file, clone its subtree under parent, remap ids with prefix, apply prop overrides. Overrides are keyed "node_id.prop"; unknown targets fail loudly.

SceneNode

One flat node entry. props preserves unknown keys (forward compat).

SceneScript

Attached script reference (project-relative path + class).

Constants

FORMAT_VERSION

Current scene format version. Bump = migrate or error loudly, never silent.

Functions

build_tree

Build the full runtime tree: host nodes plus every [[instance]] subtree (loaded, id-remapped, overrides applied).

instantiate

Load the referenced scene, clone its subtree, apply prop overrides. Returns node records ready to insert into the host tree plus the remapped id of the referenced scene’s root.

load_cached

Load with the binary cache: a valid cache wins; a missing cache parses TOML and writes the cache; a corrupt or version-mismatched cache parses TOML, rewrites the cache, and reports the fallback loudly via the returned warning — never silently. TOML stays source of truth.

load_scene

load_scene_cached

Preferred entry point: load_cached with the fallback warning surfaced loudly on stderr. Corruption anywhere falls back to TOML, never silently.

migrate

Format migration hook (§12). New fields are additive; breaking change = version bump, never silent reinterpretation.

parse_scene_str

save_scene

to_node_tree

Convert a scene document into a runtime NodeTree. Missing scripts are placeholders here, never a load failure.

validate

Structural validation. Missing script = placeholder, never a load failure; unknown props warn and are preserved on save.