From d676a33365a17de0eb38b3bc09ee877bb24c2805 Mon Sep 17 00:00:00 2001 From: Guillaume ARM Date: Sun, 7 Jun 2026 21:16:03 +0200 Subject: [PATCH] docs: add create integration glossary --- CLAUDE.md | 75 ++++++++++-------------------- docs/README.md | 15 ++++++ docs/create_cc_tweaked_glossary.md | 36 ++++++++++++++ 3 files changed, 75 insertions(+), 51 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/create_cc_tweaked_glossary.md diff --git a/CLAUDE.md b/CLAUDE.md index 130e6c1..98c6f26 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,67 +1,40 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Concise guidance for agents working in this repository. -## What this is +## Project -A collection of [ComputerCraft](https://tweaked.cc/) (CC:Tweaked) Lua APIs, servers, and programs for in-game networked computers. Targets **CC:Tweaked for Minecraft 1.21** (latest). Runtime is the ComputerCraft Lua sandbox (`fs`, `peripheral`, `os.pullEvent`, `shell`, `parallel`, `modem.transmit`, etc.), not standard Lua. +ComputerCraft / CC:Tweaked Lua APIs, servers, and programs for Minecraft 1.21. Code runs in the ComputerCraft sandbox, not standard Lua. -When more CC:Tweaked API details are needed, is a useful documentation entrypoint. It is not mandatory to fetch every time, but its left-hand navigation includes the broader glossary and links to globals, modules (for example `cc.base64` and `cc.pretty`), peripherals, and events, even when the topic is not turtle-specific. A compact local index of these documentation pages is maintained in `docs/cc_glossary.md`. +Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and Create integration documentation links. -## Tooling constraints +## Constraints -- **There is no way to run, build, or test this code yet.** It only executes inside ComputerCraft (in-game or under CraftOS-PC). Do not attempt to run Lua locally or add a test harness unless asked. -- **Linting:** `just check` runs `luacheck` over all Lua source. **Always run `just check` after editing a Lua file, and fix any warnings before considering the change done.** Config lives in `.luacheckrc` (a custom `lua51+cc` std that knows the ComputerCraft sandbox globals and the `os`/`table` extensions). If a new genuine global is needed, add it there rather than suppressing the warning inline. -- Match the existing style (2-space indent, semicolons, `local function`). -- `require` paths are ComputerCraft-resolved and absolute from the computer root, e.g. `require('/apis/net')`. Most modules return a *factory* function — call it once to get the API: `local net = require('/apis/net')()`. +- Do not run Lua locally or add a test harness unless asked; code executes in-game or CraftOS-PC. +- 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 -Three layers, bottom-up: +- `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. +- `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. -1. **`apis/eventloop.lua`** — the foundation. A single-threaded event loop wrapping `os.pullEventRaw`. `register(eventName, handler)` returns a disposer; handlers returning `api.STOP` auto-unregister. Also provides `setTimeout`/clearTimeout, `onStart`/`onStop`, and `runLoop`. The loop auto-stops when no handlers/timeouts remain (unless `runLoop(true)`). Mutations during dispatch are queued (`unregisterQueue`, `removeTimeoutQueue`, `timeoutFactories`) and flushed after, so handlers can safely (un)register. +## Boot And Install -2. **`apis/net.lua`** — messaging built on the event loop. Sends typed packets over modems. Key concepts: - - **Packet** = `{ sourceId, sourceLabel, routerId, destId, message }`. `destId` may be a numeric computer ID, a string label, or `nil` (broadcast). - - **Routing**: messages go out on `DEFAULT_ROUTING_CHANNEL` (10) to be picked up by a router, *unless* the sender is itself a router (`_G.isRouterEnabled`). **A router must be running somewhere on the network for net-based programs to reach other machines.** - - **Request/response**: `sendRequest`/`listenRequest` implement RPC — the responder replies on `eventType .. "_response"`. `sendRequest` spins up a *private* event loop + net instance, waits up to `timeoutInSec` (default 0.5s), and returns `ok, result, packet`. `sendMultipleRequests` collects replies from many machines until timeout. - - Higher-level helpers: `createRequest(channel, eventType)` and `createEvent(channel, eventType)`. - -3. **`servers/`** and **`programs/`** — concrete uses of `net`. Servers `listenRequest` and call `net.startLoop()`; programs (clients) fire `sendRequest`/`sendMultipleRequests` and exit. - -### Channels (well-known ports) - -- `9` — ping -- `10` — router / default routing channel - -These are duplicated as local constants across files; keep them in sync when changing. - -## Boot flow - -`startup/servers.lua` is the entry point on each machine: it adds `/programs` to `shell.path`, then `parallel.waitForAll` runs an interactive shell alongside every server in `SERVERS`. When all stop, it reboots. - -## CraftOS-PC emulation - -`startup/servers.lua` detects the `periphemu` global and, when present, creates an emulated modem plus (on computer 0) a few emulated peer/router computers. Preserve these guards. - -## Installation / distribution - -`install.lua` is fetched and run on a machine via `wget run /install.lua`. It deletes old paths, re-downloads every file in `LIST_FILES` from the `master` branch raw GitHub URL by default, or from `next` when run with `--beta`, and runs `startup/servers.lua`. **When adding a new file that ships to machines, add it to `LIST_FILES` in `install.lua`** (and to `SERVERS` in `startup/servers.lua` if it's a server). +- `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. +- Add new servers to `startup/servers.lua` as needed. ## Conventions -- Each module starts with `local _VERSION = '...'`; bump it when changing that module's behavior. -- Programs accept `-version`/`--version` and `-help`/`--help` (and `-silent`/`--silent` for the router) via vararg `...`. -- French comments appear throughout — fine to add either language, match the surrounding file. +- 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`. -### Commit messages - -Commit messages roughly follow Angular-style conventional commits, but the convention is intentionally lightweight. Use either `topic(scope): description` or `topic: description`. - -- Common topics include `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, and `revert`. -- Keep the description short, lowercase, imperative, and without a trailing period. -- The exact topic/scope matters less than making the commit easy to scan. - -## Development setup - -See `DEVELOPMENT.md` for local development requirements and setup steps. +See `DEVELOPMENT.md` for local setup. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2236c21 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +# Documentation + +Start here when looking up ComputerCraft-related APIs, peripherals, or mod integrations used by this repository. + +## Indexes + +- [`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. + +## Notes + +- These files are compact navigation indexes, not full documentation mirrors. +- Prefer the local indexes first, then open the linked upstream docs for details. +- Update the relevant `Last checked` line when refreshing an index. diff --git a/docs/create_cc_tweaked_glossary.md b/docs/create_cc_tweaked_glossary.md new file mode 100644 index 0000000..a599d4c --- /dev/null +++ b/docs/create_cc_tweaked_glossary.md @@ -0,0 +1,36 @@ +# Create CC:Tweaked Integration Documentation Glossary + +Compact index of Create's CC:Tweaked integration documentation pages from . The sidebar HTML on that page exposes the broader ComputerCraft integration navigation. + +Last checked: 2026-06-07. + +## Logistics + +- [Packager](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/packager) +- [Re-Packager](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/repackager) +- [Stock Ticker](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/stock-ticker) +- [Redstone Requester](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/redstone-requester) +- [Table Cloth](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/table-cloth) +- [Package Frogport](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/package-frogport) +- [Postbox](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/postbox) +- [Package Object](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/package-object) +- [Order Data Object](https://wiki.createmod.net/users/cc-tweaked-integration/logistics/order-data-object) + +## Trains + +- [Train Station](https://wiki.createmod.net/users/cc-tweaked-integration/train/train-station) +- [Train Signal](https://wiki.createmod.net/users/cc-tweaked-integration/train/train-signal) +- [Train Observer](https://wiki.createmod.net/users/cc-tweaked-integration/train/train-observer) +- [Train Schedule](https://wiki.createmod.net/users/cc-tweaked-integration/train/train-schedule) +- [Libraries](https://wiki.createmod.net/users/cc-tweaked-integration/train/libraries) + +## Peripherals + +- [Nixie Tube](https://wiki.createmod.net/users/cc-tweaked-integration/nixie-tube) +- [Display Link](https://wiki.createmod.net/users/cc-tweaked-integration/display-link) +- [Sticker](https://wiki.createmod.net/users/cc-tweaked-integration/sticker) +- [Sequenced Gearshift](https://wiki.createmod.net/users/cc-tweaked-integration/sequenced-gearshift) +- [Rotational Speed Controller](https://wiki.createmod.net/users/cc-tweaked-integration/rotational-speed-controller) +- [Creative Motor](https://wiki.createmod.net/users/cc-tweaked-integration/creative-motor) +- [Speedometer](https://wiki.createmod.net/users/cc-tweaked-integration/speedometer) +- [Stressometer](https://wiki.createmod.net/users/cc-tweaked-integration/stressometer)