Cartridges

Version: 1.0 (stable baseline) Status: Proposal

1. Objective

Define a minimum and stable contract for Prometeu cartridges, allowing:

App identification
Mode selection (Game/System)
Entrypoint resolution
Predictable loading by the runtime

2. Concept

A cartridge is the distributable unit of Prometeu. It can exist as:

Directory (dev) — ideal for development and hot-reload
Packaged file (.pmc) — ideal for distribution

Both share the same logical layout.

3. Logical Layout

<cartridge>/
 ├── manifest.json
 ├── program.pbc
 └── assets/
     └── ...

Required fields:

manifest.json
program.pbc (Prometeu bytecode)

4. manifest.json (Contract v1)

{
  "magic": "PMTU",
  "cartridge_version": 1,
  "app_id": 1234,
  "title": "My Game",
  "app_version": "1.0.0",
  "app_mode": "Game",
  "entrypoint": "main"
}

Fields

magic: fixed string PMTU
cartridge_version: format version
app_id: unique numerical identifier
title: name of the app
app_version: app version
app_mode: Game or System
entrypoint: symbol or index recognized by the VM

5. Runtime Rules

Validate magic and cartridge_version
Read app_mode to decide execution flow
Resolve entrypoint in program.pbc
Ignore assets/ if not supported yet

6. Usage Modes

Directory (development)

prometeu --run ./mycart/

Packaged file

prometeu --run mygame.pmc

Both must behave identically in the runtime.

7. Contract Stability

From v1 onwards:

manifest.json is the source of truth
Fields can only be added in a backward-compatible manner
Incompatible changes require a new cartridge_version

< Back | Summary | Next >

1.9 KiB Raw Blame History