< [Back](chapter-14.md) | [Summary](table-of-contents.md) | [Next](chapter-16.md) > # Asset Management ## Bank-Centric Hardware Asset Model **Scope:** Runtime / Hardware Asset Management (SDK-agnostic) --- ## 1. Fundamental Principles 1. **Every asset in Prometeu resides in a Bank** 2. **A Bank is a hardware memory management system** 3. **Assets are cold binaries stored in the cartridge** 4. **Asset memory belongs to the console, not to the VM** 5. **Loading, residency, and eviction are explicit** 6. **Hardware does not interpret gameplay semantics** 7. **The SDK orchestrates policies; hardware executes contracts** > In Prometeu, you do not load “data”. You load **residency**. --- ## 2. Asset Origin (Cold Storage) * All assets initially reside in **cold storage** inside the cartridge. * Typically, each asset corresponds to a binary file. * The runtime **never scans the cartridge directly**. * All access goes through the **Asset Table**. --- ## 3. Asset Table The Asset Table is an index loaded at cartridge boot. It describes **content**, not residency. ### Location * The Asset Table **must be embedded as JSON inside `manifest.json`**. * Tooling may compile this JSON into a binary table for runtime use, but the source of truth is the manifest. ### Required Fields (conceptual) * `asset_id` (integer, internal identifier) * `asset_name` (string, user-facing identifier) * `asset_type` (TILEBANK, SOUNDBANK, BLOB, TILEMAP, ...) * `bank_kind` (mandatory, single) * `offset` (byte offset in cartridge) * `size` (cold size) * `decoded_size` (resident size) * `codec` (RAW, LZ4, ZSTD, ...) * `asset_metadata` (type-specific) > `bank_kind` defines **where** an asset may reside in hardware. --- ## 4. Bank — Definition > **A Bank is the residency and swapping mechanism of the Prometeu hardware.** A Bank: * owns **numbered slots** * enforces **resident memory budgets** * enforces **staging / inflight budgets** * accepts only compatible assets * supports **atomic swap via commit** * exposes memory and residency metrics Banks are hardware infrastructure, not assets. --- ## 5. BankKind Each Bank belongs to a **BankKind**, defining its pipeline and constraints. ### Example BankKinds * `GFX_TILEBANK` * `AUDIO_SOUNDBANK` * `DATA_BLOBBANK` * `MAP_TILEMAPBANK` Each BankKind defines: * slot count * maximum resident memory * inflight / staging memory budget * decode and validation pipeline * hardware consumer subsystem (renderer, audio mixer, etc.) --- ## 6. Slots and Slot References * Each BankKind owns a fixed set of **slots**. * A slot: * references a resident asset (or is empty) * never stores data directly * may expose a **generation counter** (debug) ### Slot Reference Slots are always referenced with explicit BankKind context: * `gfxSlot(3)` * `audioSlot(1)` * `blobSlot(7)` This prevents cross-bank ambiguity. --- ## 7. Bank Memory Model * Bank memory is **console-owned memory**. * It does not belong to the VM heap. * It does not participate in GC. * It can be fully released when the cartridge shuts down. Each Bank manages: * total memory * used memory * free memory * inflight (staging) memory Conceptually, each Bank is a **specialized allocator**. --- ## 8. Unified Loader ### Conceptual API ```text handle = asset.load(asset_name, slotRef, flags) ``` Load flow: 1. Resolve `asset_name` via Asset Table to get its `asset_id` 2. Read `bank_kind` from asset entry 3. Validate compatibility with `slotRef` 4. Enqueue load request 5. Perform IO + decode on worker 6. Produce materialized asset in staging ### Handle States * `PENDING` — enqueued * `LOADING` — IO/decode in progress * `READY` — staging completed * `COMMITTED` — installed into slot * `CANCELED` * `ERROR` --- ## 9. Commit ```text asset.commit(handle) ``` * Commit is **explicit** and **atomic** * Executed at a safe frame boundary * Performs **pointer swap** in the target slot * Previous asset is released if no longer referenced The hardware **never swaps slots automatically**. --- ## 10. Asset Deduplication * A decoded asset exists **at most once per BankKind**. * Multiple slots may reference the same resident asset. * Redundant loads become **install-only** operations. Memory duplication is forbidden by contract. --- ## 11. Bank Specializations ### 11.1 GFX_TILEBANK * AssetType: TILEBANK * Immutable graphical tile + palette structure * Consumed by the graphics subsystem ### 11.2 AUDIO_SOUNDBANK * AssetType: SOUNDBANK * Resident audio samples or streams * Consumed by the audio mixer ### 11.3 DATA_BLOBBANK * AssetType: BLOB * Read-only byte buffers * Hardware does not interpret contents Used by the SDK via: * **Views** (zero-copy, read-only) * **Decode** (materialization into VM heap) --- ## 12. Views and Decode (SDK Contract) * **View** * read-only * zero-copy * valid only while the blob remains resident * **Decode** * allocates VM-owned entities * independent from the Bank after creation Hardware is unaware of Views and Decode semantics. --- ## 13. Manifest and Initial Load * The cartridge may include a `manifest.json`. * The manifest may declare: * assets to preload * target slot references These loads occur **before the first frame**. --- ## 14. Shutdown and Eviction * On cartridge shutdown: * all Banks are cleared * all resident memory is released No implicit persistence exists. --- ## 15. Debugger and Telemetry Each Bank must expose: * total memory * used memory * free memory * inflight memory * occupied slots * `asset_id` per slot * `asset_name` per slot * generation per slot This enables debuggers to visualize: * memory stacks per Bank * memory pressure * streaming strategies --- ## 16. Minimal Syscall API (Derived) The following syscalls form the minimal hardware contract for asset management: ```text asset.load(asset_name, slotRef, flags) -> handle asset.status(handle) -> LoadStatus asset.commit(handle) asset.cancel(handle) bank.info(bank_kind) -> BankStats bank.slot_info(slotRef) -> SlotStats ``` Where: * `LoadStatus` ∈ { PENDING, LOADING, READY, COMMITTED, CANCELED, ERROR } * `BankStats` exposes memory usage and limits * `SlotStats` exposes current asset_id, asset_name and generation --- ## 17. Separation of Responsibilities ### Hardware (Prometeu) * manages memory * loads bytes * decodes assets * swaps pointers * reports usage ### SDK * defines packs, scenes, and policies * interprets blobs * creates VM entities ### VM * executes logic * manages its own heap * never owns hardware assets --- ## 18. Golden Rule > **Banks are the foundation of the hardware.** > **Asset Types describe content.** > **The SDK orchestrates; the hardware executes.** < [Back](chapter-14.md) | [Summary](table-of-contents.md) | [Next](chapter-16.md) >