Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ohemilyy/universe/llms.txt

Use this file to discover all available pages before exploring further.

Templates are directories of files that Universe copies into an instance’s working directory (./running/<instance-id>/) before launching the instance process. They let you share common configuration, assets, and startup files across every instance of a configuration without duplicating them manually. After copying, Universe scans the files listed in fileModifications and replaces placeholder variables — like %PORT% and %INSTANCE_ID% — with the actual runtime values for that instance.

​
Directory structure

Templates live under ./templates/<group>/<name>/. The group is a top-level namespace for organizing related templates; the name is the specific template within that group.
templates
global
server
server.properties
plugins
lobby
default
server.properties
world
In this example, global/server is a shared base template applied to every server instance, while lobby/default provides lobby-specific files that layer on top.

​
Template installation

When a new instance is created, TemplateManager resolves and installs templates in the following sequence:
1

Resolve templates

Universe evaluates the templateInstallationConfig in the instance’s configuration file to determine which templates to install. The four selection modes — allOf, allInGroups, oneOf, oneInGroups — are each processed and their results combined into a single list.
2

Sort by priority

The resolved template list is sorted by the priority field on each Template entry. Sort order depends on onTemplatePasteOverridePresentFiles:
  • false (default): Higher-priority templates are pasted first. Lower-priority templates skip files that already exist.
  • true: Lower-priority templates are pasted first. Higher-priority templates are pasted last and overwrite existing files.
3

Copy files

Each template directory is recursively copied to ./running/<instance-id>/. Files from storage-backed templates (e.g., S3) are downloaded first if not already present locally.
4

Apply variable replacement

Universe reads each file listed in Configuration.fileModifications and replaces all recognized placeholder strings with their runtime values. See built-in variables below.

​
Selection modes

ModeBehavior
allOfEvery template explicitly listed is installed.
allInGroupsEvery template found inside each named group directory is installed. Includes templates from registered remote storage providers.
oneOfExactly one template is selected at random from the provided list and installed.
oneInGroupsFor each named group, exactly one template from that group is selected at random and installed.
You can combine modes. For example, use allOf to always install a shared base template and oneInGroups to add a randomly-selected map or variant on top of it.

​
Built-in variables

Variables are replaced in files listed in the fileModifications field of the instance configuration. The replacement applies to the full text content of each listed file.
PlaceholderResolved valueSource
%PORT%The port allocated to this instanceDetermined at deploy time from availablePorts range
%INSTANCE_ID%The unique 6-character instance IDGenerated from UUID.randomUUID() at deploy time
%MASTER_IP%Master node IP addressmasterAddress in config.json
%MASTER_ADDRESS%Master node IP addressSame as %MASTER_IP% — alias for compatibility
%MASTER_PORT%Master Hazelcast portmasterPort in config.json
%MASTER_API_PORT%Master REST API portmasterApiPort in config.json
%NODE_ID%ID of the wrapper node running this instancenodeId in config.json on the executing node
%HOST_ADDRESS%Address instances advertise to clientshostAddress in the instance configuration file
%CONFIGURATION_NAME%Name of the instance configurationname field in the instance configuration file
%MASTER_IP% and %MASTER_ADDRESS% resolve to the same value. Both are provided for backwards compatibility; prefer %MASTER_ADDRESS% in new templates.

​
The fileModifications field

Variable replacement only runs on files you explicitly opt into via fileModifications in the instance configuration. This is intentional: scanning every file in a large template for replacements would be expensive and could corrupt binary files.
./configuration/default.json (excerpt)
{
  "fileModifications": ["server.properties", "config/settings.yml"]
}
Only the listed paths (relative to the instance working directory) are read, modified, and written back. Files not listed are copied verbatim.

​
Example: server.properties with variable replacement

A server.properties file in a template can reference placeholders that Universe fills in at deploy time:
templates/global/server/server.properties
server-port=%PORT%
server-ip=%HOST_ADDRESS%
level-name=world
online-mode=false
After installation, the file in ./running/<instance-id>/server.properties will contain the actual port and host address for that specific instance:
./running/abc123/server.properties (after replacement)
server-port=25566
server-ip=10.0.0.2
level-name=world
online-mode=false

​
Template sync between nodes

Templates stored locally on one node can be pushed to other cluster nodes using the template sync command: 
template sync server/base node-2        # sync one template
template sync server/* node-2           # sync all templates in a group
template sync * node-2                  # sync all templates

​
Custom variables

Extensions can contribute additional placeholder variables by implementing TemplateVariableProvider and registering with the TemplateVariableRegistry. Custom variables take precedence over built-in ones if they share the same placeholder name. For details on building extensions that add custom template variables, see the building extensions guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us