112 lines
2.5 KiB
Markdown
112 lines
2.5 KiB
Markdown
# Cartridges
|
|
|
|
Domain: cartridge package
|
|
Function: normative
|
|
|
|
This chapter defines the cartridge contract consumed by the current runtime.
|
|
|
|
## 1 Scope
|
|
|
|
A cartridge is the distributable unit loaded by firmware/runtime.
|
|
|
|
In the current implementation, the supported dev/runtime form is a directory containing:
|
|
|
|
- `manifest.json`
|
|
- `program.pbx`
|
|
- optional `assets.pa`
|
|
|
|
The loader also recognizes `.pmc` as a future packaged form, but packaged cartridge loading is not implemented yet.
|
|
|
|
## 2 Cartridge Metadata
|
|
|
|
The runtime currently expects the following manifest fields:
|
|
|
|
```json
|
|
{
|
|
"magic": "PMTU",
|
|
"cartridge_version": 1,
|
|
"app_id": 1234,
|
|
"title": "My Game",
|
|
"app_version": "1.0.0",
|
|
"app_mode": "Game",
|
|
"entrypoint": "main"
|
|
}
|
|
```
|
|
|
|
Additional manifest-supported fields include:
|
|
|
|
- `capabilities`
|
|
- `asset_table`
|
|
- `preload`
|
|
|
|
## 3 Required Fields
|
|
|
|
Current required manifest fields:
|
|
|
|
- `magic`
|
|
- `cartridge_version`
|
|
- `app_id`
|
|
- `title`
|
|
- `app_version`
|
|
- `app_mode`
|
|
- `entrypoint`
|
|
|
|
Current required file payloads:
|
|
|
|
- `program.pbx`
|
|
|
|
Optional file payloads:
|
|
|
|
- `assets.pa`
|
|
|
|
## 4 Runtime Validation Rules
|
|
|
|
The current loader validates:
|
|
|
|
- `magic == "PMTU"`
|
|
- `cartridge_version == 1`
|
|
- manifest parse validity
|
|
- capability normalization
|
|
- presence of `program.pbx`
|
|
|
|
If validation fails, cartridge loading is rejected before execution.
|
|
|
|
## 5 App Mode and Entrypoint
|
|
|
|
`app_mode` controls firmware launch behavior:
|
|
|
|
- `Game`
|
|
- `System`
|
|
|
|
`entrypoint` is passed to the VM initialization flow and may be resolved as a symbol or function identifier according to the VM/runtime contract.
|
|
|
|
## 6 Assets and Preload
|
|
|
|
If present, the manifest may provide:
|
|
|
|
- `asset_table`: runtime asset descriptors;
|
|
- `preload`: initial residency requests.
|
|
|
|
If `assets.pa` exists, its bytes become the cartridge asset payload used by the asset manager during cartridge initialization.
|
|
|
|
## 7 Runtime Forms
|
|
|
|
### Directory form
|
|
|
|
This is the working runtime/dev form used by the current loader.
|
|
|
|
### Packaged `.pmc` form
|
|
|
|
This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
|
|
|
|
The cartridge spec therefore distinguishes:
|
|
|
|
- supported current load form;
|
|
- reserved future distribution form.
|
|
|
|
## 8 Relationship to Other Specs
|
|
|
|
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines how firmware consumes cartridge metadata.
|
|
- [`14-boot-profiles.md`](14-boot-profiles.md) defines cartridge selection at boot.
|
|
- [`15-asset-management.md`](15-asset-management.md) defines asset table and residency semantics.
|