8.0 KiB
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 (party.iroiro.luajava:luajava + luaj, pure-Java LuaJ, no native libs).
Commands
./gradlew build— compile and build the mod jar (output inbuild/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) intosrc/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,EditorFileViewundersrc/client/java/com/aranroig/client/editor/. - Text editing, completion, and syntax colors:
EditorFileView,LiveDocument,EditHistory,CompletionProvider, andLuaHighlighterin that same package. For edit networking, follow the corresponding payloads toDocumentManager. - Project files, collaboration, and persistence:
Codecraftregisters packet handlers;DocumentManagerowns live shared documents;ProjectStorereads/writes files;ProjectPathdefines file names;SavedProjectDataonly handles legacy migration. Follow only the subsystem involved in the task. - Lua execution and API behavior:
Codecrafthandles the run request;ScriptRuntimeManagerowns server-side runtimes and event dispatch;ScriptRuntimeowns one Lua state; API bindings are insrc/main/java/com/aranroig/wrapper/andlisteners/. Readdocs/lua-api.mdfirst for documented user-facing behavior. - In-game Lua documentation and completion libraries:
docs/lua-api.mdis the human-authored reference;src/main/resources/data/codecraft/docs/lua-api.jsonis the packaged data;LuaApiDocs,DocLibraries, andCompletionProviderload or expose it in the editor. For translation changes, editCodecraftEnglishLangProvider, not generated output. - Terminal pane and server shell:
EditorTerminalPaneandTerminalEmulatorare client-side;ShellManagerandShellSessionare 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. Entrypointcom.aranroig.Codecraftregisters payloads and handles them server-side; Lua execution and its API bindings also run here.src/client/java— client-only code. Entrypointscom.aranroig.client.CodecraftClient(keybind, defaultJ, toggles the editor) andcom.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 inCodecraftEnglishLangProviderand runrunDatagen.
Architecture
Flow: client editor → custom payloads → server → persisted project.
- Networking (
com.aranroig.payloads): one record per message implementingCustomPacketPayloadwith a staticTYPEandStreamCodec. Serverbound payloads must be registered inCodecraft.onInitialize()viaPayloadTypeRegistry.serverboundPlay().register(...), and received withServerPlayNetworking.registerGlobalReceiver(...). - Persistence (
com.aranroig.project.ProjectStore): the project lives on the server's disk underconfig/codecraft/as plain.luafiles 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(worldSavedData) is legacy: kept only to migrate a world's scripts into the config folder once, onSERVER_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.EditorScreenroutes input to hit-testedWidgets.EditorManagerowns editor actions;EditorFileTree,EditorTopBar, andEditorPaneContainermake up the main layout. The pane container manages one or moreEditorFileViews; 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 aServerboundRunCodePayload;Codecraftreads the entrypoint fromProjectStoreand starts a fresh per-player runtime throughScriptRuntimeManager. Lua runs on the server thread.docs/lua-api.mddocuments the exposed API; the server bindings live undersrc/main/java/com/aranroig/wrapper/andlisteners/.
Conventions
- Use
Codecraft.id(path)/Identifier.fromNamespaceAndPath(MOD_ID, path)for all ids, and theCodecraft.LOGGER(slf4j) instead ofSystem.out.printlnfor new logging. - Data classes that cross both persistence and network layers (see
EditorFile) carry both a MojangCodecand aStreamCodec;RunInfocurrently only has a stream codec. - A file's name is the path it lives at:
lib/gui/theme,/-separated, no extension.com.aranroig.editor.ProjectPathis the only thing that reads one; to the server and to the live-document map a name is still an opaque unique key.EditorFileTreegroups by the folders in those names (folders exist while something is in them, and folding one is client-side view state onEditorManager), andProjectPath.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, packagecom.aranroig.mixin) andcodecraft.client.mixins.json(client).ExampleMixin/ExampleClientMixinare template leftovers.
Status / gotchas
EditorManager.stop()is currently empty.com.aranroig.editor.Projectremains a stub; file lists are still represented asList<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.