diff --git a/.plans/tror-helloworld-plan.md b/.plans/tror-helloworld-plan.md new file mode 100644 index 0000000..16b8b0b --- /dev/null +++ b/.plans/tror-helloworld-plan.md @@ -0,0 +1,55 @@ +# TRoR Hello World POC Plan + +## Goal + +Build a small proof-of-concept that drives an in-game ComputerCraft computer (on an ATM10 server) from a local CraftOS-PC instance using TRoR (Terminal Redirection over Rednet). + +The POC is intentionally minimal: see "Hello World" printed by an in-game computer rendered locally, and have a local keystroke produce a CC event in-game. + +## Background + +- `craftos --tror` enables the TRoR renderer but only reads/writes packets over **stdio** — it does not speak real rednet. See `docs/craftos_pc_glossary.md`. +- TRoR is a ComputerCraft standard (oeed/CraftOS-Standards #10): packet format `:;` (e.g. `TW` write, `TC` cursor, `EV` event). +- [`lyqyd/cc-netshell`](https://github.com/lyqyd/cc-netshell) already implements a TRoR server/client over rednet inside CC. We piggyback on it instead of reimplementing the protocol. + +## Architecture + +Three actors: + +```text +[ local craftos --tror ] <-- stdio --> [ ws bridge ] <-- ws --> [ in-game relay CC ] <-- rednet --> [ in-game target CC ] +``` + +1. **Target CC** (in-game): runs `cc-netshell` server, prints "Hello World", reads `key`/`char` events. +2. **Relay CC** (in-game): has wireless modem + uses `http.websocket` to bridge TRoR packets between rednet and an external WS endpoint. +3. **WS bridge** (host): tiny Node/Python WS server that also pipes stdio to/from `craftos --tror`. Could be a single script that spawns `craftos` as a child process. + +Why a relay: CC has no raw TCP socket; the only off-world transport is `http`/`websocket`. The ATM10 server must allow outbound HTTP/WS to our host (default CC:Tweaked config does). + +## Milestones + +1. **In-game baseline**: install `cc-netshell` on two test computers (creative world / single-player first), confirm server/client TRoR shell works over rednet alone. +2. **WS bridge skeleton**: minimal local WS server that logs frames. Verify a CC computer can connect via `http.websocket` and exchange text frames. +3. **Relay program**: in-game program that joins the WS server and forwards every WS frame as a rednet message to a configured target ID, and vice versa. Treat frames as opaque TRoR packets. +4. **Local TRoR client**: spawn `craftos --tror`, pipe its stdout to the WS bridge, pipe WS frames to its stdin. A "Hello World" written by the target CC should render in CraftOS-PC. +5. **Input loopback**: confirm keystrokes typed in local CraftOS-PC reach the target as `key`/`char` events (TRoR `EV` packets). +6. **ATM10 deployment**: copy the relay + target programs to the real server, point relay at the public host running the WS bridge. + +## Open Questions + +- Does `cc-netshell`'s wire format match the on-the-wire TRoR packet format byte-for-byte, or does it wrap packets in a rednet envelope? If wrapped, the relay must unwrap before forwarding to the WS bridge (and rewrap on the way back). +- ATM10 default CC:Tweaked config: is outbound WS to arbitrary hosts allowed? May need a whitelist entry in `computercraft-server.toml`. +- Auth: any pairing/handshake between local client and target CC, or do we rely on "obscure WS URL" for the POC? +- One target only, or do we want the relay to multiplex by target ID from day one? + +## Out Of Scope + +- Multi-user, auth, TLS hardening. +- Reconnect logic beyond "restart both ends". +- Packaging into this repo's `programs/` / `servers/` layout — that comes after the POC proves the loop works. + +## Deliverables + +- `programs/tror-relay.lua` (in-game relay, prototype quality). +- `tools/tror-bridge/` (host-side WS + craftos spawner script, language TBD). +- Notes appended to `docs/craftos_pc_glossary.md` once the stdio contract is verified.