Skip to content

Types

Named types used throughout the API. An alias names the values a string parameter or field accepts; a table type describes the fields of a table you pass to a function or get back from one. Your editor's Lua language server knows them too, so it completes the values and flags typos.

Aliases

AttackMode

How a mob attacks in an attack task, see MobEntity:startAttack.

Values

  • "auto" — Shoot if the mob is able to shoot and holds a bow, a crossbow or a trident, or if it cannot hit at all, like a snow golem. Hit otherwise.
  • "melee" — Always hit.
  • "ranged" — Shoot if the mob is able to, for example to make a witch throw potions rather than punch. A mob that cannot shoot, like a zombie or a skeleton without a bow, hits instead.

CompassDirection

One of the four horizontal directions.

Values

  • "north" — Toward negative z.
  • "east" — Toward positive x.
  • "south" — Toward positive z.
  • "west" — Toward negative x.

DimensionName

The name of a dimension. Besides the vanilla ones, any dimension id is accepted, such as one added by a data pack.

Values

  • "overworld"
  • "the_nether"
  • "the_end"
  • string

EquipmentSlot

An equipment slot of a living entity.

Values

  • Hand
  • "feet" — Boots.
  • "legs" — Leggings.
  • "chest" — Chestplate or elytra.
  • "head" — Helmet, or anything else worn on the head.
  • "body" — Armor of an animal, like horse armor or a llama's carpet.
  • "saddle" — The saddle of a horse, pig or strider.

GameMode

A player's game mode.

Values

  • "survival"
  • "creative"
  • "adventure"
  • "spectator"

Hand

One of the two hands of a living entity.

Values

  • "mainhand" — The main hand; for a player it holds the selected hotbar item.
  • "offhand" — The off hand.

HitType

What a raycast hit.

Values

  • "block" — A block; the result is a BlockHitResult.
  • "entity" — An entity; the result is an EntityHitResult.
  • "miss" — Nothing.

LogTarget

Where the output of log(...) is sent, see WizardsOfLua.log.

Values

  • "source" — To the spell's command source.
  • "operators" — To all server operators.
  • "console" — To the Minecraft server console.
  • "none" — Nowhere; the output is discarded.

MoveDirection

A direction to move in: an absolute one, or one relative to the yaw.

Values

  • Side
  • "forward" — In the direction of the yaw.
  • "back" — Against the direction of the yaw.
  • "left" — To the left of the yaw.
  • "right" — To the right of the yaw.

Side

One of the six sides of a block, or a direction along one of the three axes.

Values

TaskName

The kind of task a mob executes, as MobEntity.task.name tells it.

Values

  • "path" — Started by startPathTo.
  • "attack" — Started by startAttack.
  • "follow" — Started by startFollow.
  • "flee" — Started by startFleeFrom.
  • "stay" — Started by startStay.
  • "break" — Started by startBreakBlock.
  • "place" — Started by startPlaceBlock.
  • "put" — Started by startPutInto.
  • "take" — Started by startTakeFrom.

TaskReason

Why a mob task did not start, failed or was interrupted. A start... function returns it as its second value, and MobEntity.task.reason holds it once the task has ended that way.

Values

  • "no_path" — No route to the target could be found within searchRange.
  • "unreachable" — The mob could not get there, or got stuck on the way.
  • "invalid_target" — The target is dead, or the game refuses it as a target, which is the case for players in creative or spectator mode and for ghasts. For startBreakBlock: the block is air or a fluid.
  • "other_dimension" — The target is in another world.
  • "ai_disabled" — The mob's ai is false, so it executes no tasks at all.
  • "ai_blocked" — The mob's own behavior did not hand over control within a second. This happens while it is doing something it cannot be interrupted in, such as a dolphin swimming up for air, and it can happen with mobs added by other mods.
  • "self_preservation" — The mob had to take care of itself, for example to breathe.
  • "no_damage" — The mob has no attack damage of its own and none was given. Only an attack task ends this way, and only if the attack damage is taken away while it runs.
  • "died" — The mob died.
  • "unloaded" — The mob was unloaded or changed world, which cancels its task.
  • "unbreakable" — The block cannot be broken at all, like bedrock.
  • "target_changed" — The block was replaced by another one, or the container is gone.
  • "occupied" — A block or another entity is where the block should be placed.
  • "not_a_block" — The item in the hand cannot be placed as a block.
  • "hand_empty" — The hand that should give an item holds none.
  • "cannot_place" — The block cannot stay where it should be placed, like a torch above a hole.
  • "hand_full" — The hand that should take items holds something else, or a full stack.
  • "no_container" — There is no container at the given position.
  • "container_full" — The container took none of the items.
  • "nothing_to_take" — Nothing in the container matched.
  • "replaced" — Another task was started.
  • "stopped" — The task was stopped by stopTask.

