47 lines
3.5 KiB
Markdown
47 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
Concise guidance for agents working in this repository.
|
|
|
|
## Project
|
|
|
|
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, CraftOS-PC, Advanced Peripherals, and Create integration documentation links. Use `docs/adrs/README.md` for repository architecture decisions.
|
|
|
|
## Constraints
|
|
|
|
- Do not add a standalone Lua test harness unless asked. Local execution happens through the CraftOS-PC harness (see `docs/install-craftos-pc.md`, `docs/craftos_pc_glossary.md`, and ADR-0005); code otherwise executes in-game.
|
|
- Do not run `just repl` as an LLM agent; it is a human-only interactive CraftOS-PC wrapper. Use `just craftos --headless ...` for automated probes.
|
|
- When changing behavior, add as many useful CraftOS-PC tests as practical. It is acceptable to skip tests that require human-only validation, such as complex turtle motion, in-game UX feel, or visual approval, but still add unit-style non-regression tests for deterministic parts when possible.
|
|
- Use `/apis/libtest.lua` for test scripts under `tests/`; `/programs/runtest.lua` prints `__TRAPOS_TEST_OK__` only after the suite passes.
|
|
- `libtest` cancels each case after `3`s (`--timeout <s>` / `--no-timeout` to override); never commit a hanging test to `tests/`. Slow harness fixtures go in `tests/harness/` behind dedicated recipes. See `docs/adrs/adr-0009-layered-test-timeouts.md`.
|
|
- After editing Lua, run `just check` and fix all `luacheck` warnings.
|
|
- Use 2-space indent, semicolons, and `local function`.
|
|
- `require` paths are absolute ComputerCraft paths, for example `require('/apis/net')()`.
|
|
- Most API modules return factories; call the required module once before use.
|
|
|
|
## Architecture
|
|
|
|
- `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/libtest.lua` is the lightweight test helper used by scripts under `tests/`; `/programs/runtest.lua` discovers tests, renders suite output, and owns the `__TRAPOS_TEST_OK__` success marker.
|
|
- `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.
|
|
|
|
## Boot And Install
|
|
|
|
- `startup/servers.lua` starts `/programs`, the shell, and configured servers via `parallel.waitForAll`.
|
|
- Preserve `periphemu` guards used for CraftOS-PC emulation; see `docs/craftos_pc_glossary.md` for upstream emulator references.
|
|
- `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
|
|
|
|
- Bump `local _VERSION = '...'` when changing module behavior.
|
|
- Programs support `-version`/`--version` and `-help`/`--help`; router also supports `-silent`/`--silent`.
|
|
- French or English comments are fine; match surrounding code.
|
|
- Commit messages use lightweight conventional style: `topic(scope): description` or `topic: description`.
|
|
|
|
See `DEVELOPMENT.md` for local setup.
|