API Reference

Context Managers

directory(name)

Create a directory in the datapack

Parameters:

Name	Type	Description	Default
name	str	The directory name	required

Example

with directory('api'):
    with directory('foo/bar'):
        ...

folder(name)

Create a directory in the datapack

Parameters:

Name	Type	Description	Default
name	str	The directory name	required

Example:

with folder('api'):
    with folder('foo/bar'):
        ...

namespace(name)

Create a namespace directory in the datapack

Parameters:

Name	Type	Description	Default
name	str	The namespace	required

Example:

with namespace('mypack'):
    ...

Decorators

blocks(generator_fn=None, *, name=None, **kwargs)

Decorator to create a blocks tag file.

The generator function can yield JSON structures (usually a dict) or call write().

Parameters:

Name	Type	Description	Default
generator_fn	Callable[[], Iterator]	Generator function to build the file from	None
name	str	The name of the file, overrides the decorated function's name	None
kwargs	any	extra arguments to be passed to the underlying file function	{}

Example

@blocks
def transparent_blocks():
    yield {
        "values": ["minecraft:glass", "minecraft:air"]
    }

file(generator_fn=None, *, name=None, category=None, mode='w', header=False, ctx_handler=None)

Underlying function to create a file in the datapack

See mcfunction, functions, blocks, etc to write specific types.

Parameters:

Name	Type	Description	Default
generator_fn	Callable[[], Iterator]	Generator function to build the file from	None
name	str	The file name	None
category	Literal['functions', 'tags', 'blocks', 'items, advancements']	the category of file. E.g. functions, tags, blocks, items, advancements	None

Returns:

Name	Type	Description
resource_path	Resource	The resource path to the file created in this context

functions(generator_fn=None, *, name=None, **kwargs)

Decorator to create a functions tag file.

The generator function can yield JSON structures (usually a dict) or call write().

Parameters:

Name	Type	Description	Default
generator_fn	Callable[[], Iterator]	Generator function to build the file from	None
name	str	The name of the file, overrides the decorated function's name	None
kwargs	any	extra arguments to be passed to the underlying file function	{}

Example

@functions
def load():
    yield {
        "values": ["dep_pack:tick", "my_pack:tick"]
    }

items(generator_fn=None, *, name=None, **kwargs)

Decorator to create an items tag file.

The generator function can yield JSON structures (usually a dict) or call write().

Parameters:

Name	Type	Description	Default
generator_fn	Callable[[], Iterator]	Generator function to build the file from	None
name	str	The name of the file, overrides the decorated function's name	None
kwargs	any	extra arguments to be passed to the underlying file function	{}

Example

@items
def cool_items():
    yield {
        "values": ["minecraft:stick", "minecraft:apple"]
    }

json_file(generator_fn=None, *, category=None, name=None, **kwargs)

Decorator to create a JSON file.

The generator function can yield JSON structures (usually a dict) or call write().

Parameters:

Name	Type	Description	Default
generator_fn	Callable[[], Iterator]	Generator function to build the file from	None
category	Literal['functions', 'tags', 'blocks', 'items, advancements']	The type of JSON resource, used in file path	None
name	str	The name of the file, overrides the decorated function's name	None
kwargs	any	extra arguments to be passed to the underlying file function	{}

Example

@json_file('tags')
def my_tag():
    yield {
        "values": ["value1", "value2", "value3"]
    }

mcfunction(generator_fn=None, *, name=None, **kwargs)

A decorator for creating an mcfunction file.

The generator function can yield command strings or call write()

Parameters:

Name	Type	Description	Default
generator_fn	Callable[[], Iterator]	Generator function to build the file from	None
name	str	The name of the file, overrides the decorated function's name	None
kwargs	any	extra arguments to be passed to the underlying file function	{}

Example

@mcfunction
def greet():
    yield 'say Hello'
    write('say World!')
    yield 'Goodbye!'

tag(generator_fn=None, *, tag_type=None, name=None, **kwargs)

Decorator to create a generic tag file.

The generator function can yield JSON structures (usually a dict) or call write().

Parameters:

Name	Type	Description	Default
generator_fn	Callable[[], Iterator]	Generator function to build the file from	None
tag_type	Literal['functions', 'tags', 'blocks', 'items, advancements']	The resource category of the tag	None
name	str	The name of the file, overrides the decorated function's name	None
kwargs	any	extra arguments to be passed to the underlying file function	{}

Example

@tag('some_future_tag')
def my_tag():
    yield {
        "values": ["foo", "bar"]
    }

Context

Context dataclass

A class to represent the state of the datapack.

get_path()

Returns the current full path in the datapack

get_resource()

Returns the resource for the current context or None if the context does not have an associated resource. E.g. Resource, FunctionResource, etc

write(item)

Handle the given input depending on the current context

GlobalContext dataclass

increment_count(key)

Get the current count then increment the counter

call_self(*args, **kwargs)

Perform a recursive call to the current resource

Parameters:

Name	Type	Description	Default
args	any	Any args needed for the resource type of the current context. E.g. mcfunction's FunctionResource or scoped_mcfunction's ScopedFunctionResource	()
kwargs	any	Any kwargs needed for the resource type of the current context.	{}

Returns:

Name	Type	Description
resource_return_type	any	The return of the call to the current resource

Example

@scoped_mcfunction
def countdown():
    count = arg0.to_score()
    # if the count is <= 0 do not continue
    with execute(unless(count.matches("..0"))):
        continue_var = Var().set(True)
    # if continue is set to True
    with execute(if_(continue_var.present())):
        tellraw(NearestPlayer, "Countdown: ", continue_var)
        count.remove()
        call_self(Var().set_from_score(count))

get_context()

Get the current context of the datapack

Returns:

Type	Description
Context	Current context object

init_context(base_dir, config, **initial_ctx_args)

Underlying context manager for creating an initial datapack context

Parameters:

Name	Type	Description	Default
base_dir	Path	datapack base directory	required
config	dict	datapack config	required
initial_ctx_args	any	initial values to apply to the context	{}

update_context(**context_changes)

Underlying context manager for making changes to the current context

Parameters:

Name	Type	Description	Default
context_changes	any	changes to apply to the new context	{}

write(item)

Handle the given input depending on the current context

Building

The following are used by the command-line (python -m mcpy) tool to compile datapacks from python source files.

build(builder_fn, output_dir, config=None)

Calls the given datapack builder function and writes the datapack to the output directory

This automatically gets called when using the CLI tool.

Parameters:

Name	Type	Description	Default
builder_fn	Callable[[Context], None]	The datapack builder function	required
output_dir	Path	The output location of the datapack	required

datapack(_func=None, *, include=None)

Decorator to wrap a datapack creation function

Parameters:

Name	Type	Description	Default
include	list[str | Path]	The names of dependencies to bundle this datapack with	None