User Documentation: Types

This page lists all currently available data types with their properties and methods. For operators, see the dedicated page.

The properties’ types and methods’ signatures feature the following special characters:

• | between types: Indicates that the property value or method argument/return value may be of one of the listed types.
• ? after the type: The property value or method parameter/return value may be null.
• ... after the parameter name: The parameter is a vararg.
• ->: Indicates the return type. A method with no specified return type always returns null. It is roughly equivalent to void in C-like languages.

any

The base type. It is a placeholder used to denote that a method/function may accept/return values of any type.

block

Represents a Minecraft block.

Properties

Name	Type	Documentation
id	string	The ID of the block.

Methods

None

boolean

Represents a value that can either be true or false.

Can be implicitly converted to an int or float.

Properties

None

Methods

None

float

Represents a decimal number ranging from -(2-2^-52)·2¹⁰²³ to (2-2^-52)·2¹⁰²³.

Cannot be converted implicitly to an int. When evaluated as a boolean, a value of 0 yields false while any other value yields true.

Properties

None

Methods

None

function

Represents a function. A function is a callable object that takes arguments and returns a value.

Properties

None

Methods

None

int

Represents an integer ranging from -2⁶³ to 2⁶³-1.

Can be implicitly converted to a float. When evaluated as a boolean, a value of 0 yields false while any other value yields true.

Properties

None

Methods

None

item

Represents a Minecraft item.

Properties

Name	Type	Documentation
id	string	The ID of the item.
max_stack_size	int	The max stack size of the item.
max_damage	int	The max damage of the item.

Methods

None

list

A list is an ordered sequence of values.

Lists can be iterated over in for loops and are accepted by the len function. When evaluated as a boolean, an empty list yields false while non-empty lists yield true.

Items can be accessed/updated through the [] syntax: l[i]; will return the value at index i, l[i] := x; will set the value at index i. Indices may be negative, from -1 for the last item to -len(l) for the first item. If index i does not exist, an error will be raised. Several items can be accessed/updated at the same time by passing a range object instead of a single int:

const l := [1, 2, 3, 4];
print("@a", l[0:2] == [1, 2]); # prints true
l[0:2] := [6, 7]; # replaces the first two elements with the ones of the right list
print("@a", l == [6, 7, 3, 4]); # prints true

Items may be deleted by using the del keyword: del l[i]; will delete the value at index i from list l and shift all elements at its right towards the left. If index i does not exist, an error will be raised. Several items may be deleted at the same time by passing a range object instead of a single int:

const l := [1, 2, 3, 4];
del l[0:2]; # deletes the first two elements
print("@a", l == [3, 4]); # prints true

Properties

None

Methods

Signature	Documentation
clear()	Removes all values from this list.
add(any? value)	Adds a value at the end of this list. value: The value to add to this list.
insert(int index, any? value)	Adds a value at the specified index of this list. index: Index at which to insert the value. value: The value to add to this list.
extend(list other)	Appends the values of the given list to the end of this one. Modifies this list. This is strictly equivalent to this += other;. All elements of the provided list will be copied before being inserted. other: The list to append.
count(any? value) -> int	Counts the number of times the given value occurs in this list. value: The value to count the occurences of. Returns: The number of occurences of the value.
index(any? value) -> int	Returns the index of the first occurence of the given value in this list. Returns -1 if the value is not present in this list. value: The value to get the index of. Returns: The index of the first occurence or -1 if the value was not found.
sort(boolean reversed)	Sorts this list using natural ordering of its elements. reversed: If true this list will be sorted in reverse order.

map

A map is a data structure that contains key-value pairs where keys cannot appear multiple times.

Maps can be iterated over in for loops and are accepted by the len function. for loops will iterate over the keys. When evaluated as a boolean, an empty map yields false while non-empty maps yield true.

Items can be accessed/updated through the [] syntax: m[k]; will return the value for key k, m[k] := x; will set the value for key k. If key k does not exist when querying, an error will be raised; it will be created if updating.

Entries may be deleted by using the del keyword: del m[k]; will delete the value for key k from map m. If key k does not exist, an error will be raised.

Properties

Name	Type	Documentation
keys	set	The set of all keys of this map.
values	list	The list of all values of this map. Order of values in the returned list is not guaranteed.

Methods

