Assets

Purpose

Assets discovers source files and manifests, prepares owned CPU data and publishes reusable images, sprites, tilesets, shaders and materials. Application classes keep their own position, behavior and animation state while sharing immutable assets.

Interface

Types below are in CE::Assets unless another namespace is shown.

Types and operations

API and purpose
`Loading::Loader`, `Loading::Prepared` Prepare owned CPU input, upload on the provider owner, or synchronously `load_assets()`. Loading entry point; publication and retry.
`Loading::FileRegistry`, `Manifests::Graphics` Discover indexed files and retain parsed manifest metadata. Index selection; typed consumers.
`Sprites::Manager`, `Tilesets::Manager` Retrieve shared sprite/tile assets; validate handles before use. Resources and caches; sprite walkthrough.
Catalogue sources and exact-key changes Observe complete Published/Replaced/Reset commits, retain generation metadata and read native-domain provenance separately. Upload settlement remains one outcome per executed batch.
`Graphics::Asset` Load a whole image or wrap an uploaded image as a retained quad with a default material. Draw a whole image.
`Sprites::Definition`, `Tilesets::Definition`, `Grids::Definition` Describe immutable atlas grids, cells, clips and tile rules. Grid coordinates; manifest schema.
`Sprites::Animation`, `Tilesets::Animation` Keep independent playback cursors over shared clip metadata. Sprite playback; tile playback.

Selection values and enums

Type	Choices and details
`Grids::CellIndex`, `Grids::View`	Address cells and resolve authored grid geometry/UVs. Grid and cell addressing; coordinates.
`Tilesets::Direction`	Eight compass neighbors used by tile selection. Tile selection.
`Tilesets::BitmaskType`, `Tilesets::WangType`	Four/eight-neighbor masks or corner/edge Wang rules. Tile rules; autotile schema.
`Sprites::Clip`, `Sprites::Profile`	Select named clip timing and application-selected animation profiles. Animations; animation task.

Usage

Load a root during platform initialization, then retain the resulting asset handles in application-owned objects. For larger loads, split CPU preparation from provider-owned upload; the application selects and schedules that split.

        ---
config:
  theme: base
  themeVariables:
    fontFamily: system-ui, sans-serif
    fontSize: 14px
  flowchart:
    htmlLabels: true
    curve: linear
    nodeSpacing: 22
    rankSpacing: 38
    padding: 12
---
flowchart LR
    accTitle: Assets · simple loading and lookup
    accDescr: Local names omit Assets::; ambiguous nested namespaces remain qualified. Arrows point toward dependencies. Application roles are rounded; named API operations have rounded corners. Dashed arrows mark optional choices.
    k0(["Application<br/>init_platform()"]):::app
    k1["Loading::<br/>Loader"]:::focal
    k2["Loading::<br/>Prepared"]:::focal
    k3["Rendering::Resources::<br/>Provider"]:::neighbor
    k4(["Application-owned game objects"]):::app
    k5["Sprites::<br/>Manager"]:::focal
    k6["Sprites::<br/>Asset"]:::focal
    k0 --> k1
    k1 --> k2
    k1 --> k3
    k4 --> k5
    k5 --> k6
    k4 --> k6
    classDef focal fill:#e7f3ef,stroke:#387d6b,color:#153d33,stroke-width:1.2px
    classDef neighbor fill:#f0f3f8,stroke:#8c9bb1,color:#35445b,stroke-width:1px
    classDef app fill:#fff2df,stroke:#c09452,color:#674515,stroke-dasharray:5 3
    classDef system fill:#eaf0fc,stroke:#617fab,color:#263f69,stroke-width:1.2px
    linkStyle default stroke:#7e8fa7,stroke-width:1.2px

Local names omit Assets:: where unambiguous. Explore this diagram and its other views →

The application map includes the worker and dispatch handoff; the engine dependency map shows the caches and retained content behind this small loading path.

Loading stages and results

