Files
codecraft/AGENTS.md
2026-10-06 17:59:26 +02:00

47 lines
4.6 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).
## 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, handles them server-side). Lua execution belongs here eventually.
- `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** (`SavedProjectData`): a `SavedData` stored in the overworld (`saved_project_data`). Holds the list of `EditorFile`s that make up the user's project.
- **Editor UI** (`com.aranroig.client.editor`): a custom immediate-mode-ish GUI system, not vanilla widgets. `EditorScreen` routes key/mouse input to `Widget`s by hit-testing (`inside()`) and z-index. `EditorManager` owns the widgets and editor actions (save/run/etc.); `EditorFileTree`, `EditorTopBar`, `EditorFileView` are the three panels. `EditorFileView` is the actual text editor; `LuaHighlighter` tokenizes lines into colored `Span`s and `CompletionProvider` handles autocomplete.
- **Lua runtime**: `EditorManager.run()` sends a `ServerboundRunCodePayload` with the entrypoint name; the server handler in `Codecraft.java` is a TODO (currently just prints). Example of embedding: `Lua l = new LuaJ(); l.register("print", Logger.print()); l.run(code);` — `com.aranroig.client.wrapper.Logger` adapts a `LuaFunction` to print into the player chat. Decide carefully whether Lua runs client- or server-side; server-side is the apparent direction.
## 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.
- 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
- Work in progress: `EditorManager.newFile/undo/redo/stop` are empty stubs, server-side code execution is unimplemented, `com.aranroig.editor.Project` is a stub that is meant to replace the raw `List<EditorFile>` usage, and `EditorManager.files` is never populated (loading files from the server is an open TODO; `toggleVisible()` will NPE on `files.getFirst()`).
- 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.