Reference

What one kind of ask has cost this pack, and what every kind has together. An ask is a question the engine puts to a pack with a deadline on it; an answer that does not arrive in time is not used.

What the engine's questions with a deadline have cost this pack, in total and per kind: `citadel.budget().asks`.

A boss bar, from `ui.bossbar` for the room or `player.ui.bossbar` for one player; title, progress and colour are live.

A boss bar's colour is its own closed set — six the client draws, and anything else is white. It is not an `Ink`: the bar has no hex form.

How a display turns toward the viewer: "fixed" never turns, "vertical" turns about the up axis, "horizontal" tips up and down, "center" does both.

What a pack changes about the vanilla biome its own biome copies. Each colour is a `Color` or a colour name such as "#7fd8c8".

The biomes a pack adds to the game.

One block the game version has, in its own numbers, from `game.block(name)`: hardness, light, fire and material.

What `game.blocks.amend` takes: **hooks only**. Every tnt in every world already looks like tnt and is as hard as tnt, so a data column here is refused by name. For a block of your own with different numbers, `game.blocks.define { extends = "tnt" }`.

The block a hook was called about. Reads are fields and acts are methods. The reads are **live** — the world as it is right now — and everything that changes the world is carried out by the engine the moment the hook returns, in the order it was asked for.

The handle `define` hands back. Equality is identity — two handles are the same block when they name the same block.

One block, or one of a list chosen by a field: `floor(by)` counts through the list and starts again at its end.

A block, as anything that takes one will take it.

`game.blocks`: defines a pack's own blocks and amends the game's own, at load time.

What a definition says a block *is*. Every hook takes `base` as its **last** argument: call it and you extended what is under you, leave it out and you replaced it. `base` is a decision rather than a reentrant call — its effects land when your hook returns, and calling it twice happens once.

Whatever is standing on one. `kind` is `"mob"` for a cow or a zombie.

Degrees: 0 yaw faces south, 90 west; positive pitch tips down. Constructors default missing angles to zero; later writes preserve them.

What took a block out, and with what.

What a pack's tick and event callbacks are allowed per tick, together, and what it did with it. Milliseconds throughout.

What `world.build` hands the function it is given. Coordinates are whole blocks of the build's own and may be negative; later writes win.

FixedCamera | EntityCamera | FreeCamera | OrbitCamera | ChaseCamera

A picture of one or more maps with no frame of its own, from `world.canvas`, for a frame display, a hand or a screen.

A 16 by 16 column of blocks, handed to `world.on_generate`, `world.on_populate` and a room's `generate` to fill.

