diff --git a/README.md b/README.md index 374dd2d..75e7f3d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,10 @@ # 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](https://fabricmc.net/) 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. ```lua for y = 64, 67 do @@ -9,12 +12,90 @@ for y = 64, 67 do end ``` -The API is documented in [docs/lua-api.md](docs/lua-api.md). +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. -## Setup +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. -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. +## 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`](gradle.properties). + +## Building from source + +Requires JDK 25. + +```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 -This template is available under the CC0 license. Feel free to learn from it and incorporate it in your own projects. +Distributed under the CC0-1.0 license (see [LICENSE](LICENSE)). The project builds on the +[Fabric example mod](https://github.com/FabricMC/fabric-example-mod) template, which is +also CC0.