4.5 KiB
codecraft
A Fabric mod for Minecraft that lets players write and run
Lua from an in-game code editor. Press J (default, rebindable under
Options → Controls → Codecraft) to open the editor, write a script, and hit
Run Script: the code runs on the server and can change the world through a small
scripting API.
for y = 64, 67 do
world.set_block(10, y, -3, "minecraft:cobblestone")
end
Scripts are plain files in a project that lives on the server, so your work is a folder
of .lua files you can version, diff and edit outside the game — and several players can
type in the same file at the same time.
The full API reference lives in docs/lua-api.md, and it is browsable in-game from Help → Lua API Documentation or with F1 on a function while editing.
Features
In-game editor — a custom editor screen with multiple panes (split horizontally or vertically), a file tree with folders, Lua syntax highlighting, autocompletion with snippets, find and replace, undo/redo, and selectable colour themes.
Server-side Lua — every script runs on the server thread, so its effects are authoritative for everyone in the world and the same script behaves the same wherever it is written. A script can also keep listening after it finishes, reacting to item use, broken blocks, chat, joins, leaves and every server tick. There are no permission or reach checks, so this is for players you already trust.
A project on disk — the project lives in config/codecraft/ as plain .lua files
mirroring the paths shown in the file tree (lib/gui/theme →
config/codecraft/lib/gui/theme.lua). Explicit saves write through at once; keystrokes
are flushed a beat after typing settles, and everything is read back fresh when the
editor opens, so external edits are picked up too.
Real-time collaboration — the server is the single authority on every open document. Keystrokes are broadcast and rebased between players, so editing the same file together does not lose anyone's work, and each file shows who else is in it.
Terminal — the editor has a terminal pane attached to a shell on the machine the server runs on.
Note: that terminal hands out a real shell to anyone who can open the editor. It is meant for single-player games and servers among friends, not for a public server.
The Lua API
Scripts get a small, documented set of tables for touching the game:
| Table | What it does |
|---|---|
print(...), run(command) |
Message the player's chat, run a server command |
world |
Set, remove and read blocks, plus dimension, time, weather, biome and the online player list |
entities |
Find, spawn, inspect, teleport, rename and heal entities |
items |
Give, count, clear and edit inventory slots |
scoreboard |
Objectives, scores and display slots |
hud |
Titles, action-bar messages and boss bars |
events |
Listen for item use, broken blocks, chat, joins, leaves and ticks |
The file called main is the entrypoint — Run Script executes it, replacing the
previous run and its listeners. The runtime is LuaJ (Lua 5.1) with only the base library
loaded, and scripts run to completion on the server thread, so keep loops reasonable.
Requirements
- Minecraft 26.2
- Fabric Loader 0.19.3 or newer, with Fabric API
- Java 25 or newer
Versions are pinned in gradle.properties.
Building from source
Requires JDK 25.
./gradlew build # compile and build the mod jar into build/libs/
./gradlew runClient # launch a dev client with the mod loaded
./gradlew runDatagen # regenerate data (lang files) into src/main/generated/
Loom uses split source sets: src/main/java holds the common/server code (payload
handlers, the project store, the Lua runtime and its API bindings) and src/client/java
holds the client code (keybind, editor UI, datagen). Flow is client editor → custom
payloads → server → persisted project.
src/main/generated/ is datagen output — change its provider (for translations,
CodecraftEnglishLangProvider) and regenerate it instead of editing it by hand.
For setting up a development workspace in your IDE, see the Fabric documentation.
License
Distributed under the CC0-1.0 license (see LICENSE). The project builds on the Fabric example mod template, which is also CC0.