> ## 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.

# Configurators

> Automatic server configuration based on server software

## 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

```yaml theme={null}
# 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

```yaml theme={null}
# 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

| Format       | Extension   | Description                 |
| ------------ | ----------- | --------------------------- |
| `yaml`       | .yml, .yaml | YAML configuration files    |
| `json`       | .json       | JSON configuration files    |
| `properties` | .properties | Java properties files       |
| `toml`       | .toml       | TOML configuration files    |
| `text`       | any         | Plain text file replacement |

## Placeholders

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

### Server Properties

| Placeholder       | Description                   |
| ----------------- | ----------------------------- |
| `{{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

| Placeholder             | Description                |
| ----------------------- | -------------------------- |
| `{{forwarding-secret}}` | Velocity forwarding secret |
| `{{server-ip}}`         | Server IP address          |
| `{{network-id}}`        | Network identifier         |

### Type Properties

| Placeholder    | Description                                 |
| -------------- | ------------------------------------------- |
| `{{type}}`     | Server type (`proxy`, `server`, `lobby`)    |
| `{{software}}` | Server software (`paper`, `velocity`, etc.) |

### Custom Properties

Access custom properties defined in the group:

```yaml theme={null}
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/`:

```yaml theme={null}
# 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:

```yaml theme={null}
# 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`:

```yaml theme={null}
# 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:

```yaml theme={null}
files:
  - path: config.yml
    format: yaml
    values:
      server.network.port: "{{port}}"
      server.network.host: "0.0.0.0"
      features.enabled.chat: true
```

This creates:

```yaml theme={null}
server:
  network:
    port: 25565
    host: "0.0.0.0"
features:
  enabled:
    chat: true
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Configuration not applied">
    **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`
  </Accordion>

  <Accordion title="Placeholder not replaced">
    **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}}`
  </Accordion>

  <Accordion title="Wrong file format error">
    **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
  </Accordion>
</AccordionGroup>

3. Ensure the file exists in the server directory