Command API Reference

The command API is focused on making the built-in Minecraft commands easier to work with.

NBT Data

Module for all NBT related container types and functions. Not all of these NBT container types need to be constructed on their own because most functions that use them as parameters can convert their primitive types directly. (e.g. a dict can be used instead of constructing an NbtObj)

Attributes:

Name	Type	Description
NbtPrimitive	Union[str, int, bool, dict, list]	Data types that can be converted into valid NBT data

Bool dataclass

Bases: Value

Container type for NBT Boolean values.

Attributes:

Name	Type	Description
value	bool	Bool

Example

value = Bool(True)

Byte dataclass

Bases: Value

Container type for NBT Byte values.

Attributes:

Name	Type	Description
value	int	Int representation of bytes

Example

value = Byte(12)

Float dataclass

Bases: Value

Container type for NBT Float values.

Attributes:

Name	Type	Description
value	float	Float

Example

value = Float(12.3)

Int dataclass

Bases: Value

Container type for NBT Int values.

Attributes:

Name	Type	Description
value	int	Int

Example

value = Int(12)

NbtList dataclass

Bases: Value

Container type for NBT List values.

Attributes:

Name	Type	Description
value	list	List

Example

value = NbtList(['foo','bar'])

NbtObj dataclass

Bases: Value

Container type for NBT Compound values. (e.i. JSON object)

Attributes:

Name	Type	Description
value	dict	Dict representation of object

Example

value = NbtObj({'name':'Some name'})

NbtPath dataclass

Bases: CmdObject

Container type for NBT paths

Attributes:

Name	Type	Description
path	str	String data path (e.g. Inventory[0])

Example

value = NbtPath('some.nested.path')

at(index)

Create a new path from the current and given index or query Attributes: index_or_query: Index or query Returns: A new NbtPath

Example

path = str(NbtPath('foo').where({"Count":Byte(2)}))
# returns 'foo[{"Count":1b}]'

key(subpath)

Create a new path from the current and given subpath Attributes: subpath: Subpath key(s) to add to this path Returns: A new NbtPath

Example

path = str(NbtPath('foo').key('bar'))
# returns 'foo.bar'

where(index_or_query)

Create a new path from the current and given index or query Attributes: index_or_query: Index or query Returns: A new NbtPath

Example

path = str(NbtPath('foo').where({"Count":Byte(2)}))
# returns 'foo[{"Count":1b}]'

Short dataclass

Bases: Value

Container type for NBT Short values.

Attributes:

Name	Type	Description
value	int	Int representation of short

Example

value = Short(12)

Str dataclass

Bases: Value

Container type for string values

Attributes:

Name	Type	Description
value	str	String value. Double quotes will be escaped when used in commands

Example

value = Str('Some name')

Value dataclass

Bases: CmdObject

Base container type for all NBT value types. Can also be used to express any string-able value.

Attributes:

Name	Type	Description
value	any	Raw value. String representation will be used in commands.

Example

macro_value = Value('$(my_macro_var)')

as_nbt(primitive_value)

Convert the given type into its NBT wrapped type if possible

Attributes:

Name	Type	Description
primitive_value		value

Returns:

Type	Description
Union[Value, Str, Bool, Int, NbtObj, NbtList]	NBT subtype that corresponds to the given Python type value

Raises:

Type	Description
ValueError	When a NBT type is not found for the given value

Selectors

Module for all entity selector container types and functions

Selector dataclass

Bases: CmdObject

Base container type for entity selectors

Attributes:

Name	Type	Description
entity_type	str	type of entity (e.g. @s, @p)
arguments	tuple	selector arguments built with where function

Example

s = Selector('@s').where('tag','foo')
# or use built in ones
s = CurrentEntity.where('tag','foo')
a = AllPlayers.where('tag','foo')
r = RandomPlayer.where('tag','foo')
p = NearestPlayer.where('tag','foo')
e = Entities.where('tag','foo')

Data Command

Module for all data command container types and functions

Attributes:

Name	Type	Description
TargetType	Union[StoragePath, EntityPath, BlockPath]	Data types that can be used as the target of a data command. (e.g. the one being affected)
SourceType	Union[StoragePath, EntityPath, BlockPath, Value, NbtPrimitive]	Data types that can be used as the source of a data command. (e.g. the one being read from)

BlockPath dataclass

Bases: DataPath, Tellable

A container for a block path

Attributes:

Name	Type	Description
pos	str	block pos string triplet (e.g. "~ 1 ~")

