diff --git a/CLAUDE.md b/CLAUDE.md index 98c6f26..d039e23 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Concise guidance for agents working in this repository. ComputerCraft / CC:Tweaked Lua APIs, servers, and programs for Minecraft 1.21. Code runs in the ComputerCraft sandbox, not standard Lua. -Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and Create integration documentation links. +Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and Create integration documentation links. Use `docs/adrs/README.md` for repository architecture decisions. ## Constraints @@ -18,8 +18,9 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and ## Architecture -- `apis/eventloop.lua` is the single-threaded event loop around `os.pullEventRaw`. -- `apis/net.lua` builds modem packet messaging, routing, and request/response RPC on the event loop. +- `apis/eventloop.lua` is the single-threaded event loop around `os.pullEventRaw`; consider using it everywhere async behavior is needed. A handler that returns `api.STOP` auto-unregisters. +- `apis/net.lua` builds modem packet messaging, routing, and request/response RPC on the event loop. `sendRequest` returns `ok, result, packet` and defaults to a 0.5s timeout. +- A router (`/programs/router.lua`) must be running somewhere on the network; without it, packets lack `routerId`, `isPacketOk` rejects them, and cross-machine messaging silently fails. - `servers/` listen for requests and start loops; `programs/` are clients that send requests and exit. - Well-known channels: `9` ping, `10` router/default routing. Keep duplicated constants in sync. @@ -27,7 +28,7 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and - `startup/servers.lua` starts `/programs`, the shell, and configured servers via `parallel.waitForAll`. - Preserve `periphemu` guards used for CraftOS-PC emulation. -- `install.lua` downloads files listed in `LIST_FILES`; add shipped files there. +- `install.lua` downloads files listed in `LIST_FILES` from `master` by default, or from `next` with `--beta`; add shipped files there. - Add new servers to `startup/servers.lua` as needed. ## Conventions diff --git a/docs/README.md b/docs/README.md index 2236c21..2dba7a5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ Start here when looking up ComputerCraft-related APIs, peripherals, or mod integ - [`cc_glossary.md`](cc_glossary.md) - CC:Tweaked globals, modules, peripherals, events, and guides. - [`advanced_peripherals_glossary.md`](advanced_peripherals_glossary.md) - Advanced Peripherals 0.7 guides, peripherals, turtles, integrations, and changelog pages. - [`create_cc_tweaked_glossary.md`](create_cc_tweaked_glossary.md) - Create CC:Tweaked integration pages. +- [`adrs/`](adrs/) - Lightweight Architecture Decision Records for this repository. ## Notes diff --git a/docs/adrs/README.md b/docs/adrs/README.md new file mode 100644 index 0000000..24ceb58 --- /dev/null +++ b/docs/adrs/README.md @@ -0,0 +1,13 @@ +# Architecture Decision Records + +This directory contains lightweight Architecture Decision Records for this repository. + +The goal is simple: keep a short memory of why we made repo-level choices while building ComputerCraft / CC:Tweaked code for Minecraft. This is not meant to be a heavy process. + +Future ADRs can reuse the shape of the existing files when it is useful. + +## Records + +- [`adr-0001-target-computercraft.md`](adr-0001-target-computercraft.md) - Target ComputerCraft. +- [`adr-0002-use-eventloop-for-async-code.md`](adr-0002-use-eventloop-for-async-code.md) - Use eventloop for async code. +- [`adr-0003-current-net-api-state.md`](adr-0003-current-net-api-state.md) - Current net API state. diff --git a/docs/adrs/adr-0001-target-computercraft.md b/docs/adrs/adr-0001-target-computercraft.md new file mode 100644 index 0000000..fbbb457 --- /dev/null +++ b/docs/adrs/adr-0001-target-computercraft.md @@ -0,0 +1,28 @@ +# ADR 0001: Target ComputerCraft + +## Status + +Accepted + +## Date + +2026-06-07 + +## Context + +This repository exists to build APIs, servers, and programs for ComputerCraft / CC:Tweaked inside Minecraft. + +The code is Lua, but the runtime is not generic local Lua. The real environment provides ComputerCraft APIs such as `os.pullEvent`, `peripheral`, modems, timers, labels, computer IDs, and the CraftOS filesystem. + +## Decision + +This repo targets ComputerCraft / CC:Tweaked first. + +Local Lua compatibility is not a goal by itself. Code can assume the ComputerCraft runtime and use ComputerCraft conventions when they make the in-game code clearer. + +## Consequences + +- Prefer ComputerCraft-style absolute `require` paths, such as `require('/apis/net')()` (most API modules return factories — call the result once to get the API). +- Local checks are useful, but runtime behavior should be validated in-game or with CraftOS-PC when needed. +- Avoid adding a local Lua harness unless there is a clear reason. +- Keep the repository practical: this is for playing Minecraft, not designing a general Lua framework. diff --git a/docs/adrs/adr-0002-use-eventloop-for-async-code.md b/docs/adrs/adr-0002-use-eventloop-for-async-code.md new file mode 100644 index 0000000..631fdf2 --- /dev/null +++ b/docs/adrs/adr-0002-use-eventloop-for-async-code.md @@ -0,0 +1,28 @@ +# ADR 0002: Use Eventloop For Async Code + +## Status + +Accepted + +## Date + +2026-06-07 + +## Context + +ComputerCraft is event-driven. Direct `os.pullEvent` loops are easy to write, but they are hard to compose when multiple things need to happen at the same time. + +This matters for servers, network listeners, timers, peripheral events, and future UI code. UI code especially will need to handle input, redraws, network replies, and timers together. + +## Decision + +New async code should use `/apis/eventloop`. + +Event handlers, timers, server listeners, and future UI behavior should compose through the event loop instead of each feature owning its own blocking event loop. + +## Consequences + +- Prefer `eventloop.register`, `setTimeout`, `onStart`, `onStop`, and `startLoop` for async behavior. +- APIs that listen for events should accept an existing event loop as a constructor argument, the way `/apis/net` already takes one. Do not create a private loop inside a module. +- Direct `os.pullEvent` loops should be rare and justified. +- Existing code can stay as-is for now, but future async, server, and UI code should move toward eventloop composition. diff --git a/docs/adrs/adr-0003-current-net-api-state.md b/docs/adrs/adr-0003-current-net-api-state.md new file mode 100644 index 0000000..9a76a8a --- /dev/null +++ b/docs/adrs/adr-0003-current-net-api-state.md @@ -0,0 +1,36 @@ +# ADR 0003: Current Net API State + +## Status + +Accepted + +## Date + +2026-06-07 + +## Context + +`/apis/net` is the current networking abstraction in this repository. + +It wraps modem messages with packet metadata and uses `/apis/eventloop` for listeners and request/response flows. It is useful for today's basic routed messages and RPC-like requests, but it is not a final protocol design. + +## Decision + +Keep using `/apis/net` for simple program and server messaging. + +Document the current behavior as the baseline, without over-designing the future protocol before real needs appear. + +## Current State + +- Default routing channel is `10`. +- Ping channel is `9`. +- Packets include `sourceId`, `sourceLabel`, `routerId`, `destId`, and `message`. +- Main convenience APIs include `send`, `listen`, `sendRequest`, `sendMultipleRequests`, `listenRequest`, `createEvent`, `createRequest`, and `openChannel` (alias `open`). Listening on a non-default channel requires `openChannel` first. +- `sendRequest` and `sendMultipleRequests` run a private event loop, default to a `0.5s` timeout, and return `ok, result, packet` (or `ok, results, packets` for the multi variant). +- Router behavior currently lives separately in `/programs/router.lua`. A router must be running on the network — otherwise non-router senders produce packets with `routerId = nil` and `isPacketOk` drops them on receive, so cross-machine messages silently fail. + +## Consequences + +- Use `/apis/net` for current basic messaging needs. +- Keep duplicated well-known channel constants in sync while they remain duplicated. +- Future ADRs can replace or refine this one if the network protocol gains discovery, retries, schemas, versioning, auth, or a different routing model.