70 lines
4.3 KiB
Markdown
70 lines
4.3 KiB
Markdown
# `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-and-probes.md) (why CraftOS-PC is our local harness, and 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`. [AGENTS.md](./../AGENTS.md) and [ADR-0005](adrs/adr-0005-craftos-pc-harness-and-probes.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.
|