prometeu-runtime/docs/specs/hardware/topics/chapter-15.md

< Back | Summary | Next >

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

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

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:

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 | Summary | Next >