Stage	Result and owner	What becomes visible
`Loader::prepare()` or `prepare_graphics(indexes)`	An owned `Assets::Loading::Prepared` containing definitions, decoded pixels and shader bytes; CPU work can run on a worker.	No cache entries or native resources. Focused preparation decodes only images referenced by the selected indexes.
`Loader::upload()`	Consumes the prepared value on the active provider/loading owner.	Complete entries publish incrementally; only a successful batch replaces the loader’s submitted-definition snapshots. Failure can leave earlier entries published.
Manager lookup	A retained sprite, tileset, image or shader/material generation.	The selected handle remains the same generation after later cache changes. Validate missing lookups before building game objects.

load_assets(provider) performs preparation and upload synchronously. Use prepare_graphics(indexes) when only selected installed packages are needed. Keep a prepared copy before moving it into upload if retry needs the exact same input. The loading guide owns the failure and shader-replacement rules.

Uses

Consumer	Dependency	Integration boundary
`Loading::Loader` preparation	`Files::FileIndex` from Utilities, manifest readers and image decoding	Discovers paths and owns the CPU inputs before graphics work begins. `FileRegistry` publishes discovered paths; it is separate from the discovery index.
Loader and asset managers	`Rendering::Resources::Provider` from Resources	Upload images/geometry and build compatible materials on the provider owner. Constructing another loader does not create another cache domain.
Loader and cache observation	`Events::EventBus::Publisher` from Events	Optional weak routes report one upload settlement per executed batch and separate committed catalogue changes per key. Observation contracts.

Workers and Dispatch are application composition choices for loading. Loader itself does not submit CPU jobs or platform requests.

Used by

Consumer	Retained input	Responsibility
Application-owned actors and maps	`Assets::Sprites::Asset`, `Assets::Tilesets::Asset`	Keep position, map cells and animation cursors outside shared definitions. Asset values and playback.
Rendering submission	Sprite/tile assets or `Assets::Graphics::Asset`	Resolve selected cells and styles into retained draw packets; resolution does not advance animation.
Loading tools and resource browsers	Prepared definitions, `manifests()` and catalogue snapshots	Inspect CPU metadata and exact-key changes. A successful metadata snapshot is not an atomic view of all caches.

Shared assets, independent playback

Give each moving actor its own Assets::Sprites::Animation while sharing the sprite asset. Advance it during game update, then copy the selected cell into frame preparation. A clip entry index selects an animation entry; that entry’s cell selects atlas geometry. Tile playback similarly wraps shared tileset data in an application-owned cursor.

The playback diagram separates shared content from per-object state. Follow animate a sprite for the complete update and drawing route. Fonts use the separate Text selection/layout path.

Contracts

Preparation changes no global caches or native state. Upload is serialized on the active provider/loading owner. Successful entries can become visible before the whole upload finishes; failure does not imply rollback. Retain a prepared copy before consuming it when retry needs that exact input. Existing keys and explicit shader replacement have different update rules.

An owned loader binds one immutable root, but another loader does not create a second resource domain. The shared caches currently support one active provider/loading-owner domain. Retained definitions and handles remain distinct from a live backend’s ability to use them.

Lifecycle

Create an owned loader for an asset root, prepare CPU input and upload after renderer initialization. Validate retrieved handles before constructing game objects. Release the game’s handles during cleanup; published frames may retain their own copies until recycled. Native resource retirement follows the backend domain, not loader destruction or the last manager lookup.

Execution

CPU preparation may run on workers. Cache publication and resource upload obey provider thread/current-context requirements. Advance animation and select visible state on simulation; frame preparation copies selected cells and styles without changing essential game state.

Integration

On the platform owner during init_platform():

CE::Assets::Loading::Loader loader(asset_root_);
loader.load_assets(engine_.resources());
auto sprite = CE::Assets::Sprites::Manager::get().get_asset("first-game", "actor");

Check sprite and required materials before constructing your player; a lookup can return an empty handle. The loading failure contract explains which earlier entries remain published after an upload error. Keep player position and animation state in the player, not in shared asset metadata. See loading and drawing a sprite.

Limits and further reading

There is no engine-owned map/world or prescribed controller/Character class. Tile selection operates on application-owned map data. Read loading, manifests, asset values and playback, file/font discovery, asset catalog and residency. The Loader header defines preparation/publication entry points.