Files
codecraft/AGENTS.md
Aran Roig 5897870725
Some checks failed
build / build (push) Failing after 1m37s
Shell and folders
2026-10-07 19:13:25 +02:00

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 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 EditorFiles 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 Widgets by hit-testing (inside()) and z-index; scrolling goes to the widget under the mouse. EditorManager owns the widgets and editor actions (save/run/etc.); EditorFileTree, EditorTopBar, EditorPaneContainer are the three panels. EditorPaneContainer tiles the editing area into one or more EditorFileView panes (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. EditorFileView is the actual text editor; LuaHighlighter tokenizes lines into colored Spans 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.
  • 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

  • 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.