329 lines
6.5 KiB
Markdown
329 lines
6.5 KiB
Markdown
< [Back](chapter-14.md) | [Summary](table-of-contents.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` (string or hash)
|
|
* `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_id, slotRef, flags)
|
|
```
|
|
|
|
Load flow:
|
|
|
|
1. Resolve `asset_id` via Asset Table
|
|
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
|
|
* 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_id, 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 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) > |