diff --git a/docs/adrs/README.md b/docs/adrs/README.md index 93d3000..4827beb 100644 --- a/docs/adrs/README.md +++ b/docs/adrs/README.md @@ -13,3 +13,4 @@ Future ADRs can reuse the shape of the existing files when it is useful. - [`adr-0003-current-net-api-state.md`](adr-0003-current-net-api-state.md) - Current net API state. - [`adr-0004-trapos-branding-and-manifest.md`](adr-0004-trapos-branding-and-manifest.md) - TrapOS branding and manifest-driven installs. - [`adr-0005-craftos-pc-harness.md`](adr-0005-craftos-pc-harness.md) - CraftOS-PC as the local harness. +- [`adr-0006-simplify-periphemu-bootstrap.md`](adr-0006-simplify-periphemu-bootstrap.md) - Simplify periphemu bootstrap. diff --git a/docs/adrs/adr-0006-simplify-periphemu-bootstrap.md b/docs/adrs/adr-0006-simplify-periphemu-bootstrap.md new file mode 100644 index 0000000..959295b --- /dev/null +++ b/docs/adrs/adr-0006-simplify-periphemu-bootstrap.md @@ -0,0 +1,47 @@ +# ADR 0006: Simplify `periphemu` Bootstrap + +## Status + +Accepted + +## Date + +2026-06-08 + +## Context + +`startup/servers.lua` historically called `periphemu.create` four times on computer 0: a top modem, two `computer` peers at ids 1 and 2 (both labelled `Trap` in saved per-computer config), and a router peer at id 10. In CraftOS-PC GUI mode this opened **four windows** on every launch (`Computer 0`, two duplicate `Trap`s, and `Router`). + +That setup predates the current workflow: + +- The install path is now manifest-driven (`install.lua` v3.0.0 fetches files listed in `manifest.json` and writes a marker at `/trapos/manifest.json`). The legacy `apis/`, `programs/`, `servers/`, `install.lua` files hand-copied into each per-computer dir are obsolete. +- Local verification runs **headless** through `just test` against scripts in `tests/`; the smokes don't need persistent emulated peers. +- The duplicate `Trap` label and persistent stale computer state across versions caused recurring confusion. + +The CraftOS-PC data directory (`~/Library/Application Support/CraftOS-PC/`) had also accumulated years of stale state in `computer/`, `old_computer/`, and per-id `config/*.json` files (labels like `test`, two `Trap`s, etc.). + +## Decision + +- `startup/servers.lua` attaches **only a top modem** under `periphemu`: + + ```lua + if periphemu then + periphemu.create('top', 'modem'); + end + ``` + +- Extra emulated computers are spawned manually from the CraftOS-PC shell when actually needed (e.g. `periphemu create 10 computer` to bring up a router peer for cross-VM testing). The pattern is documented in [`docs/periphemu.md`](../periphemu.md). +- Wiped the live CraftOS-PC data dir back to a clean slate (one-time, manually). Removed `computer/`, `old_computer/`, and all per-id `config/*.json`. Preserved `config/global.json` (user-level CraftOS-PC settings). A full pre-wipe backup lives at `~/Backups/craftos-pc-2026-06-08/CraftOS-PC/` outside any repo. + +## Consequences + +- `craftos` (GUI) now opens a single unlabelled `Computer 0` window with a top modem attached. No more duplicate `Trap` windows. +- `just test` is unchanged: the headless smokes set up whatever they need per script. +- New contributors and fresh machines get a clean state by default — no inherited per-computer config to chase. +- Cross-machine testing now requires an explicit `periphemu create` call from the shell rather than being implicit on boot. That is a deliberate trade-off: the cost is one extra command when you genuinely need a peer; the benefit is no surprise windows and no persisted ghost VMs. +- The `if periphemu then` guard (called out in CLAUDE.md) is preserved, so in-game behavior is unchanged. + +## Future Work + +- If `tests/` grows a multi-VM scenario, drive peer creation from the test script itself (each `tests/*.lua` already owns its setup) rather than re-adding peers to `startup/servers.lua`. +- Consider a small `programs/spawn-peer.lua` wrapper to make ad-hoc shell incantations friendlier (`spawn-peer 10` instead of `periphemu create 10 computer`). Not done now — premature for current usage. diff --git a/docs/craftos_pc_glossary.md b/docs/craftos_pc_glossary.md index 30b4a54..6093422 100644 --- a/docs/craftos_pc_glossary.md +++ b/docs/craftos_pc_glossary.md @@ -9,7 +9,7 @@ Repo notes: - Use [Install CraftOS-PC](install-craftos-pc.md) for the pinned local setup used by this repository. - Use [Command-Line Flags](https://www.craftos-pc.cc/docs/cli) for `--headless`, `--script`, `--exec`, `--rom`, `--directory`, `--id`, and `--mount-*`. - Use [File System Mounting](https://www.craftos-pc.cc/docs/mounter) for exposing repository files inside CraftOS-PC. -- Use [Peripheral Emulation](https://www.craftos-pc.cc/docs/periphemu) for `periphemu` and local modem/peripheral tests. +- Use [Peripheral Emulation](https://www.craftos-pc.cc/docs/periphemu) for `periphemu` and local modem/peripheral tests. See [`docs/periphemu.md`](periphemu.md) for the in-repo reference and how this repo uses it. - Use [Error Messages](https://www.craftos-pc.cc/docs/error-messages) when `craftos --help` works but booting a computer fails, including `Could not mount ROM`. ## Introduction diff --git a/docs/periphemu.md b/docs/periphemu.md new file mode 100644 index 0000000..5b586e6 --- /dev/null +++ b/docs/periphemu.md @@ -0,0 +1,69 @@ +# `periphemu` — CraftOS-PC Peripheral Emulation + +In-repo reference for the `periphemu` global exposed by [CraftOS-PC](https://www.craftos-pc.cc/). It does **not** exist in CC:Tweaked in-game — always guard usage with `if periphemu then`. + +Upstream: . See also the [CraftOS-PC glossary](craftos_pc_glossary.md) and [ADR-0005](adrs/adr-0005-craftos-pc-harness.md) (why CraftOS-PC is our local harness) and [ADR-0006](adrs/adr-0006-simplify-periphemu-bootstrap.md) (why our startup attaches only a modem). + +## Usage in this repo + +`startup/servers.lua` attaches a single top modem when running under CraftOS-PC: + +```lua +if periphemu then + periphemu.create('top', 'modem'); +end +``` + +That is the only `periphemu` call in the codebase. In-game (`periphemu == nil`) the block is a no-op. Locally a top modem is enough to boot the router, `ping-server`, and clients on the same VM. + +To exercise cross-computer behavior locally, spawn extra peers ad-hoc from the shell: + +``` +periphemu create 10 computer # spawn router VM (id 10) +periphemu create 1 computer # spawn a client VM +``` + +Each call opens a new CraftOS-PC window (GUI mode). Keep this out of `startup/servers.lua` — persistent emulated peers clutter the desktop and leave stale state under `~/Library/Application Support/CraftOS-PC/computer//`. + +## API + +### `periphemu.create(side, type[, arg])` → `boolean` + +Attaches a peripheral. Returns `true` on success, `false` if `side` is already occupied. + +- `side` (string | number) — string for directional sides (`"top"`, `"left"`, …) or arbitrary names (`"modem_4"`); a number to attach a `computer` peripheral by id. +- `type` (string) — see types below. +- `arg` (optional) — type-specific, see table below. + +### `periphemu.remove(side)` → `boolean` + +Detaches the peripheral on `side`. Returns `false` if nothing is attached. + +### `periphemu.names()` → `string[]` + +Returns the list of peripheral type identifiers this CraftOS-PC build accepts as the `type` argument to `create`. + +## Peripheral types + +| Type | Third arg | Notes | +| -------------- | -------------------- | -------------------------------------------------------------------- | +| `modem` | network id (number) | Default network if omitted. Used to isolate modem networks. | +| `computer` | — | `side` is the computer id (number). Spawns a new VM window. | +| `drive` | mount path / `record:` / `treasure:` / `computer:` | Initial mounted disk. | +| `monitor` | — | Size is set via `monitor.setTextScale` after attach. | +| `printer` | output PDF path | Required. Receives printed pages as PDF. | +| `speaker` | — | See caveat below about `playAudio` vs CC:T. | +| `debugger` | — | Attaches the CraftOS-PC debugger; see upstream debugger docs. | +| `debug_adapter`| — | DAP front-end peripheral. | +| `chest` | `true`/`false` | `true` = double chest. Also accepts `minecraft:chest`. | +| `energy` | max energy (number) | Optional further args declare supported energy type strings. | +| `tank` | tank count (number) | Optional further args set tank size and accepted fluid type strings. | + +Call `periphemu.names()` from a CraftOS-PC shell to confirm what the current build supports — the upstream list grows occasionally. + +## Caveats + +- **CC:T has no `periphemu`.** Always guard with `if periphemu then`. CLAUDE.md and [ADR-0005](adrs/adr-0005-craftos-pc-harness.md) treat that guard as mandatory. +- **Speaker `playAudio` differs from CC:T** unless [standards mode](https://www.craftos-pc.cc/docs/standards) is on — CraftOS-PC queues audio without ever returning `false`. +- **Modem network id** segregates emulated networks. Two modems with different ids will not see each other; useful for testing the [router](../programs/router.lua) against a sealed network. +- **Persisted per-computer state** lives at `~/Library/Application Support/CraftOS-PC/computer//` and `config/.json` (labels stored base64-encoded). Spawning a new id leaves that state behind across sessions. diff --git a/startup/servers.lua b/startup/servers.lua index f697966..2d7be70 100644 --- a/startup/servers.lua +++ b/startup/servers.lua @@ -1,4 +1,4 @@ -local _VERSION = '1.2.0' +local _VERSION = '1.3.0' local LOCAL_MANIFEST_PATH = '/trapos/manifest.json'; @@ -18,27 +18,8 @@ end init(); -local periphEmulation = function() - -- attach modem - periphemu.create('top', 'modem'); - - if os.getComputerID() == 0 then - -- attach computers - - os.sleep(0.1) - periphemu.create(1, 'computer'); - - os.sleep(0.1) - periphemu.create(2, 'computer'); - - -- attach router - os.sleep(0.1) - periphemu.create(10, 'computer'); - end -end - if periphemu then - periphEmulation(); + periphemu.create('top', 'modem'); end local function shellFn()