Namespacing

Namespacing is a feature that allows you remap the namespaces used in your systems to something else in the generated files. This is very convenient when you want to keep your code reusable across different projects that use different namespaces. The workflow is simple: When you write your systems, you always use the same namespace, regardless of the project. Then, once you have the namespacing configured, you just let System Template remap that namespace to something that is specific to the project.

Filter Configuration

In order to properly use namespacing you have to configure 2 things - System Template settings in the config.json file (by adding the namespace property) and the auto_map.json to alter the paths of the AUTO mapping.

System Template Configuration

In order to enable namespacing, you have to add the namespace property in System Template run configuration. Below is an example of how configuration of the namespace property might look like:

"namespace": {
    "hook": "nusiq",
    "target": "xyz",
    "keep_hook": true
}

hook is the namespace you use in your systems. System Tempalte will look for some variants of this string to replace it. More infrmation below.
target is the namespace you want to replace the hook with or a string that you want to append to the hook.
keep_hook determines if the hook should be kept in the generated files.

Example 1
hook: nusiq
target: xyz
keep_hook: true

This configuration will cause System Template to replace text in all of the text files generated by system template using the following rules:

“nusiq_” -> “nusiq_xyz_”
“nusiq:” -> “nusiq_xyz:”
“nusiq.” -> “nusiq_xyz.”
“nusiq/” -> “nusiq/xyz/” Note that this one uses ‘/’ not ‘_’

With these rules:

Command tag @s nusiq_some_tag would be replaced with tag @s nusiq_xyz_some_tag.
Entity identifier nusiq:some_entity would be replaced with nusiq_xyz:some_entity.
Animation animation.nusiq.some_animation would be replaced with animation.nusiq_xyz.some_animation.
and function call function nusiq/some_function would be replaced with function nusiq/xyz/some_function.

Example 2:
hook: nusiq
target: xyz
keep_hook: false

“nusiq_” -> “xyz_”
“nusiq:” -> “xyz:”
“nusiq.” -> “xyz.”
“nusiq/” -> “xyz/”

These rules are even simpler. Basically, the hook is just replaced with the target given it has one of the above characters after it.

Auto Mapping

Since using the namespace property causes changes in the paths (see rule 4 in examples above), you have to adjust the export paths from auto_map.json to match that behavior. Luckily, you don’t have to worry about doing that yourself. The default data folder of System Template already provides different configurations of the auto_map.json file. By defult, it assumes that you are not using the namespace property. If you want to use it, simply delete the default auto_map.json and replace it with auto_map.namespaces.json (that you can find in the same folder).

In case you want to know how to configure auto_map.json yourself, here is an example of one of the mapings:

{
    ".mcfunction": "`f\"BP/functions/{__namespace__['hook']+'/'+__namespace__['target'] if __namespace__['keep_hook'] else __namespace__['target']}/\"`",
}

It may look intimidating at the first glance but when it’s broken down it’s actually really simple.

The auto_map.json is evaluated using JSON Template. This means that every string that starts and ends with ` is a Python expression. In our code the expression is an f-string. The interesting part is between the curly braces {}. You can see that we are using the __namespace__ variable. This variable is a dictionary that has the same content as the namespace property in the System Template run configuration.

The expression above means “if keep_hook is enabled, replace the hook with hook/target, otherwise just replace the hook with target”.

The __namespace__ property is added to the scope only if your System Template configuration has the namespace in its settings. It’s a normal scope variable like any other, if you want you can access it in your systems.