2 Commits

Author SHA1 Message Date
Gitea OpenCode Agent
af64e9140c Respond to issue #16 comments
Some checks failed
build / build (pull_request) Failing after 58s
build / build (push) Failing after 1m5s
2026-10-13 18:23:57 +00:00
Gitea OpenCode Agent
7fa45c8f49 Fix issue #16: Update README.md
Some checks failed
build / build (push) Has been cancelled
build / build (pull_request) Failing after 56s
2026-10-13 18:21:12 +00:00

316
README.md
View File

@@ -1,45 +1,10 @@
# codecraft # codecraft
A Fabric mod for Minecraft that turns the game into a scripting playground. Press A [Fabric](https://fabricmc.net/) mod for Minecraft that lets players write and run
**`J`** (rebindable under *Options → Controls → Codecraft*) to open a full in-game Lua from an in-game code editor. Press `J` (default, rebindable under
code editor — tabs, splits, file tree, syntax highlighting, autocomplete, find and *Options → Controls → Codecraft*) to open the editor, write a script, and hit
replace, themes — write Lua, and run it **on the server**. **Run Script**: the code runs **on the server** and can change the world through a small
scripting API.
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 ```lua
for y = 64, 67 do for y = 64, 67 do
@@ -47,132 +12,193 @@ for y = 64, 67 do
end end
``` ```
## More examples 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.
**Hollow out a small stone-brick room** — walls, floor and ceiling, empty inside: The full API reference lives in [docs/lua-api.md](docs/lua-api.md), and it is browsable
in-game from **Help → Lua API Documentation** or with **F1** on a function while editing.
```lua ## Features
local x, y, z = 10, 64, -3 -- corner of the build
local width, height, depth = 7, 4, 7
for dx = 0, width - 1 do **In-game editor** — a custom editor screen with multiple panes (split horizontally or
for dy = 0, height - 1 do vertically), a file tree with folders, Lua syntax highlighting, autocompletion with
for dz = 0, depth - 1 do snippets, find and replace, undo/redo, and selectable colour themes.
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.*` **Server-side Lua** — every script runs on the server thread, so its effects are
run whenever the event happens, with the same powers as the script that registered authoritative for everyone in the world and the same script behaves the same wherever it
them. Pressing **Run Script** again drops the old listeners and starts clean: 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.
```lua **A project on disk** — the project lives in `config/codecraft/` as plain `.lua` files
events.on_player_join(function(player) mirroring the paths shown in the file tree (`lib/gui/theme` →
print(player .. " joined the world") `config/codecraft/lib/gui/theme.lua`). Explicit saves write through at once; keystrokes
end) are flushed a beat after typing settles, and everything is read back fresh when the
editor opens, so external edits are picked up too.
events.on_break_block(function(player, x, y, z, block) **Real-time collaboration** — the server is the single authority on every open document.
if block == "minecraft:diamond_ore" then Keystrokes are broadcast and rebased between players, so editing the same file together
print(player .. " struck diamond at " .. x .. ", " .. y .. ", " .. z) does not lose anyone's work, and each file shows who else is in it.
end
end)
```
**A tiny coin economy** on the scoreboard, with a sidebar and an action-bar readout: **Terminal** — the editor has a terminal pane attached to a shell on the machine the
server runs on.
```lua > **Note:** that terminal hands out a real shell to anyone who can open the editor. It is
scoreboard.create_objective("coins", "dummy", "Coins") > meant for single-player games and servers among friends, not for a public server.
events.on_break_block(function(player, x, y, z, block) ## The Lua API
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") Scripts get a small, documented set of tables for touching the game:
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 | | Table | What it does |
| ----- | ------------ | | ----- | ------------ |
| `print(...)` | Writes to the running player's chat | | `print(...)`, `run(command)` | Message the player's chat, run a server command |
| `run(command)` | Runs a command as the server | | `world` | Set, remove and read blocks, plus dimension, time, weather, biome and the online player list |
| `world` | Blocks, dimension, time, weather, biomes, players | | `entities` | Find, spawn, inspect, teleport, rename and heal entities |
| `entities` | Find, spawn, move, rename and heal entities |
| `items` | Give, count, clear and edit inventory slots | | `items` | Give, count, clear and edit inventory slots |
| `scoreboard` | Objectives and scores | | `scoreboard` | Objectives, scores and display slots |
| `hud` | Titles, action bar, boss bars | | `hud` | Titles, action-bar messages and boss bars |
| `events` | Listen to items, blocks, chat, joins, leaves, ticks | | `events` | Listen for item use, broken blocks, chat, joins, leaves and ticks |
Everything is documented — signatures, return values, failure reasons and more The file called `main` is the entrypoint — **Run Script** executes it, replacing the
examples — in [docs/lua-api.md](docs/lua-api.md). 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.
## 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 ## Requirements
Minecraft `26.2` with Fabric Loader `>=0.19.3`, Fabric API, and Java `25`. - Minecraft **26.2**
- Fabric Loader **0.19.3** or newer, with **Fabric API**
- Java **25** or newer
## Setup Versions are pinned in [`gradle.properties`](gradle.properties).
Build the mod jar with `./gradlew build`; the output lands in `build/libs/`. ## Building from source
`./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 Requires JDK 25.
page](https://docs.fabricmc.net/develop/getting-started/creating-a-project#setting-up)
related to the IDE that you are using. ```sh
./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](https://docs.fabricmc.net/develop/getting-started/creating-a-project#setting-up).
## License ## License
This template is available under the CC0 license. Feel free to learn from it and Distributed under the CC0-1.0 license (see [LICENSE](LICENSE)). The project builds on the
incorporate it in your own projects. [Fabric example mod](https://github.com/FabricMC/fabric-example-mod) template, which is
also CC0.
```snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
snickers
```