Signature	Documentation
clear()	Removes all values from this map.
extend(list other)	Adds all the entries of the given map into this one. Modifies this map. If this map already contains an entry for a key of the argument map, its value will be replaced by the one from the latter. This is strictly equivalent to this += other;. All values of the provided `map will be copied before being inserted. other: The list to append.

module

A module is a script that was imported using the import instruction. Its public variables and functions can be accessed using the . operator like a regular object property.

null

This type has a single value, null which represents the absence of any value.

When evaluated as a boolean, it always yields false.

pos

Represents a 3D position. Its components are floats or ints.

When converted to a string, the resulting representation is parsable by in-game commands.

Properties

Name	Type	Documentation
x	float|int	The x component of this position.
y	float|int	The y component of this position.
z	float|int	The z component of this position.
x_relative	boolean	Indicates whether the x component is relative (tilde or caret notation).
y_relative	boolean	Indicates whether the y component is relative (tilde or caret notation).
z_relative	boolean	Indicates whether the z component is relative (tilde or caret notation).

Methods

Signature	Documentation
up(int offset) -> pos	Returns a position that is a certain amount of blocks above. offset: The number of blocks up. Returns: A new pos object.
down(int offset) -> pos	Returns a position that is a certain amount of blocks below. offset: The number of blocks down. Returns: A new pos object.
north(int offset) -> pos	Returns a position that is a certain amount of blocks north. offset: The number of blocks to the north. Returns: A new pos object.
south(int offset) -> pos	Returns a position that is a certain amount of blocks south. offset: The number of blocks to the south. Returns: A new pos object.
west(int offset) -> pos	Returns a position that is a certain amount of blocks west. offset: The number of blocks to the west. Returns: A new pos object.
east(int offset) -> pos	Returns a position that is a certain amount of blocks east. offset: The number of blocks to the east. Returns: A new pos object.
rotate(int quadrant) -> pos	Rotates a position by 0°, 90°, 180° or 270°. quadrant: 0 for 0°, 1 for 90°, 2 for 180°, 3 for 270°. Returns: A new pos object.
distance(pos p) -> float	Returns the distance between two positions. p: The position to get the distance to. Returns: The euclidian distance between the two positions.
distance_sq(pos p) -> float	Returns the squared distance between two positions. p: The position to get the distance to. Returns: The squared euclidian distance between the two positions.

range

A range is an iterable object that returns values in between two bounds with a certain step.

Their main use is within for loops. They are accepted by the len function. When evaluated as a boolean, an empty range yields false while non-empty range yield true.

There are two ways to create a range object: through the range function or with a dedicated syntax:

• start:end creates a range object from start (inclusive) to end (exclusive) with a step of 1.
• start:end:step creates a range object from start (inclusive) to end (exclusive) with a step of step.

Properties

None

Methods

None

set

A set is an unordered collection of unique values.

Sets can be iterated over in for loops and are accepted by the len function. The order in which elements are iterated over is not guaranteed. When evaluated as a boolean, an empty set yields false while non-empty sets yield true.

Properties

None

Methods

Signature	Documentation
clear()	Removes all values from this set. Modifies this set.
add(any? value)	Adds a value to a set. Modifies this set. value: The value to add to this set.
is_disjoint(set other) -> boolean	Checks whether this set and the provided one have no elements in common. other: A set. Returns: True if both sets share no elements, false if they have at least one in common.
union(set other)	Performs the union of values of two set objects, i.e. adds all values of the provided set into this one. Modifies this set. This is strictly equivalent to this |= other;. All elements of the provided set will be copied before being inserted. other: The set perform the union with.
intersection(set other)	Performs the intersection of values of two set objects, i.e. removes all values from this set that are not contained in the provided set. Modifies this set. This is strictly equivalent to this &= other;. other: The set to perform the intersection with.
difference(set other)	Performs the difference of values of two set objects, i.e. removes all values from this set that are contained in the provided set. Modifies this set. This is strictly equivalent to this -= other;. other: The set to perform the difference with.
symmetric_difference(set other)	Performs the symetric difference of values of two set objects, i.e. retains all values that are contained in both this set and the provided one. Modifies this set. This is strictly equivalent to this ^= other; or this := (this | other) - (this & other); (note: the latter may be less memory efficient as intermediate copies of this set may be made). All elements of the provided set will be copied before being inserted. other: The set to perform the symmetric difference with.

string

A string is a sequence of characters that represents text. Strings are immutable objects.

Strings can be iterated over in for loops. The len function returns the number of Unicode code units. When evaluated as a boolean, an empty string yields false while non-empty strings yield true.

Characters can be accessed through the [] syntax: s[i]; will return the character at index i. If index i does not exist, an error will be raised. Indices may be negative, from -1 for the last character to -len(s) for the first character. Several characters can be accessed at the same time by passing a range object instead of a single int:

const s := "abcd";
print("@a", s[0:2] == "ab"); # prints true

As strings are immutable, characters cannot be replaced nor deleted.

Properties

None

Methods

Signature	Documentation
lower() -> string	Converts a string to lower case. Returns: A new string.
upper() -> string	Converts a string to upper case. Returns: A new string.
title() -> string	Converts a string to title case, i.e. sets the first letter of every word to upper case and all other letters to lower case. Returns: A new string.
starts_with(string prefix) -> boolean	Returns whether a string starts with the given string. prefix: The string to search for. Returns: True if the string begins with the given prefix, false otherwise.
ends_with(string suffix) -> boolean	Returns whether a string ends with the given string. prefix: The string to search for. Returns: True if the string ends with the given suffix, false otherwise.
count(string needle) -> int	Returns the number of times a string is present in another. prefix: The string to get the number of occurences of. Returns: The number of occurences of the needle.
index(string needle) -> int	Returns the index of the first occurence of the given string this string, or -1 if no occurence were found. prefix: The string to get the index of. Returns: The index of the first occurence of the needle or -1 if it was not found.
strip() -> string	Removes all leading and trailing whitespace from a string. Returns: A new string.
left_strip() -> string	Removes all leading whitespace from a string. Returns: A new string.
right_strip() -> string	Removes all trailing whitespace from a string. Returns: A new string.
replace(string target, string replacement) -> string	Replaces each substring of this string that matches the target string with the specified replacement sequence. target: The substring to replace. replacement: The replacement string. Returns: A new string.
replace_regex(string target, string replacement) -> string	Replaces each substring of this string that matches the regex string with the specified literal replacement sequence. target: The regex. replacement: The replacement string. Returns: A new string.
split(string separator) -> list	Splits a string around matches of the given regular expression. separator: The delimiting regular expression. Returns: The list of string objects computed by splitting the string around matches of the given regular expression.
join(list collection) -> list	Joins all values from the given list using the string as a delimiter. collection: A list containing the values to join. Returns: A new string.
format(any? args...) -> list	Formats a string using the specified values. args: The values to insert into the string. Returns: A new string.

world

Represents a world dimension (overworld, nether, end, etc.). They are the objects through which scripts can interact with blocks, entities, etc.

World instances may be accessed through various global variables:

• OVERWORLD: The overworld dimension.
• THE_NETHER: The Nether dimension.
• THE_END: The End dimension.
• DIM: The dimension the script is running in.
• DIMS: A map object containing all loaded dimensions, i.e. all vanilla dimensions as well as the ones defined by enabled datapacks and active mods, if any. Each map entry associates the dimension’s ID (e.g.: minecraft:overworld) to the world dimension object itself.

Properties

Game rules can be accessed and set through properties bearing the exact same name as the rule, prefixed with gr_.

Name	Type	Documentation
dimension	string	Name of the dimension this world object represents.
dimension_type	string	Name of the dimension type this world object represents.
seed	int	The seed of the world.
day	int	The current day of the world.
day_time	int	The current time of day of the world.
game_time	int	The current game time (number of ticks) of the world.

Methods

Signature	Documentation
players_have_advancement(string targets, string advancement, string? criterion) -> boolean	Returns whether the selected players have the given advancement. targets: An entity selector that targets players. advancement: The advancement to check. criterion: An optional criterion for the advancement. Returns: True if all the targetted players have the specified advancement, false otherwise, null if an error occured.
get_entity_data(string target, string? target_nbt_path) -> list?	Returns NBT data from the targetted entity. target: An entity selector that targets a single entity. target_nbt_path: The path to the data to query. If null, all data is returned. Returns: The queried data or null if none or more than one entity were targetted or the specified path is invalid.
get_block_entity_data(pos position, string? target_nbt_path) -> list?	Returns NBT data from the block entity at the given position. position: A block position. target_nbt_path: The path to the data to query. If null, all data is returned. Returns: The queried data or null if the targetted block does not have a block entity or the specified path is invalid.
get_storage_data(string identifier, string? target_nbt_path) -> list?	Returns NBT data from the specified storage. position: A storage identifier. target_nbt_path: The path to the data to query. If null, all data is returned. Returns: The queried data or null if the specified storage does not exist or the specified path is invalid.
list_all_datapacks() -> list?	Returns the list of names of all available and/or enabled datapacks. Returns: The list of names of all available and/or enabled datapacks, null if an error occured.
list_available_datapacks() -> list?	Returns the list of names of all available but non-enabled datapacks. Returns: The list of names of all available datapacks excluding those enabled, null if an error occured.
list_enabled_datapacks() -> list?	Returns the list of names of all enabled datapacks. Returns: The list of names of all enabled datapacks, null if an error occured.
reload_datapacks()	Reloads all datapacks.
get_force_loaded_chunks() -> list	Queries all force loaded chunks. Returns: The list of force loaded chunks’ positions.
is_chunk_force_loaded(pos p) -> boolean	Checks whether the chunk at the given position is force loaded. p: A block position inside the chunk to test. Returns: True if the chunk is force loaded, false otherwise.
get_block(pos p) -> block	Returns the block at the given position. p: Position of the block. Returns: The block at the given position.
get_block_state(pos p) -> map	Returns the block state at the given position in this world. p: Position of the block. Returns: A map containing all properties of the block.
is_block_loaded(pos p) -> boolean	Returns whether the block at the given position is currently loaded. p: Position of the block to check. Returns: True if the block is loaded, false otherwise.
get_players_list() -> map	Fetches profile data for all connected players. Returns: A map containing data for all connected players.
get_scoreboard_objectives() -> list	Returns the list of defined scoreboard objectives. Structure: name: Objective’s name. display_name: Objective’s display name. render_type: How the objective is rendered: either "hearts" or "integer". criteria: Objective’s criteria. read_only: True if the objective is read-only, false otherwise. Returns: A list of map objects that each contain data of a single objective.
get_players_tracked_by_scoreboard() -> list	Returns the names of all players tracked by the scoreboard. Returns: A sorted list of the names of all players tracked by the scoreboard.
get_player_scores(string player_name) -> map	Returns the scoreboard scores for the given player. player_name: The name of the player. Returns: A map containing the scores of each objective.
get_scoreboard_tags_for_players(string targets) -> map?	Returns the tags of selected players. targets: An entity selector that targets players. Returns: A map that contains the tags of each targetted player or null if an error occurs. Keys correspond to player entities IDs.
is_players_score_within_range(string targets, string objective, int min, int max) -> boolean?	Checks whether the score of the selected players is within the given range. targets: An entity selector that targets players. objective: Name of the objective to check. min: Lower bound of the range (inclusive). max: Upper bound of the range (inclusive). Returns: True if the score of all targetted players is within the range, false otherwise, null if an error occured.
entities_match(string targets) -> int?	Returns the number of entities that matched the selector or null if an error occured. targets: An entity selector.
get_entities_data(string targets) -> list?	Fetches the data of all entities that matched the given selector. targets: An entity selector. Returns: A list of map objects that each contain the data of an entity that matched the selector or null if an error occured.
locate_structure(string structure_id, pos around, int radius, boolean skip_already_discovered) -> pos?	Returns the coordinates of the closest structure around the given point. structure_id: ID of the structure to find. around: Position to look around of. radius: Search radius around the position. skip_already_discovered: Whether to skip structures that were previously discovered. Returns: The position of the nearest structure of desired type or null if an error occured.
locate_biome(string biome_id, pos around, int radius) -> pos?	Returns the coordinates of the closest biome around the given point. biome_id: ID of the biome to find. around: Position to look around of. radius: Search radius around the position. Returns: A position in the nearest biome of desired type or null if an error occured.
execute(string name, any args...) -> int?	Executes a command and returns its result value. See the Minecraft Wiki for more information. The `/trigger` command is not accepted and will raise an error. name: Name of the command to execute. Must not include the / character. args: The command’s arguments. All values will be converted to strings. Returns: The result of the command or null if an error occured.