Example

chest_items = BlockPath("Items", "~1 ~2 ~1")
count = (
    chest_items.where({"id": "minecraft:stick"}).to_score()
)

to_tellable()

Converts this container type to a tellraw printable element

Returns:

Type	Description
dict	dict tellraw element

DataCondition dataclass

Parent class of data command container types that can be used in execute conditions

has_value(expected_value)

condition for the checking the value at a data path Args: expected_value: NBT value to compare against Returns: Condition string

Example

@mcfunction
    def foo():
        data = EntityPath("SelectedItem", CurrentEntity)
        with execute(
            unless(data.has_value({"id": "minecraft:apple", "Count": "1b"}))
        ):
            ...

present()

condition for the existence of the this data path

Returns:

Type	Description
str	Condition string

Example

@mcfunction
    def foo():
        data = EntityPath("SelectedItem", CurrentEntity)
        with execute(unless(data.present())):
            ...

DataPath dataclass

Bases: NbtPath, DataCondition

Base class to all data path types

See BlockPath, EntityPath, and StoragePath for examples.

append(value)

Append the value to the end of this data path

Parameters:

Name	Type	Description	Default
value	any	Source data type	required

Returns:

Type	Description
Self	Self

merge(source, modify=True)

Merge the data source into this data path.

Parameters:

Name	Type	Description	Default
source	any	Source data type	required
modify	bool	Flag for using "data modify ... merge" or "data merge ..."	True

Returns:

Type	Description
Self	Self

remove()

Remove the data at this data path

Returns:

Type	Description
Self	Self

set(value)

Set the data path to the given value

Parameters:

Name	Type	Description	Default
value	any	Can be of any data path, NBT primitive, or Value type.	required

Returns:

Type	Description
Self	Self

set_from_score(score, result_type='int', scale=1)

Save the given score's value into this data path

Parameters:

Name	Type	Description	Default
score	Score	source score	required
result_type	str	data path data type	'int'
scale	int	multiplier	1

Returns:

Type	Description
Self	Self

to_score(holder=None, objective=None)

Convert this data path to a score value

Parameters:

Name	Type	Description	Default
holder	str	score holder	None
objective	str	score objective	None

Returns:

Type	Description
Score	Score

EntityPath dataclass

Bases: DataPath, Tellable

A container for an entity path

Attributes:

Name	Type	Description
selector	str	entity selector

Example

inventory_items = EntityPath("Inventory", CurrentEntity)
count = (
    inventory_items.where({"id": "minecraft:stick"}).to_score()
)

to_tellable()

Converts this container type to a tellraw printable element

Returns:

Type	Description
dict	dict tellraw element

StoragePath dataclass

Bases: DataPath, Tellable

A container for a storage path

Attributes:

Name	Type	Description
namespace	str	storage namespace

Example

some_data = StoragePath('some.path', 'namespace:io')
some_data.set("a string")

to_tellable()

Converts this container type to a tellraw printable element

Returns:

Type	Description
dict	dict tellraw element

data_get(target)

Command template function for "data get ..."

Parameters:

Name	Type	Description	Default
target	TargetType	target path	required

Returns:

Type	Description
Iterator[str]	yielded command

data_merge(target, source)

Command template function for "data merge ..."

Parameters:

Name	Type	Description	Default
target	TargetType	target path	required
source	Value	source path or value	required

Returns:

Type	Description
Iterator[str]	yielded command

data_modify_append(target, source)

Command template function for "data modify ... append ..."

Parameters:

Name	Type	Description	Default
target	TargetType	target path	required
source	SourceType	source path or value	required

Returns:

Type	Description
Iterator[str]	yielded command

data_modify_merge(target, source)

Command template function for "data modify ... merge ..."

Parameters:

Name	Type	Description	Default
target	TargetType	target path	required
source	SourceType	source path or value	required

Returns:

Type	Description
Iterator[str]	yielded command

data_modify_set(target, source)

Sets the target path to the given source path or value

Parameters:

Name	Type	Description	Default
target	TargetType	target path	required
source	SourceType	source path or value	required

Returns:

Type	Description
Iterator[str]	yielded command

data_remove(target)

Command template function for "data remove ..." Args: target: target path

Returns:

Type	Description
Iterator[str]	yielded command

get_target_type(target)

Utility function for getting the string representation of the class type to be used in commands Args: target: data path, NBT primitive, or value type

Returns:

Type	Description
str	string representation of type

