Skip to main content

Documentation Index

Fetch the complete documentation index at: https://new-docs.simplecloud.app/llms.txt

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

​
What are Configurators?

Configurators automatically adjust server configuration files based on the server software being used. They handle settings like port binding, player forwarding, and other software-specific configurations using placeholder substitution.

​
How Configurators Work

During server preparation, the Serverhost:
  1. Loads the configurator template from options/configurators/
  2. Identifies the target configuration files
  3. Replaces placeholders with actual server values
  4. Writes the configured files to the server directory

​
Configurator Templates

Configurators are defined in YAML files at options/configurators/{name}.yml. Each configurator specifies which files to modify and what placeholders to replace.

​
Example: Paper + Velocity

# options/configurators/paper_velocity.yml
files:
  - path: server.properties
    format: properties
    values:
      server-port: "{{port}}"
      max-players: "{{max-players}}"
      online-mode: "false"

  - path: config/paper-global.yml
    format: yaml
    values:
      proxies.velocity.enabled: true
      proxies.velocity.secret: "{{forwarding-secret}}"
      proxies.velocity.online-mode: true

  - path: spigot.yml
    format: yaml
    values:
      settings.bungeecord: false

​
Example: Velocity

# options/configurators/velocity.yml
files:
  - path: velocity.toml
    format: toml
    values:
      bind: "0.0.0.0:{{port}}"
      show-max-players: "{{max-players}}"
      player-info-forwarding-mode: "modern"
      forwarding-secret-file: "forwarding.secret"

  - path: forwarding.secret
    format: text
    content: "{{forwarding-secret}}"

​
Supported Formats

FormatExtensionDescription
yaml.yml, .yamlYAML configuration files
json.jsonJSON configuration files
properties.propertiesJava properties files
toml.tomlTOML configuration files
textanyPlain text file replacement

​
Placeholders

Configurators support dynamic placeholders that are replaced with server-specific values:

​
Server Properties

PlaceholderDescription
{{port}}Assigned server port
{{server-name}}Server name (e.g., lobby-1)
{{group}}Group name
{{max-players}}Maximum player count
{{memory}}Allocated memory (MB)

​
Network Properties

PlaceholderDescription
{{forwarding-secret}}Velocity forwarding secret
{{server-ip}}Server IP address
{{network-id}}Network identifier

​
Type Properties

PlaceholderDescription
{{type}}Server type (proxy, server, lobby)
{{software}}Server software (paper, velocity, etc.)

​
Custom Properties

Access custom properties defined in the group: 
values:
  custom-setting: "{{$.my-custom-property}}"
The $. prefix accesses the server’s properties map.

​
Creating Custom Configurators

​
1. Create the Template

Create a YAML file in options/configurators/: 
# options/configurators/my-configurator.yml
files:
  - path: config.yml
    format: yaml
    values:
      server.port: "{{port}}"
      server.name: "{{server-name}}"

  - path: settings.properties
    format: properties
    values:
      max.players: "{{max-players}}"

​
2. Reference in Blueprint

Specify the configurator in your blueprint: 
# blueprints/my-blueprint.yml
name: My Blueprint
configurator: my-configurator
minecraft_version: "1.21"
server_software: paper

​
3. The Serverhost Applies It

During server startup, the workflow calls the ConfiguratorAction: 
# workflows/internal/setup.yml
steps:
  - action: configurator
    configurator: "{{configurator}}"
    dir: "{{server-dir}}"

​
Built-in Configurators

​
paper_velocity

For Paper servers behind Velocity proxy:
  • Sets server port in server.properties
  • Enables Velocity modern forwarding in paper-global.yml
  • Configures forwarding secret
  • Disables BungeeCord mode in spigot.yml

​
paper_bungeecord

For Paper servers behind BungeeCord:
  • Sets server port in server.properties
  • Enables BungeeCord mode in spigot.yml
  • Disables online mode

​
velocity

For Velocity proxy servers:
  • Configures bind port in velocity.toml
  • Sets up modern forwarding
  • Creates forwarding secret file

​
bungeecord

For BungeeCord proxy servers:
  • Configures listener port in config.yml
  • Enables IP forwarding
  • Sets max players

​
Nested Value Paths

For nested configuration structures, use dot notation: 
files:
  - path: config.yml
    format: yaml
    values:
      server.network.port: "{{port}}"
      server.network.host: "0.0.0.0"
      features.enabled.chat: true
This creates: 
server:
  network:
    port: 25565
    host: "0.0.0.0"
features:
  enabled:
    chat: true

​
Troubleshooting

Symptom: Server starts with default config instead of configured values.Solution:
  1. Verify configurator name in blueprint matches file name
  2. Check file path is correct relative to server directory
  3. Review serverhost logs: sc logs serverhost
Symptom: Config contains literal {{port}} instead of actual port.Solution:
  1. Check syntax: {{name}} (double braces, no spaces)
  2. Verify the property exists on the server
  3. For custom properties use: {{$.property-name}}
Symptom: Configurator fails to parse the config file.Cause: Format field doesn’t match actual file type.Solution:
  1. Verify format matches file extension (yaml, json, properties, toml)
  2. Check the template file for syntax errors
  1. Ensure the file exists in the server directory