From ce2c7e5ba917f8842ead020526c52578c720d6c1 Mon Sep 17 00:00:00 2001 From: Gitea OpenCode Agent Date: Tue, 13 Oct 2026 18:02:46 +0000 Subject: [PATCH] Fix issue #14: Update README.md --- README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 163 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 374dd2d..fbd7bf8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,45 @@ # codecraft -Players write Lua in the in-game editor (`J` by default) and run it on the server. -Scripts can place and remove blocks through the `world` table: +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](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: + +```lua +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`: ```lua for y = 64, 67 do @@ -9,12 +47,132 @@ for y = 64, 67 do end ``` -The API is documented in [docs/lua-api.md](docs/lua-api.md). +## More examples + +**Hollow out a small stone-brick room** — walls, floor and ceiling, empty inside: + +```lua +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: + +```lua +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: + +```lua +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: + +```lua +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: + +```lua +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](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 -For setup instructions, please see the [Fabric Documentation page](https://docs.fabricmc.net/develop/getting-started/creating-a-project#setting-up) related to the IDE that you are using. +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](https://docs.fabricmc.net/develop/getting-started/creating-a-project#setting-up) +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. +This template is available under the CC0 license. Feel free to learn from it and +incorporate it in your own projects.