5.5 KiB
5.5 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).
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.Codecraft(registers payloads, handles them server-side). Lua execution belongs here eventually.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 (
SavedProjectData): aSavedDatastored in the overworld (saved_project_data). Holds the list ofEditorFiles that make up the user's project. - Editor UI (
com.aranroig.client.editor): a custom immediate-mode-ish GUI system, not vanilla widgets.EditorScreenroutes key/mouse input toWidgets by hit-testing (inside()) and z-index; scrolling goes to the widget under the mouse.EditorManagerowns the widgets and editor actions (save/run/etc.);EditorFileTree,EditorTopBar,EditorPaneContainerare the three panels.EditorPaneContainertiles the editing area into one or moreEditorFileViewpanes (split right/below from the pane headers, the View menu, or Ctrl+\ / Ctrl+Shift+), each header naming its file; the sashes between panes drag to resize them, and the "active pane" (last pane clicked) is where files from the tree open and where saving applies.EditorFileViewis the actual text editor;LuaHighlightertokenizes lines into coloredSpans andCompletionProviderhandles autocomplete. - Lua runtime:
EditorManager.run()sends aServerboundRunCodePayloadwith the entrypoint name; the server handler inCodecraft.javais a TODO (currently just prints). Example of embedding:Lua l = new LuaJ(); l.register("print", Logger.print()); l.run(code);—com.aranroig.client.wrapper.Loggeradapts aLuaFunctionto 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 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
- Work in progress:
EditorManager.newFile/undo/redo/stopare empty stubs, server-side code execution is unimplemented,com.aranroig.editor.Projectis a stub that is meant to replace the rawList<EditorFile>usage, andEditorManager.filesis never populated (loading files from the server is an open TODO;toggleVisible()will NPE onfiles.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.