Logical Paths

Authored data uses two stable logical roots:

@assets/... for application- or workspace-local assets under the active asset base;
@shared/... for repository-shared runtime assets.

These tokens are serialized authority. BulletSketch may label them as Project Assets and Shared Assets, but authored files, logs, copied references, and runtime resolution retain the aliases.

Filesystem owns logical-path and packaged-runtime resolution. Bazel runfiles construction is private implementation. Remote or detached content belongs in an asset source/catalog/cache layer above Filesystem, not in new meanings for the aliases.

Authored And Generated Data

YAML is the editable content format for scenes, prefabs, materials, environments, and framework-owned gameplay profiles. The owning module defines each format's keys, tokens, validation, and compatibility.

Generated binary data is paired with its owning authored or imported asset:

prefab sidecars accelerate compatible prefab loads;
mesh, skeleton, and animation binaries are asset-owned runtime data;
imported environment and texture outputs are generated runtime assets.

Generated data is not editor-local cache simply because it is binary. Runtime loaders validate magic, version, declared sizes, metadata, and source trust before allocation or materialization. A missing, stale, invalid, or incompatible sidecar falls back to the authored source when that format supports fallback.

Serialization Foundations

pixelbullet::SerializationResult is defined by pixelbullet/serialization/serialization_result.h. Generic Node file IO is defined by pixelbullet/serialization/node_file_io.h as serialization::read_node_file and serialization::write_node_file.

YAML scalar classification is strict: quoted or non-plain scalars remain strings, booleans use exact tokens, and authored numeric token classes are preserved. Settings and save-state YAML use the same neutral node file IO.

Internal helpers under engine/src/serialization remove repeated physical-file and binary stream mechanics. They do not own asset schemas, format versions, codec registries, or compatibility policy.

Ownership Across Assets, Scene, Image, And Graphics

engine/src/assets owns materials, meshes, animation data, environment assets, glTF inspection/import, and format-specific validation.
engine/src/scene owns generic scene/prefab data, dependency enumeration, serialization, and render extraction.
engine/src/image owns packed RGBA8 Bitmap and private image codecs, including the focused EXR decoder.
engine/src/graphics owns graphics resources and neutral render facades.
engine/integration exposes only the payload or operation needed across those ownership boundaries.

Important asset-backed integration seams are:

mesh data: pixelbullet/integration/graphics/meshes/mesh_data.h;
material data: pixelbullet/integration/graphics/materials/material_data.h;
environment data: pixelbullet/integration/graphics/environments/environment_data.h;
scene mesh bounds: engine/integration/scene/assets:mesh_bounds;
material texture dependencies: pixelbullet/integration/scene/assets/material_texture_dependencies.h;
environment cubemap dependencies: pixelbullet/integration/scene/assets/environment_cubemap_dependencies.h;
skeleton/animation runtime data: pixelbullet/integration/scene/assets/skeleton_animation_runtime_data.h;
selected-asset details: pixelbullet/integration/assets/asset_details.h.

glTF Import Boundary

framework/authoring owns staging plans, dependency copies, document mutation, and editor-facing status. Asset implementation owns cgltf-backed source inspection and generated prefab import behind:

pixelbullet/integration/assets/gltf_source_dependencies.h;
pixelbullet/integration/assets/gltf_prefab_import.h.

Local relative file URIs, embedded buffers, and data URIs are supported. Remote/file schemes, absolute paths, backslashes, malformed escapes, encoded separators, alias tokens, and paths escaping the selected root are rejected before dependency IO. Non-finite mesh, transform, animation, skin, morph, and material values are rejected before generated outputs are committed.

Both authoring copy application and glTF output generation use staging before replacing final files so failure does not leave a partially written authored closure.

Authoring Derived State

Asset manifests, browser snapshots, dependency indexes, material-reference caches, and watch snapshots are derived authoring state. Persistent forms are best-effort user-local caches and are accepted only when their roots and source metadata match. Invalid or stale state rebuilds from authored files and does not change authored YAML, watch semantics, or public runtime formats.

Runtime Closure

A runnable artifact owns a deliberate closure, not the entire shared depot by default. Bazel development runs use runfiles; extracted bundles use paths under build_output. The concrete editor closure is documented in Packaging and Distribution.