Raises:

Type	Description
ValueError	if given an unhandled container type

Example

get_target_type(StoragePath('some.path','my_storage:'))
# returns "storage"

Execute Command

Module for all execute command container types and functions

execute(*conditions, limit=3)

Context manager to execute the inner statements with the given conditions

Parameters:

Name	Type	Description	Default
conditions	str	execute conditions e.g. if, unless, store, etc to apply to each command	()
limit	int	the maximum number of inline commands to allow before creating a generated mcfunction file. If None then all child commands will be inline.	3

Example

@mcfunction
def myfile3():
    ...
    with execute('if score $holder obj matches 1'):
        yield 'say cmd 1'
        yield 'say cmd 2'
        yield 'say cmd 3'
        yield 'say cmd 4'

if_(*conditions)

Wrapper for building "execute if" conditions

Parameters:

Name	Type	Description	Default
conditions	str	all conditions to prefix with "if"	()

Example

@mcfunction
    def foo():
        data = EntityPath("SelectedItem", CurrentEntity)
        with execute(if_(data.present())):
            ...

unless(*conditions)

Wrapper for building "execute unless" conditions

Parameters:

Name	Type	Description	Default
conditions	str	all conditions to prefix with "unless"	()

Example

@mcfunction
    def foo():
        data = EntityPath("SelectedItem", CurrentEntity)
        with execute(unless(data.present())):
            ...

Scoreboard Command

Score dataclass

Bases: CmdObject, ScoreCondition, Tellable

Container to hold a score holder and objective

add(count=1)

Command to add an amount to a player score

enable()

Command to enable a player score

get()

Command to get a player score

remove(count=1)

Command to remove an amount from a player score

reset()

Command to reset a player score

set()

Command to set a player score

score_add(score, count=1)

Command to add an amount to a player score

score_enable(score)

Command to enable the score

score_get(score)

Command to get a player score

score_objectives_add(name, type=None)

Command to add an objective. Type defaults to "dummy"

score_remove(score, count=1)

Command to remove an amount from a player score

score_reset(score)

Command to reset the score

score_set(score)

Command to set a player score

Tag Command

Module for all tag command container types and functions

Tag dataclass

Bases: CmdObject

Command template function to add a tag to the given selector

Attributes:

Name	Type	Description
name	str	Optional name for the tag

Example

enabled = Tag('enabled')
temp_tag = Tag()

__invert__()

Operator to negate a tag. See Tag.negate

Returns:

Type	Description
Tag	New negated tag

Example

enabled = Tag('enabled')
not_enabled = Entities.where('tag', ~enabled)

add(entity_selector)

Add this tag to the given entity

Parameters:

Name	Type	Description	Default
entity_selector	Selector	Entity to add this tag to	required

Returns: Self

Example

enabled = Tag('enabled')
enabled.add(CurrentEntity)

negate()

Negates this tag by prefixing a !.

Returns:

Type	Description
Tag	New negated tag

Example

enabled = Tag('enabled')
not_enabled = Entities.where('tag', enabled.negate())

remove(entity_selector)

Remove this tag from the given entity

Parameters:

Name	Type	Description	Default
entity_selector	Selector	Entity to remove this tag from	required

Returns: Self

Example

enabled = Tag('enabled')
enabled.remove(CurrentEntity)

tag_add(entity_selector, tag)

Command template function to add a tag to the given selector

Parameters:

Name	Type	Description	Default
entity_selector	Selector	Entity to add the tag to	required
tag	Tag	tag to add	required

Returns:

Type	Description
Iterator[str]	yielded command

Example

enabled = Tag('enabled')
tag_add(CurrentEntity, enabled)
tag_add(CurrentEntity, 'foo')

tag_remove(entity_selector, tag)

Command template function to remove a tag to the given selector

Parameters:

Name	Type	Description	Default
entity_selector	Selector	Entity to remove the tag to	required
tag	Tag	tag to remove	required

Returns:

Type	Description
Iterator[str]	yielded command

Example

enabled = Tag('enabled')
tag_remove(CurrentEntity, enabled)
tag_remove(CurrentEntity, 'foo')

Tellraw Command

Writes a tellraw command using the given items

Parameters:

Name	Type	Description	Default
entity_selector	any	Entity to tell the message to	required
items	Union[Tellable, str, dict]	items to include in the tellraw command	()

Example

foo_var = Var()
foo_var.set(True)
tellraw(CurrentEntity,"Enabled: ", foo_var)