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

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 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 Widgets. EditorManager owns editor actions; EditorFileTree, EditorTopBar, and EditorPaneContainer make up the main layout. The pane container manages one or more EditorFileViews; 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.