Gitea OpenCode Agent ce2c7e5ba9
Some checks failed
build / build (pull_request) Failing after 50s
build / build (push) Failing after 55s
Fix issue #14: Update README.md
2026-10-13 18:02:46 +00:00
2026-07-12 17:00:44 +02:00
2026-07-12 17:00:44 +02:00
2026-10-08 14:00:22 +02:00
2026-07-12 17:00:44 +02:00
2026-07-12 17:00:44 +02:00
2026-10-08 01:54:02 +02:00
2026-07-12 17:00:44 +02:00
2026-10-06 17:59:21 +02:00
2026-07-12 17:00:44 +02:00
2026-07-12 17:00:44 +02:00
2026-10-13 18:02:46 +00:00
2026-07-12 17:00:44 +02:00

codecraft

A Fabric mod for Minecraft that turns the game into a scripting playground. Press J (rebindable under Options → Controls → Codecraft) to open a full in-game code editor — tabs, splits, file tree, syntax highlighting, autocomplete, find and replace, themes — write Lua, and run it on the server.

Scripts can build and clear terrain, spawn and move entities, give items, drive scoreboards and HUD elements, run server commands, and keep listening to the game after they finish through event listeners.

How it works

  • The editor is a custom client-side UI. Files live in a server-side project: lib/gui/theme is a file, folders exist while something is in them, and main is the entrypoint that Run Script executes.
  • The project is stored on the server under config/codecraft/ as plain .lua files mirroring those paths, so you can edit it with your normal editor too. It is re-read from disk every time the editor opens. Saves write immediately; keystrokes are flushed about a second after typing settles.
  • Collaboration is built in: several players editing the same file see each other's edits and cursors live.
  • Execution happens server-side. A script runs start to finish on the server thread, so everything it does happens at once — a loop that places millions of blocks freezes the server.
  • A terminal pane docks a real interactive shell on the server next to your code.
  • Documentation is available in-game: Help → Lua API Documentation, or press F1 on a function while editing. The full reference also lives in docs/lua-api.md.

Your first script

Open the editor with J, put this in main and press Run Script. print writes to the chat of the player who ran the script:

print("hello, player!")

Coordinates are absolute world coordinates in the dimension the running player stands in — press F3 to read your own. This raises a four-block cobblestone pillar at x = 10, z = -3:

for y = 64, 67 do
    world.set_block(10, y, -3, "minecraft:cobblestone")
end

More examples

Hollow out a small stone-brick room — walls, floor and ceiling, empty inside:

local x, y, z = 10, 64, -3        -- corner of the build
local width, height, depth = 7, 4, 7

for dx = 0, width - 1 do
    for dy = 0, height - 1 do
        for dz = 0, depth - 1 do
            local shell = dx == 0 or dx == width - 1
                    or dy == 0 or dy == height - 1
                    or dz == 0 or dz == depth - 1
            local px, py, pz = x + dx, y + dy, z + dz
            if shell then
                world.set_block(px, py, pz, "minecraft:stone_bricks")
            else
                world.remove_block(px, py, pz)
            end
        end
    end
end

Keep listening after the script finishes. Listeners registered with events.* run whenever the event happens, with the same powers as the script that registered them. Pressing Run Script again drops the old listeners and starts clean:

events.on_player_join(function(player)
    print(player .. " joined the world")
end)

events.on_break_block(function(player, x, y, z, block)
    if block == "minecraft:diamond_ore" then
        print(player .. " struck diamond at " .. x .. ", " .. y .. ", " .. z)
    end
end)

A tiny coin economy on the scoreboard, with a sidebar and an action-bar readout:

scoreboard.create_objective("coins", "dummy", "Coins")

events.on_break_block(function(player, x, y, z, block)
    if block == "minecraft:gold_ore" then
        scoreboard.add(player, "coins", 1)
        hud.action_bar(player .. " has " .. scoreboard.get(player, "coins") .. " coins")
    end
end)

scoreboard.display("coins", "sidebar")
hud.title("Welcome!")
hud.subtitle("Break gold ore to earn coins")

Check the world around you and copy a block from one place to another:

for _, name in ipairs(world.players()) do
    print("online: " .. name)
end

local block = world.get_block(10, 64, -3)
if block and block ~= "minecraft:air" then
    world.set_block(20, 70, 5, block)
end

Mutating helpers return true on success, or false and a reason; read helpers return their value, or nil and a reason. Printing the reason is the quickest way to find out why a script misbehaves:

local ok, reason = world.set_block(10, 64, -3, "minecraft:stone")
if not ok then
    print("could not place the block: " .. reason)
end

API at a glance

Table What it does
print(...) Writes to the running player's chat
run(command) Runs a command as the server
world Blocks, dimension, time, weather, biomes, players
entities Find, spawn, move, rename and heal entities
items Give, count, clear and edit inventory slots
scoreboard Objectives and scores
hud Titles, action bar, boss bars
events Listen to items, blocks, chat, joins, leaves, ticks

Everything is documented — signatures, return values, failure reasons and more examples — in docs/lua-api.md.

Limits worth knowing

  • The runtime is LuaJ (Lua 5.1) with only the base library: tostring, pairs, pcall and friends work, but math, string, table and coroutine do not.
  • Only main is executed; code in the other project files is not loaded, so require does not find them yet.
  • Only loaded chunks can be read or edited, and block entity data (chest contents, sign text) is not exposed.
  • There are no permission or reach checks: a script can change any loaded block and run commands with server permissions. Scripts stop when their owner disconnects, but keep an eye on what you let people run.

Requirements

Minecraft 26.2 with Fabric Loader >=0.19.3, Fabric API, and Java 25.

Setup

Build the mod jar with ./gradlew build; the output lands in build/libs/. ./gradlew runClient launches a development client with the mod loaded, and ./gradlew runDatagen regenerates data (language files) into src/main/generated/.

For development environment instructions, please see the Fabric Documentation page related to the IDE that you are using.

License

This template is available under the CC0 license. Feel free to learn from it and incorporate it in your own projects.

Description
Fabric mod for coding inside Minecraft
Readme CC0-1.0 486 KiB
Languages
Java 100%