TaskState

The state of a mob task, as MobEntity.task.state tells it.

Values

  • "running" — The task is being executed.
  • "finished" — The task reached its goal.
  • "failed" — The task could not reach its goal; reason tells why.
  • "interrupted" — Something else ended the task: another task replaced it, it was stopped, or the mob's ai was switched off. reason tells which.

Tables

CommandSpec

The definition of a dynamic command, see WizardsOfLua.setCommand and WizardsOfLua.listCommands.

Fields

  • id: string — The unique identifier of the command, which is also its permission node.
  • level?: number — The operator level required to run the command, from 0 to 4. Defaults to 0.
  • pattern: string — The command syntax with %-placeholders, like "coins add amount:%i to list:%players".
  • code: string — The Lua code to compile and run when the command is invoked.

FindBlockEntitiesCriteria

The criteria of Spell:findBlockEntities.

Fields

  • block?: string|string[ ] — A block id like "chest", a block tag starting with "#", or a list of them. Defaults to any block.
  • maxradius: number — The radius of the sphere to search in blocks, at most 256.
  • limit?: number — The maximum number of block entities to return, the nearest ones, an integer from 1 to 10000. Defaults to 1000.

FindBlocksCriteria

The criteria of Spell:findBlocks.

Fields

  • block: string|string[ ] — A block id like "stone", a block tag starting with "#", or a list of them.
  • maxradius: number — The radius of the sphere to search in blocks, at most 64.
  • limit?: number — The maximum number of positions to return, the nearest ones, an integer from 1 to 10000. Defaults to 100.

MobTask

A copy of a mob's task, as MobEntity.task gives it. The first four fields are always there; the others only for the tasks that have them, as each field tells.

Fields

  • name: TaskName — The kind of task.
  • state: TaskState — The state of the task.
  • reason?: TaskReason — Why the task failed or was interrupted. nil while it runs and after it finished.
  • age: number — The number of ticks since the task started.
  • target?: Vec3|Entity — The position or entity the task was started with: a copy of the position, with whole-number coordinates for a block, or a reference to the entity. All tasks but stay.
  • speed?: number — The factor applied to the mob's normal movement speed. All tasks but stay.
  • searchRange?: number — The maximum path length in blocks. All tasks but stay.
  • targetRadius?: number — The distance in blocks at which the target counts as reached. Path.
  • traveled?: number — The distance in blocks the mob has come along its path so far. Path.
  • remainingDistance?: number — The length in blocks of the rest of the path. Path.
  • reachable?: boolean — false when the path stops short of the target. Path.
  • distance?: number — The distance in blocks to keep from the target, or at which to stop running. Attack, follow, flee.
  • mode?: AttackMode — How the mob attacks at the moment: "melee" or "ranged", never "auto". It changes when the mob's weapon does. Attack.
  • damage?: number — The damage per hit, if it was given. Attack.
  • reach?: number — The distance in blocks at which the mob can hit. Attack (if given), break, place, put, take.
  • cooldown?: number — The number of ticks between two attacks. Attack.
  • chase?: boolean — Whether the mob may move toward its target. Attack.
  • hits?: number — The number of hits that landed plus the number of shots fired. Attack.
  • wearTool?: boolean — Whether attacking or breaking wears out the tool. Attack, break.
  • duration?: number — The number of ticks the task takes: the break time, or the time to stand still if one was given. Break, stay.
  • progress?: number — How far the block is broken, from 0 to 1. Break.
  • drops?: boolean — Whether the block drops items. Break.
  • remaining?: number — The number of ticks left to stand still, if a duration was given. Stay.
  • hand?: Hand — The hand holding the block or the items. Place, put, take.
  • against?: Side — The side of the position where the block rests. Place.
  • side?: Side — The side the items go in from or are taken from, if it was given. Put, take.
  • item?: string|string[ ] — The item id, item tag or list of them to take, if it was given. Take.
  • count?: number — The maximum number of items to move, if it was given. Put, take.
  • moved?: number — The number of items moved so far. Put, take.

SpellCriteria

The criteria of Spell:findSpells. A spell must match all criteria given.

Fields

  • name?: string — The spell's name.
  • owner?: string — The name of the spell's owner.
  • tag?: string — A tag the spell carries.
  • sid?: number — The spell's id.
  • maxradius?: number — The maximum distance in blocks from this spell.
  • minradius?: number — The minimum distance in blocks from this spell.
  • excludeSelf?: boolean — Whether to leave out this spell. Defaults to false.