typeof(setmetatable({} :: ColorFields, {} ::

Every colour's name: Minecraft's sixteen, which every client has had since 1.7, six more, and "transparent". `colors` holds the same names.

A command a pack added, from `commands.add`; change its suggestions or `cancel` it.

The options of `commands.add`: a permission node, aliases, the /help line and suggestions per argument.

Adds a room's slash commands from a usage line: the `commands` global, or `room.commands`.

An event subscription or repeating timer; task functions return threads.

A chest's stacks: `world.container(pos)`. A chest a player has open is theirs until it closes — `take` takes nothing, `put` puts nothing.

How an item display is posed; a read gives back the same words.

A hit on a player, before it lands: what `players.on_damage` hands a pack.

An attached JSON record/list, with tracked nested writes and generalized iteration. Runtime userdata: use data.copy for ordinary table operations. Roots use string keys; nested lists use contiguous indices starting at 1. Assignment validates the entire value. Hook views expire after their callback batch finishes.

An open dialog, from `player.ui.dialog`.

A node of a dialog, made by `ui.kit`: a table with a `kind`.

An item, text, block or frame shown in the world, from `world.display`; its place, rotation, scale and look are live.

What a broken block leaves. "table" is whatever the site that broke it would have left — the version's drop table for a player's hands, a roll for a blast, nothing at all for a fire — and "none" is nothing, which is what a pack block leaves unless it says otherwise.

Shared durable stores. Calls yield; pcall catches structured errors such as {err = "conflict", version = 3}. One store per experience.

How a tween moves over its duration: "linear" (the default) at one speed, "in" starts slow, "out" ends slow, "in_out" both, "bounce" bounces at the end.

A function called for every letter each frame a text shows, handing back how that letter looks; `i` of `n` is the letter's place, `t` is `time.now()`.

`game.entities`: the three verbs over one shape.

A pack's hooks on one of the game's own entities. Hooks only: every pig already looks like a pig, so the data columns are refused by name.

What `define{}` hands back. Usable anywhere the name is, so an author rarely types the namespace at all.

A body the world moves: a pack's own entity, a mob, a stack on the ground. Every read is a fresh look at the world, so a handle to something that has died reads `nil`. Inside a hook the same handle reads the entity as it was at the top of the tick, and its writes land at that hook's own slot.

One kind the game version has, in its own numbers, from `game.entities.<kind>`: name, size, max_health, speed and drop. A kind that is not a mob (an arrow, a boat, primed TNT; `mob == false`) has `name`, `mob`, `width`, `height` and `physics` only: every other fact is nil for it, and a write to `spawn`, `attacks` or `interact` and a call of `amend` are errors.

A kind of entity a pack makes up. `base` is the last argument of every hook: call it and you extended, don't and you replaced.

One of a block's six faces: up, down, north, south, west or east, as `hit.face` and `world.raycast` report it.

A block's faces: one picture, or `all`, `side`, `top`, `bottom`, `front`, `back`, or a face by name.

One of the four sides: north, south, west or east; a facing block's front, or the side a screen faces.

What a client is able to show. Ask this instead of comparing versions: a script never sees a version number.

A number at every block, as a recipe the engine works out. Sums (`+ - * / ^` and unary minus) and the methods make new fields; a plain number is a field too. A field above 0.5 is "true" where a rule asks a question.

Camera modes expose only the fields they use. Values shared across players update all their views. A removed target reads nil and ends the active view.

The carved air under `below` becomes `block` (a lake, lava): the first rule that holds at each block. Never the open sky over the land.

Particles for a room: Minecraft's particle packet; the `fx` global, or `room.fx`.

The game version a room runs, its entity kinds, blocks and items, and the pack's own blocks, items and recipes: the `game` global, or `room.game`.

A declared world, for the script to ask what the engine answers.

What `world.generate` takes. Without `height` and `density`, the rules add to the land the game's own terrain made.

One stack lying on the ground.

A layer of ground: `block` for the top `depth` blocks (1) of a surface. The first rule that holds wins.

Whose face a player head shows: a Minecraft account's name, or the `textures` profile property of a skin no account wears.

What `players.on_click` hands its callback: the button, the slot, and the player, entity, block and face the click met.

An invisible box a player can click, and a wall when solid, from `world.hitbox` (1.19.4 and later).

What `http.get` returns. A failed request is not an error: read `ok`.

A layout on one player's screen, from `player.ui.show`. `hud.<id>` is the item with that id.

One item of a shown layout, `hud.hp`: its live values. They tween.

Anywhere a colour is asked for, every spelling works: a `color` value, a name, or hex ("#ff8800"). A name nobody has is an error that says the nearest. A client from 1.16 gets the exact tone in text and an older one the nearest name it has.

A stack as a script reads it. `id` is there for a pack item, `damage` for a worn tool.

An item the game version has, from `game.item(name)`: its name and stack size.

An item to find — `take`, `count`, a recipe's ingredient. A name is the plain item and never a pack item made of it; a table matches the fields it names.

The extras an item table may carry: count, name, lore, colours, glint, a canvas map, a pack item id, wear, a 1.21.4+ model and a head's skin.

`game.items`: items of the pack's own.

An item is a name, or a table with the meta it carries.

An item table names an item, or a canvas whose map it is.

A layout the resource pack holds: what `ui.define` hands back.

How a row, a column or a stack lines its children up, and a label its words.

A piece of a layout's tree: what `ui.box`, `ui.image`, `ui.label`, `ui.row`, `ui.column` and `ui.stack` hand back. See "Layouts".

What an effect hands back for one letter; `text` shows something else in its place ("" hides it).

One spot of light no block makes, for `world.light`: a position and a level from 1 to 15.

What a client is told a pack's entity is: a shape it already draws. The two table forms carry a payload — the block a falling block shows, the stack an item shows.

A block's material as five yes-or-no questions, from `block.material`: solid, covers, firm, liquid and burns.

An open menu, from `player.ui.menu`.

A model the pack made, for `world.display{ kind = "model" }`.

What `models.new` hands its build function: makes the model's materials, textures, parts and animations.

A model visual in a room. Shares at, rotation, scale, alive and move with other visuals; adds named animations and model materials.

A flat colour in a model. A display repaints it by this name.

A named group of boxes that turns around its pivot. Units are 16 to the block, the origin is the model's bottom centre, and a box reaches -24..24.

What a box wears: one for all six faces, or one per face.

Pixel art for one face of a box: plain RGBA, and never repainted.

Handles accepted by mounting and cameras; a Model is an asset, not a target.

An instance of a member: a server the network started for itself.

What `network.start` and `network.find` answer.

Smooth random numbers from `noise.new`: the same seed gives the same numbers every time.

A player-shaped entity every client from 1.8 sees, from `world.npc`; it can walk, talk, hold items, wear armour and ride.

How an NPC holds its body: standing, crouching, sleeping or swimming.

Player | Npc | EntityHandle

Displays also accept a nose direction and roof direction; reads return angles.

A canvas on one player's screen, from `player.ui.overlay`: 128 by 128, drawn like a canvas. Row 0 is the engine's and never shows; draw in rows 1 to 127. Colour `colors.transparent` shows the game through it.

A named part of a stored world (`world: <folder>`) and the generator that writes it. Declared, not run: `citadel generate <pack> --part <name>`, or `/part generate <name>` in build mode, runs it; a changed file runs it again while nobody has edited the part. See "parts" in docs/luau-api.md.

Whether a kind survives a save. "save" puts it in the chunk record, `data` and all; "despawn" is gone when the chunk goes.

Which order of operations moves a body. Not a table of floats: the floats are the game version's, and this says which set of them applies.

The calls a screen, a canvas and a view all share.

A plant on a column. Each column takes at most one: a rule that holds is tried with its `chance` (1), in the order of the list.

A player in the room: what `players.on_join` and every player event hand you.

A room's players and their events: the `players` global, or `room.players`.

`player.ui`: the calls `ui` has, for one player alone, plus what only one player's screen holds.

A mob's body with no mind of its own that the script moves, from `world.puppet`; its name tag always shows.

The first block a ray met, and the face it came in through.

`game.recipes`: what a crafting grid and a furnace make of a pack's items. Load-time only, like a block definition. The game's own recipes are asked first, so a pack adds and never takes away.

An isolated world with its own players and tables, from `rooms.create` or `rooms.main`.

BodyRotation & { read roll: number? }

Which parts of the player simulation this room runs. All on for a `mode: full` server, all off on a pack server until the pack says. `survival` is the whole game: digging and its drops, placing, the inventory and crafting, respawning — and it turns fall, damage, hunger and day_cycle on. `anticheat` is on everywhere until a pack turns it off, and so is `redstone`: off, no signal moves in the room.

A box of blocks: a `.schem` file from the pack, read once by `world.schematic`, or one a script wrote with `world.build`. `min` is the build's own lowest corner, which is the corner `origin` puts down; a file has no coordinates of its own, so its `min` is zero.

A wall or floor of map frames showing a picture, from `world.screen`; it draws like a canvas and can answer clicks by pixel.

The side a frame display hangs on: a wall side, or "up" to lie flat on a floor or table (1.13 and later).

A purchase the player paid for, in Gems, that the pack has not handed over.

One overrun, as `citadel.on_slow` is handed it.

A WebSocket a pack opened with `http.socket`.

One message of a socket.

Plays and stops sounds for everyone in a room: the `sound` global, or `room.sound`.

Where a speaker is: a point, or a player or an entity it follows.

A sound `sound.stream` plays. Speakers are numbered from 1.

Called as the player types; must answer at once (no task.wait). `args` holds the arguments typed before this one, by name.

One word offered as a player types a command argument: a string, or a text with a tooltip.

One populate step of the overworld, as citadel.yml writes it, read from `game.terrain.steps`.

A string, a table of runs, or a function of the time (`time.now()`) handing back a text, worked out again every frame it is on screen.

Words wherever the API shows them: a string, or a table of runs. A table's entries are its runs in order (each a string or another table), and its named fields are the style of all of them; a run that names its own style keeps it. See "text" in docs/luau-api.md.

A picture drawn in code: `game.texture(w, h)`. Where a texture is taken, a string is a PNG file in the pack instead.

A block or item picture: a `Texture` drawn in code with `game.texture`, or the name of a PNG file in the pack.

Things that share one grid of `cell` blocks (8): a cell holds at most one, at a place that is the cell's own, so a thing over a chunk border is whole.

A thing that stands on a grid cell: one of `shapes`, its `(0, 0, 0)` on the block above the ground. `afloat` stands it on the water where the ground is under water; without it, nothing stands there. `place = "floor"` puts its `(0, 0, 0)` on the air block over a cave floor, `"ceiling"` on the air block under a ceiling (build it down from there).

What `on_think` gets: `n` bodies, and one buffer for each column with one f64 per body (entry i at byte i * 8). A yes or no is 1 or 0, an id of nothing is 0. Write the last nine to change them; a value left as it was changes nothing.

A named time of day that `world.time` holds the sky at: sunrise, day, noon, sunset, night or midnight.

Something that happened *to* a block.

A field easing over time, from tween or camera.path.

Titles, chat, the action bar, boss bars, the sidebar and the tab list: for everyone in a room (the `ui` global, or `room.ui`), or for one player (`player.ui`, the same calls). "Everyone" below is one player on `player.ui`.

What `on_use` answers. Never true or false.

typeof(setmetatable({} :: Vec3Fields, {} :: r: number, g: number, b: number, lerp: (self: Color, other: Color, t: number) -> Color,

A raw RGB video playing on a picture, from `picture:play`; read `playing` or call `stop`.

One player's own layer over a screen or canvas, from `screen:view(player)`; only they see it, drawn with the same calls.

A room's blocks, entities, displays, screens and time: the `world` global, or `room.world`.

Player | MountTarget

Armour, head first; each piece is an item like any other.

A box of blocks that knows who is in it, checked once a tick.