docs(periphemu): simplify bootstrap
This commit is contained in:
parent
2a89244733
commit
a127a7693e
@ -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.
|
||||
|
||||
47
docs/adrs/adr-0006-simplify-periphemu-bootstrap.md
Normal file
47
docs/adrs/adr-0006-simplify-periphemu-bootstrap.md
Normal file
@ -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.
|
||||
@ -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
|
||||
|
||||
69
docs/periphemu.md
Normal file
69
docs/periphemu.md
Normal file
@ -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: <https://www.craftos-pc.cc/docs/periphemu>. 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/<id>/`.
|
||||
|
||||
## 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:<id>` | 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/<id>/` and `config/<id>.json` (labels stored base64-encoded). Spawning a new id leaves that state behind across sessions.
|
||||
@ -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()
|
||||
|
||||
Loading…
Reference in New Issue
Block a user