Python Scripts

You can mark any text file in a system to be evaluated as a Python script before it undergoes further processing. To do this, simply set the python_script property of the file in the _map.py file to True.

Example:

[
    {
        "source": "example.behavior.json",
        "target": AUTO_FLAT,
        "python_script": True
    }
]

Note

Note that the file marked as a Python script in the example above uses the .json extension. This is not a mistake. As long as the file content is a valid Python script, the extension does not matter.

Sometimes using other extensions for Python scripts in System Template is beneficial because it allows you to utilize the Auto Mapping feature. If you prefer, you can always configure your auto_map.json file to use .py extension and export files wherever you want.

Note

If you’re using VS Code, you can temporarily change the syntax highlighting of the file to Python using CTRL+SHIFT+P → Change Language Mode → Python. This makes it easier to work with System Template’s Python scripts.

How It Works

When a file is marked as a Python script, System Template does not read its text content directly. Instead, the file is evaluated using Python’s exec function.

  • If the script assigns a value to the __output__ variable, that value replaces the file’s content.

  • If __output__ is not set, the file is skipped, and no further processing occurs.

Python script files are evaluated with the system’s root as their working directory and have access to all variables passed using scope.

Since these are standard Python scripts, you can use them to generate additional files. In such cases, using __output__ is optional.

When a Python script is evaluated, it receives an additional variable in its scope: __target__.

  • __target__ contains a pathlib.Path object pointing to the evaluated, absolute target path of the file.

  • This is useful when generating files without using __output__.

Combining Python Scripts with Other Features

The Python script feature simply adds an extra step to file evaluation; it does not interfere with other processing steps. This means that you can use Python scripts to generate text values for output that can still be further processed using JSON Templates, Subfunctions, or any other System Template feature.

Example: Using a Python Script for File Generation

The content of example.behavior.json from the example above could look like this:

import json

def get_blank_entity(name: str):
    return {
        "format_version": "1.20.80",
        "minecraft:entity": {
            "description": {
                "identifier": f"nusiq:{name}",
                "is_spawnable": True,
                "is_summonable": True
            },
            "component_groups": {},
        }
    }

# __target__ is not explicitly defined in the script but is still available.
with open(__target__.parent / "example2.behavior.json", "w") as f:
    json.dump(get_blank_entity("example2"), f, indent="\t")

__output__ = json.dumps(get_blank_entity("example"), indent="\t")

This script generates two files:

  1. example.behavior.json (using __output__)

  2. example2.behavior.json (by writing directly to a file)

Considerations and Limitations

While Python scripts provide great flexibility, it is generally better to use other templating features offered by System Template. This feature is designed to give you full control over file generation, but it has some drawbacks:

  • Python scripts may be harder to understand for those unfamiliar with Python.

  • You lose the benefits of autocompletion that you would otherwise have when using JSON Templates.

  • Files created directly by Python scripts are not included in the log.