Crate pite_scene 

Scene serialization, node tree instantiation, validation, and binary caching for the Pite game engine.

Human-readable TOML files (.ptscn) serve as the canonical source of truth for scene layouts, while derived binary snapshots (_cache/*.bin) accelerate runtime loading. Depends solely on pite-core.

Re-exports

pub use cache::CacheStatus;

pub use cache::CACHE_VERSION;

pub use color::format_hex_color;

pub use color::parse_hex_color;

pub use tilemap::load_tilemap;

pub use tilemap::map_to_world;

pub use tilemap::parse_tilemap_str;

pub use tilemap::save_tilemap;

pub use tilemap::world_to_map;

pub use tilemap::TileCell;

pub use tilemap::TileMapDoc;

pub use tilemap::TileMapLayer;

Modules

cache

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

color

Hex color encoding for the scene file format.

tilemap

TileMap document schema, TOML serialization, coordinate math, and layer management.

Structs

SceneDoc

Canonical .ptscn 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, fill defaults, remap ids with prefix, 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

prop_to_toml

Convert a PropValue back to its scene-file TOML shape. The inverse of toml_to_prop: Color becomes "#rrggbbaa", Vec2 becomes [x, y], primitives map to their natural TOML types, and any unrecognized variant (future) falls back to a string.

resolve_scene_ref

save_scene

to_node_tree

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

toml_to_prop

validate

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