Files
codecraft/AGENTS.md
Aran Roig fe084e1843
Some checks failed
build / build (push) Failing after 50s
More things editor is now more stable
2026-10-08 14:00:22 +02:00

65 lines
8.0 KiB
Markdown

# AGENTS.md
Codecraft is a Fabric mod (mod id `codecraft`, group `com.aranroig`) that lets players write and run Lua code from an in-game code editor. The Lua runtime is [luajava](https://iroiro.party/luajava/) (`party.iroiro.luajava:luajava` + `luaj`, pure-Java LuaJ, no native libs).
## Commands
- `./gradlew build` — compile and build the mod jar (output in `build/libs/`). This is the only verification available; there are no tests.
- `./gradlew runClient` — launch the dev client with the mod loaded.
- `./gradlew runDatagen` — regenerate data (lang files) into `src/main/generated/`.
- Requires JDK 25. CI (`.github/workflows/build.yml`) builds on ubuntu-24.04 with JDK 25 (Microsoft distribution).
## Fast task-oriented reading
Do not read the whole source tree just to get oriented. Start with the files named in the task, then follow only the callers, callees, and data types needed to understand that change. Use `rg` to find a symbol or payload's other endpoints when needed. Check `git status --short` first and preserve pre-existing user changes; avoid touching unrelated files.
Use this map to find the likely starting point:
- **Editor input, layout, and panes:** `TextEditorScreen`, `EditorScreen`, `Widget`, `EditorTopBar`, `EditorFileTree`, `EditorPaneContainer`, `EditorFileView` under `src/client/java/com/aranroig/client/editor/`.
- **Text editing, completion, and syntax colors:** `EditorFileView`, `LiveDocument`, `EditHistory`, `CompletionProvider`, and `LuaHighlighter` in that same package. For edit networking, follow the corresponding payloads to `DocumentManager`.
- **Project files, collaboration, and persistence:** `Codecraft` registers packet handlers; `DocumentManager` owns live shared documents; `ProjectStore` reads/writes files; `ProjectPath` defines file names; `SavedProjectData` only handles legacy migration. Follow only the subsystem involved in the task.
- **Lua execution and API behavior:** `Codecraft` handles the run request; `ScriptRuntimeManager` owns server-side runtimes and event dispatch; `ScriptRuntime` owns one Lua state; API bindings are in `src/main/java/com/aranroig/wrapper/` and `listeners/`. Read `docs/lua-api.md` first for documented user-facing behavior.
- **In-game Lua documentation and completion libraries:** `docs/lua-api.md` is the human-authored reference; `src/main/resources/data/codecraft/docs/lua-api.json` is the packaged data; `LuaApiDocs`, `DocLibraries`, and `CompletionProvider` load or expose it in the editor. For translation changes, edit `CodecraftEnglishLangProvider`, not generated output.
- **Terminal pane and server shell:** `EditorTerminalPane` and `TerminalEmulator` are client-side; `ShellManager` and `ShellSession` are server-side; shell payloads connect them.
- **Mod setup, versions, and metadata:** `gradle.properties`, `build.gradle`, `src/main/resources/fabric.mod.json`, and the mixin configs. Do not inspect editor code for a build or metadata-only task.
Generated files under `src/main/generated/` should only be inspected when the generated output itself is relevant. Change its provider/input and regenerate it instead of editing it by hand.
## Versions
All versions live in `gradle.properties` (check https://fabricmc.net/develop): Minecraft `26.2`, loader `0.19.3`, loom `1.17-SNAPSHOT`, Fabric API `0.153.0+26.2`. Java release/target is 25. Mod version comes from `mod_version` and is expanded into `fabric.mod.json` at build time — never hardcode the version there.
## Source layout
Loom uses `splitEnvironmentSourceSets()`:
- `src/main/java` — common/server code. Entrypoint `com.aranroig.Codecraft` registers payloads and handles them server-side; Lua execution and its API bindings also run here.
- `src/client/java` — client-only code. Entrypoints `com.aranroig.client.CodecraftClient` (keybind, default `J`, toggles the editor) and `com.aranroig.client.CodecraftDataGenerator` (datagen).
- `src/main/resources` — `fabric.mod.json`, mixins config, assets.
- `src/main/generated` — datagen output (e.g. `assets/codecraft/lang/en_us.json`). Do not hand-edit; add translations in `CodecraftEnglishLangProvider` and run `runDatagen`.
## Architecture
Flow: client editor → custom payloads → server → persisted project.
- **Networking** (`com.aranroig.payloads`): one record per message implementing `CustomPacketPayload` with a static `TYPE` and `StreamCodec`. Serverbound payloads must be registered in `Codecraft.onInitialize()` via `PayloadTypeRegistry.serverboundPlay().register(...)`, and received with `ServerPlayNetworking.registerGlobalReceiver(...)`.
- **Persistence** (`com.aranroig.project.ProjectStore`): the project lives on the server's disk under `config/codecraft/` as plain `.lua` files mirroring the project paths (`lib/gui/theme` → `config/codecraft/lib/gui/theme.lua`), so it can also be edited with external editors — the project is re-read from disk every time the editor opens. Explicit saves write synchronously; keystrokes go to a pending map a daemon thread flushes ~1s after typing settles, and everything pending is flushed on server stop. Names are sanitized (`..` etc. refused) before touching the filesystem. `SavedProjectData` (world `SavedData`) is legacy: kept only to migrate a world's scripts into the config folder once, on `SERVER_STARTED`, when the config folder holds no scripts yet. The project is now per server-install, not per world.
- **Editor UI** (`com.aranroig.client.editor`): custom widgets, not vanilla widgets. `EditorScreen` routes input to hit-tested `Widget`s. `EditorManager` owns editor actions; `EditorFileTree`, `EditorTopBar`, and `EditorPaneContainer` make up the main layout. The pane container manages one or more `EditorFileView`s; edits are tracked per pane and shared through the live-document payloads. See the task-oriented map above before opening more UI classes.
- **Lua runtime**: `EditorManager.run()` sends a `ServerboundRunCodePayload`; `Codecraft` reads the entrypoint from `ProjectStore` and starts a fresh per-player runtime through `ScriptRuntimeManager`. Lua runs on the server thread. `docs/lua-api.md` documents the exposed API; the server bindings live under `src/main/java/com/aranroig/wrapper/` and `listeners/`.
## Conventions
- Use `Codecraft.id(path)` / `Identifier.fromNamespaceAndPath(MOD_ID, path)` for all ids, and the `Codecraft.LOGGER` (slf4j) instead of `System.out.println` for new logging.
- Data classes that cross both persistence and network layers (see `EditorFile`) carry both a Mojang `Codec` and a `StreamCodec`; `RunInfo` currently only has a stream codec.
- A file's name is the **path** it lives at: `lib/gui/theme`, `/`-separated, no extension. `com.aranroig.editor.ProjectPath` is the only thing that reads one; to the server and to the live-document map a name is still an opaque unique key. `EditorFileTree` groups by the folders in those names (folders exist while something is in them, and folding one is client-side view state on `EditorManager`), and `ProjectPath.ENTRYPOINT` (`main`) is what a run executes.
- Records are used for payloads/simple data; match the style of the file you're editing (entrypoint classes from the Fabric template use tabs, editor code uses 4 spaces).
- Translation keys follow `key.codecraft.*` / `key.category.codecraft.*`.
- Mixin configs: `codecraft.mixins.json` (common, package `com.aranroig.mixin`) and `codecraft.client.mixins.json` (client). `ExampleMixin` / `ExampleClientMixin` are template leftovers.
## Status / gotchas
- `EditorManager.stop()` is currently empty. `com.aranroig.editor.Project` remains a stub; file lists are still represented as `List<EditorFile>`.
- Lua execution, event listeners, API bindings, live document collaboration, project loading, persistence, and the terminal shell are implemented. Check the relevant task-map entries before assuming one of these is still a TODO.
- Some TODOs/comments are written in Spanish/Catalan; leave them unless resolving them.
- Minecraft 26.2 uses the newer class/mapping names (`Identifier`, `GuiGraphicsExtractor`, `MouseButtonEvent`, `Component`, etc.) — don't rename them back to older MCP/Yarn-era names.