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

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