This commit is contained in:
123
docs/lua-api.md
123
docs/lua-api.md
@@ -32,6 +32,22 @@ without the decimal, concatenate them into a string:
|
||||
print("blocks placed: " .. 12) -- -> blocks placed: 12
|
||||
```
|
||||
|
||||
## run(command)
|
||||
|
||||
Runs a Minecraft command from the server command source, with full server permissions
|
||||
and no player position or entity. The command may be written with or without a leading
|
||||
slash. The function returns `true` when the command is submitted, or `false` and a
|
||||
reason when the argument is invalid. A `true` result means the command was submitted;
|
||||
it does not guarantee the command succeeded.
|
||||
|
||||
```lua
|
||||
run("time set day")
|
||||
run("weather clear")
|
||||
```
|
||||
|
||||
For commands that need a player or coordinates, use explicit selectors and coordinates
|
||||
in the command string. The command source is the server, not the player running Lua.
|
||||
|
||||
## Blocks
|
||||
|
||||
Coordinates are **absolute world coordinates** — never relative to the player — in the
|
||||
@@ -43,6 +59,11 @@ use them in the script.
|
||||
| `world.set_block(x, y, z, block)` | `true`, or `false` and a reason |
|
||||
| `world.remove_block(x, y, z[, drops])` | `true`, or `false` and a reason |
|
||||
| `world.get_block(x, y, z)` | block id string, or `nil` and a reason |
|
||||
| `world.get_dimension()` | dimension id |
|
||||
| `world.get_time()` / `world.set_time(ticks)` | world clock time in ticks |
|
||||
| `world.get_weather()` / `world.set_weather(weather[, ticks])` | `clear`, `rain` or `thunder` |
|
||||
| `world.get_biome(x, y, z)` | biome id, or `nil` and a reason |
|
||||
| `world.players()` | array of online player names |
|
||||
|
||||
### world.set_block(x, y, z, block)
|
||||
|
||||
@@ -92,6 +113,106 @@ if block ~= "minecraft:air" then
|
||||
end
|
||||
```
|
||||
|
||||
## Entities
|
||||
|
||||
Entity ids returned by `entities.nearby` and `entities.spawn` are UUID strings. The
|
||||
nearby query only checks loaded entities in the executing player's current dimension;
|
||||
it excludes the script owner, its radius defaults to 16 blocks and is capped at 128.
|
||||
Entity positions are absolute.
|
||||
|
||||
| Function | Purpose |
|
||||
| -------- | ------- |
|
||||
| `entities.nearby([radius[, type]])` | UUIDs of nearby entities, optionally filtered by type id |
|
||||
| `entities.spawn(type, x, y, z)` | Spawn a summonable entity and return its UUID |
|
||||
| `entities.get(uuid)` | Return type id, x, y, z and custom/display name |
|
||||
| `entities.teleport(uuid, x, y, z)` | Move an entity in its current dimension |
|
||||
| `entities.remove(uuid)` | Remove an entity (players are protected) |
|
||||
| `entities.set_name(uuid, name)` | Set a visible custom name |
|
||||
| `entities.set_health(uuid, health)` | Set living entity health up to its maximum |
|
||||
|
||||
```lua
|
||||
local ids = entities.nearby(12, "minecraft:zombie")
|
||||
for _, id in ipairs(ids) do
|
||||
local type, x, y, z, name = entities.get(id)
|
||||
print(name .. " is at " .. x .. ", " .. y .. ", " .. z)
|
||||
end
|
||||
```
|
||||
|
||||
## Scoreboards
|
||||
|
||||
Scoreboard helpers operate on the server scoreboard. Objective names follow vanilla's
|
||||
1–16 character limit. `create_objective` defaults to the `dummy` criterion; built-in
|
||||
criteria such as `deathCount` and `health` are also accepted. `display` accepts `list`,
|
||||
`sidebar` or `below_name`.
|
||||
|
||||
| Function | Purpose |
|
||||
| -------- | ------- |
|
||||
| `scoreboard.create_objective(name[, criterion[, display_name]])` | Create an objective |
|
||||
| `scoreboard.remove_objective(name)` | Remove an objective |
|
||||
| `scoreboard.set(player, objective, value)` | Set a score |
|
||||
| `scoreboard.add(player, objective, value)` | Add to a score |
|
||||
| `scoreboard.get(player, objective)` | Read a score (`nil` when unset) |
|
||||
| `scoreboard.reset(player[, objective])` | Clear one score or all of a player's scores |
|
||||
| `scoreboard.display(objective, slot)` | Show an objective in a display slot |
|
||||
|
||||
```lua
|
||||
scoreboard.create_objective("coins", "dummy", "Coins")
|
||||
scoreboard.add("Alex", "coins", 5)
|
||||
scoreboard.display("coins", "sidebar")
|
||||
```
|
||||
|
||||
## HUD and boss bars
|
||||
|
||||
Titles, subtitles and action-bar messages go to the player who ran the script by default;
|
||||
pass an online player name to target someone else. Title timings are measured in ticks
|
||||
(20 ticks per second). Boss bars are saved server-side, identified by a resource id; ids
|
||||
without a namespace use `codecraft:`. A new boss bar is shown to the script owner by
|
||||
default. `bossbar_visible` can add or remove any online player.
|
||||
|
||||
| Function | Purpose |
|
||||
| -------- | ------- |
|
||||
| `hud.title(text)` / `hud.subtitle(text)` | Show a title or subtitle |
|
||||
| `hud.action_bar(text)` | Show text above the hotbar |
|
||||
| `hud.title_times(fade_in, stay, fade_out)` | Set title timings in ticks |
|
||||
| `hud.clear_titles([reset])` | Clear title and subtitle |
|
||||
| `hud.bossbar_add(id, name[, max])` | Create a boss bar (max defaults to 100) |
|
||||
| `hud.bossbar_remove(id)` | Remove a boss bar |
|
||||
| `hud.bossbar_value(id, value)` / `hud.bossbar_max(id, value)` | Change boss bar progress |
|
||||
| `hud.bossbar_visible(id, visible)` | Show or hide it for the script owner |
|
||||
|
||||
```lua
|
||||
hud.title_times(10, 60, 20)
|
||||
hud.title("Welcome!")
|
||||
hud.action_bar("You have " .. scoreboard.get("Alex", "coins") .. " coins")
|
||||
hud.bossbar_add("round", "Round progress", 10)
|
||||
hud.bossbar_value("round", 3)
|
||||
```
|
||||
|
||||
## Items and inventories
|
||||
|
||||
Item ids can omit the `minecraft:` namespace. Inventory slots are indexed from 0 to 35
|
||||
in the player's main inventory. The optional player argument names an online player;
|
||||
when omitted, the script owner is used. Excess items from `items.give` drop at the
|
||||
target player's feet. `items.clear` and `items.count` only affect the main inventory.
|
||||
|
||||
| Function | Purpose |
|
||||
| -------- | ------- |
|
||||
| `items.give(item, count[, player])` | Give items; overflow drops at the player |
|
||||
| `items.count(item[, player])` | Count matching items in the main inventory |
|
||||
| `items.clear(item[, player])` | Remove matching items; also returns the removed count |
|
||||
| `items.get_slot(slot[, player])` | Read an inventory slot (item id and count, or `nil`) |
|
||||
| `items.set_slot(slot, item, count[, player])` | Replace a slot; count 0 clears it |
|
||||
|
||||
```lua
|
||||
items.give("gold_ingot", 8)
|
||||
print("You now have " .. items.count("minecraft:gold_ingot"))
|
||||
items.set_slot(0, "minecraft:diamond_sword", 1)
|
||||
```
|
||||
|
||||
All mutating helpers return `true` on success or `false` and a reason on invalid input
|
||||
or missing targets. Read helpers return their value, or `nil` and a reason when lookup
|
||||
fails.
|
||||
|
||||
## Events
|
||||
|
||||
Listeners let a script react to the game *after* it has finished running. Register one
|
||||
@@ -125,7 +246,7 @@ the event:
|
||||
cheap: they run twenty times a second, and a slow one lags the whole server.
|
||||
|
||||
Callbacks run on the server thread and have the same powers as the script that
|
||||
registered them — they can call `print` and the `world` functions. An error inside a
|
||||
registered them — they can call `print` and the Minecraft API tables. An error inside a
|
||||
callback is printed to the owner's chat; it never stops the game or the other
|
||||
listeners.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user