cc-libs/.plans/archived/tror-helloworld-plan.md

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 <Code>:<Meta>;<Payload> (e.g. TW write, TC cursor, EV event).
• 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:

[ 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.