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