StartAttackOptions

The options of MobEntity:startAttack.

Fields

  • damage?: number — The damage per hit. Defaults to the mob's attack damage attribute; required for a mob that has none, like a pig.
  • reach?: number — The distance in blocks at which the mob can hit. Defaults to the reach the mob has in the game, which depends on its size.
  • cooldown?: number — The number of ticks between two attacks. Defaults to 20.
  • distance?: number — The distance in blocks a shooting mob keeps from its target; a mob that hits always closes in. Defaults to 15.
  • chase?: boolean — Whether the mob may move toward its target at all. Defaults to true.
  • mode?: AttackMode — Whether the mob hits or shoots. Defaults to "auto".
  • wearTool?: boolean — Whether attacking wears out the weapon. Defaults to false.
  • searchRange?: number — The maximum path length in blocks, an integer. Defaults to 50.
  • speed?: number — A factor applied to the mob's normal movement speed. Defaults to 1.

StartBreakBlockOptions

The options of MobEntity:startBreakBlock.

Fields

  • duration?: number — The number of ticks it takes to break the block, an integer. Defaults to the time a player with the same tool would need.
  • drops?: boolean — Whether the block drops items. Defaults to true.
  • wearTool?: boolean — Whether breaking wears out the tool. Defaults to true.
  • reach?: number — The distance in blocks from the mob's eyes to the center of the block at which it can hit the block. Defaults to 2, which brings it right up to the block.
  • searchRange?: number — The maximum path length in blocks, an integer. Defaults to 50.
  • speed?: number — A factor applied to the mob's normal movement speed. Defaults to 1.

StartFleeFromOptions

The options of MobEntity:startFleeFrom.

Fields

  • distance?: number — The distance in blocks at which the mob stops running. Defaults to 10.
  • searchRange?: number — The maximum path length in blocks, an integer. Defaults to 50.
  • speed?: number — A factor applied to the mob's normal movement speed. Defaults to 1.

StartFollowOptions

The options of MobEntity:startFollow.

Fields

  • distance?: number — The distance in blocks to keep. Defaults to 2.
  • searchRange?: number — The maximum path length in blocks, an integer. Defaults to 50.
  • speed?: number — A factor applied to the mob's normal movement speed. Defaults to 1.

StartPathToOptions

The options of MobEntity:startPathTo.

Fields

  • targetRadius?: number — The distance in blocks at which the target counts as reached, an integer. Defaults to 1.
  • searchRange?: number — The maximum path length in blocks, an integer. Defaults to 50.
  • speed?: number — A factor applied to the mob's normal movement speed, so 2 makes it walk twice as fast as it usually does. Defaults to 1.

StartPlaceBlockOptions

The options of MobEntity:startPlaceBlock.

Fields

  • hand?: Hand — The hand holding the block. Defaults to "mainhand".
  • against?: Side — The side of the position where the block rests. Defaults to "down".
  • reach?: number — The distance in blocks from the mob's eyes to the center of the block at which it can place the block. Defaults to 2.
  • searchRange?: number — The maximum path length in blocks, an integer. Defaults to 50.
  • speed?: number — A factor applied to the mob's normal movement speed. Defaults to 1.

StartPutIntoOptions

The options of MobEntity:startPutInto.

Fields

  • hand?: Hand — The hand holding the items. Defaults to "mainhand".
  • side?: Side — The side the items go in from. Defaults to the side the mob stands at, then "up".
  • count?: number — The maximum number of items to put in, an integer. Defaults to the whole stack.
  • reach?: number — The distance in blocks from the mob's eyes to the center of the container at which it can reach it. Defaults to 2.
  • searchRange?: number — The maximum path length in blocks, an integer. Defaults to 50.
  • speed?: number — A factor applied to the mob's normal movement speed. Defaults to 1.

StartStayOptions

The options of MobEntity:startStay.

Fields

  • duration?: number — The number of ticks to stand still. Defaults to no limit.

StartTakeFromOptions

The options of MobEntity:startTakeFrom.

Fields

  • item?: string|string[ ] — An item id, an item tag starting with "#", or a list of them. Defaults to any item.
  • count?: number — The maximum number of items to take, an integer. Defaults to as many as fit in the hand.
  • hand?: Hand — The hand to take the items into. Defaults to "mainhand".
  • side?: Side — The side the items are taken from. Defaults to "down".
  • reach?: number — The distance in blocks from the mob's eyes to the center of the container at which it can reach it. Defaults to 2.
  • searchRange?: number — The maximum path length in blocks, an integer. Defaults to 50.
  • speed?: number — A factor applied to the mob's normal movement speed. Defaults to 1.