Game API

The split is simple: world is everything in the loaded world, local_player is your own player, minecraft is static game data that exists even outside a world.

`world` — the loaded world

Every function returns nil while no world is loaded.

Function	What it does
`world.exists()`	returns `true` while a world is loaded
`world.player(name)`	finds a player by name (case doesn't matter), or `nil`; your own player is `local_player.entity()`
`world.players()`	returns every player in the world as an array; you are in the list too — check `is_self`
`world.entities([type_id])`	returns every entity; pass a type id like `"minecraft:item"` to keep only that type
`world.block(x, y, z)`	returns the block id at that position, like `"minecraft:stone"`
`world.block_state(x, y, z)`	returns the full block state table at that position
`world.raycast(x1, y1, z1, x2, y2, z2, [fluids])`	casts a ray against blocks between two points; returns a hit table or `nil` on a miss; pass `true` to also hit fluids
`world.raycast_entity(x1, y1, z1, x2, y2, z2)`	casts a ray against entities between two points; returns a hit table or `nil`; your own player is never hit
`world.time()`	returns the world's time of day
`world.dimension()`	returns the dimension id, like `"minecraft:overworld"`

for _, p in ipairs(world.players() or {}) do
    if not p.is_self and p.distance < 8 then
        client.print_chat(p.name .. " is close!")
    end
end

`minecraft` — static game data

Function	What it does
`minecraft.item(id)`	returns the item table for one default item, like `minecraft.item("minecraft:netherite_sword")`, or `nil` for an unknown id

`local_player` — your player

Reads and controls the local player in one place. Every function returns nil (or does nothing) while no player exists, so no guards are needed.

Function	What it does
`local_player.entity()`	the full entity table of your player
`local_player.position()`	returns `x, y, z`
`local_player.velocity()`	returns `x, y, z` velocity, in blocks per tick
`local_player.rotation()`	returns `yaw, pitch`
`local_player.health()`	current health
`local_player.food()`	food level (0–20)
`local_player.saturation()`	saturation level
`local_player.on_ground()`	`true` while standing on the ground
`local_player.effects()`	your active potion effects as an array of `{id, amplifier, duration}`
`local_player.armor()`	your worn armor as `{head, chest, legs, feet}` item tables
`local_player.raycast([max_distance])`	casts a ray from your eyes along your view, against blocks and entities; returns a hit table or `nil`; default distance is 4.5
`local_player.exists()`	`true` while a local player exists
`local_player.set_velocity(x, y, z)`	sets the velocity directly, in blocks per tick
`local_player.jump()`	jumps, even mid-air
`local_player.set_position(x, y, z)`	teleports client-side to that position

module:event("tick", function()
    if local_player.on_ground() then
        local vx, _, vz = local_player.velocity()
        local_player.set_velocity(vx * 1.1, 0.42, vz * 1.1)
    end
end)

Every function that returns an entity (world.player, world.players, world.entities, local_player.entity) gives you a plain table. It is a snapshot: it shows the moment it was created and does not update by itself.

Fields every entity has:

Field	Meaning
`id`, `uuid`, `name`, `type`	entity id, UUID, display name and type (`"minecraft:player"`)
`is_self`	`true` when this entity is your own player
`alive`, `age`	whether it is alive; how many ticks it has existed
`pose`	current pose: `"standing"`, `"crouching"`, `"swimming"`, `"gliding"`, `"sleeping"`, ...
`x, y, z`, `eye_y`	position; `eye_y` is the eye height
`prev_x/y/z`, `delta_x/y/z`	position on the previous tick and how far it moved this tick
`vel_x/y/z`	current velocity
`yaw, pitch`	where the entity is looking
`width, height`	hitbox size
`distance`	distance from your player to this entity
`on_ground, sneaking, sprinting, swimming, crawling`	movement state
`spectator, invisible, glowing, silent, no_gravity`	status flags
`on_fire, fire_ticks, fire_immune`	burning state
`in_water, wet, submerged, in_lava`	fluid state; `wet` also counts rain
`frozen_ticks, frozen`	powder snow freezing
`air, max_air`	remaining air (drowning)
`fall_distance`	how far it has been falling
`vehicle`	the id of the entity it rides, or `nil`
`passengers`	array of rider entity ids, or `nil` when empty

Living entities (mobs, players) also have:

Field	Meaning
`health, max_health, absorption`	hearts, including the yellow absorption ones
`armor`	armor points (what the armor bar shows)
`hurt_time, death_time, dead`	red-flash ticks after a hit; death animation ticks
`baby, scale`	whether it is a baby and its size multiplier
`body_yaw, head_yaw`	body and head rotation (the entity's `yaw` is the head look)
`movement_speed`	movement speed attribute
`blocking, climbing, gliding, sleeping, jumping`	action state; `gliding` means elytra flight
`using_item, using_riptide`	whether it is using an item / riptide-spinning
`item_use_time, item_use_time_left`	ticks the current item has been / still needs to be used
`held_item, offhand_item`	item tables of the hands
`active_item`	the item being used right now (eating, blocking, ...), or `nil`
`equipment`	worn armor as `{head, chest, legs, feet}` item tables
`effects`	active potion effects: array of `{id, amplifier, duration, infinite, ambient, visible}`
`attributes`	effective attribute values: table of `id -> {base, value}`, e.g. `attributes["minecraft:attack_damage"].value`

Players also have ping and gamemode. Your own player additionally has:

Field	Meaning
`food, saturation`	hunger bar and hidden saturation
`xp_level, xp_progress, total_xp`	experience level, progress to the next level (0..1) and total points
`attack_cooldown`	attack charge 0..1 — `1` means the next hit is full strength
`flying, allow_flying, creative`	ability flags
`walk_speed, fly_speed`	movement ability speeds

Item table

Describes one item stack. Returned by held_item, equipment, inventory.item, minecraft.item(id) and others.

Field	Meaning
`id`, `name`, `count`	item id (`"minecraft:diamond_sword"`), display name and stack size
`empty`	`true` for an empty slot
`max_count, stackable`	how many fit in one stack
`rarity`	`"common"`, `"uncommon"`, `"rare"` or `"epic"`
`use_action`	what using it does: `"none"`, `"eat"`, `"drink"`, `"block"`, `"bow"`, `"spear"`, ...
`damage, max_damage`	durability used so far and the maximum (0 when not damageable)
`damageable, damaged, unbreakable`	durability flags
`enchanted`	`true` when the item has any enchantment
`enchantments`	table of `id -> level`, e.g. `enchantments["minecraft:sharpness"] == 5`
`custom_name`	the anvil-given name, or `nil`
`food`	`{nutrition, saturation, can_always_eat}` for eatable items, or `nil`
`tags`	array of item tag ids, like `"minecraft:swords"`
`attribute_modifiers`	array of `{attribute, id, value, operation, slot}` the item applies, or `nil`

Two methods query the stack's data components directly:

Method	What it does
`item:has_component(id)`	`true` when the stack has the component, e.g. `"minecraft:piercing_weapon"`
`item:component(id)`	the component decoded to a plain Lua value; `true` when present but not decodable; `nil` when absent

local held = local_player.entity().held_item
if held.enchantments["minecraft:sharpness"] then
    client.print_chat(held.name .. " has Sharpness")
end
if held:has_component("minecraft:piercing_weapon") then
    local weapon = held:component("minecraft:piercing_weapon")
    client.print_chat(held.name .. " dismounts: " .. tostring(weapon.dismounts))
end

Block state table

Returned by world.block_state(x, y, z). Describes the exact block at a position, including its state properties.

Field	Meaning
`id`, `name`	block id (`"minecraft:chest"`) and display name
`x, y, z`	the queried block position (floored)
`air, liquid, solid, replaceable`	basic kind flags; `replaceable` means placing over it works (grass, water, ...)
`burnable`	fire can consume it
`tool_required`	drops only when mined with the right tool
`opaque, full_cube, has_collision`	shape flags
`has_block_entity`	has extra data like a chest or furnace
`random_ticks`	receives random ticks (crops grow, ice melts, ...)
`emits_redstone`	emits redstone power
`piston_behavior`	`"normal"`, `"destroy"`, `"block"`, `"push_only"`, ...
`hardness, blast_resistance`	mining and explosion resistance
`slipperiness`	ice-like sliding (0.6 is normal, 0.98 is ice)
`velocity_multiplier, jump_velocity_multiplier`	movement slowdown on/in the block (soul sand, honey)
`luminance`	light it emits, 0–15
`opacity`	how much light it blocks
`map_color`	the color it has on maps, as a number
`properties`	table of state properties as strings, e.g. `properties.facing == "north"`, `properties.lit == "true"`
`fluid`	`{id, level, still}` when the block contains a fluid, or `nil`
`tags`	array of block tag ids, like `"minecraft:mineable/pickaxe"`

local b = world.block_state(x, y, z)
if b and b.properties.lit == "true" then
    client.print_chat(b.name .. " is lit")
end

Raycast hit table

Returned by world.raycast, world.raycast_entity and local_player.raycast. Check type to see what was hit — local_player.raycast can return either kind.

Every hit has:

Field	Meaning
`type`	`"block"` or `"entity"`
`x, y, z`	the exact point the ray hit
`distance`	distance from the ray start to the hit point

Block hits (type == "block") add:

Field	Meaning
`block_x, block_y, block_z`	the position of the hit block
`side`	the hit face: `"up"`, `"down"`, `"north"`, `"south"`, `"east"`, `"west"`
`inside`	`true` when the ray started inside the block
`state`	the full block state table of the hit block

Entity hits (type == "entity") add:

Field	Meaning
`entity`	the entity table of the hit entity

local hit = local_player.raycast(20)
if hit then
    if hit.type == "entity" then
        client.print_chat("looking at " .. hit.entity.name)
    else
        client.print_chat("looking at " .. hit.state.name .. " (" .. hit.side .. ")")
    end
end

`client` — client & chat

Function	What it does
`client.fps()`	returns the current FPS
`client.ping()`	returns your ping in milliseconds
`client.server()`	returns the server address, or `nil` in singleplayer
`client.has_screen()`	returns `true` while any screen (inventory, chat, menu) is open
`client.millis()`	returns the current time in milliseconds
`client.tick_delta()`	returns the progress between two ticks (0..1) — useful for smooth movement
`client.say_chat(text)`	sends `text` to the server chat; a leading `/` sends it as a command
`client.command(cmd)`	sends a command to the server (the leading `/` is optional)
`client.print_chat(text)`	shows a message in your chat only — nothing is sent to the server
`client.key_down(code)`	returns `true` while a key is held down (GLFW key code, e.g. 32 is space)

print(...) — the standard Lua print, shown in your chat with the [lua] prefix.

`aesthetic`

Function	What it does
`aesthetic.log(msg)`	writes a line to the game log file
`aesthetic.script`	the file name of the current script

Standard libraries

math, string, table, bit32, coroutine, a limited os (os.time, os.clock, os.date) and require (see Getting Started) are available.

Aesthetic — Lua Scripting