> ## Documentation Index
> Fetch the complete documentation index at: https://simplecloud.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurators

> Customize software configuration files before a server starts

Before a server starts, SimpleCloud uses a configurator to write values such as the assigned port and player limit to the server software's configuration files. The dashboard selects a built-in configurator when you create a group or persistent server, so a standard setup needs no extra work.

Create a custom configurator when you need to add settings that the built-in configurator does not manage. Use [templates](/docs/en/manual/setup/templates) instead when you only need to copy the same files to your servers.

<Warning>
  A custom configurator replaces the selected built-in configurator. Keep the built-in settings that your server needs, especially its port and proxy settings.
</Warning>

## Create a custom configurator

This example extends the **Paper/Spigot Standalone** configurator with a difficulty and view distance. If your server connects through a proxy, start with the matching proxy configurator instead.

<Steps>
  <Step title="Create the configurator file">
    On the serverhost, create `options/configurators/paper_survival.yml`:

    ```yaml options/configurators/paper_survival.yml theme={null}
    paths:
      - path: "server.properties"
        type: "PROPERTIES"
        data:
          server-ip: "0.0.0.0"
          server-port: %port%
          max-players: %max-players%
          online-mode: true
          difficulty: "hard"
          view-distance: 10
    ```

    Each `path` is relative to the server's own directory. The file can contain several path entries when you need to configure more than one file.
  </Step>

  <Step title="Select the configurator">
    Open the group or persistent server in the dashboard, then go to **Settings > Blueprint**. Under **Software Configuration**, select **Custom**, enter `paper_survival`, and save.
  </Step>

  <Step title="Apply the changes">
    Restart the group or persistent server. SimpleCloud applies the configurator to every server that uses its blueprint before that server starts.
  </Step>
</Steps>

<Warning>
  If the server can run on multiple serverhosts, add the configurator file to each one.
</Warning>

## Configurator reference

Each entry under `paths` identifies a configuration file, its format, and the values to apply.

<AccordionGroup>
  <Accordion title="Supported file types">
    | Type         | File format     |
    | ------------ | --------------- |
    | `YML`        | YAML            |
    | `JSON`       | JSON            |
    | `TOML`       | TOML            |
    | `PROPERTIES` | Java properties |
    | `TXT`        | Plain text      |

    Structured files keep values that are not specified in the configurator. `TXT` replaces the complete file.
  </Accordion>

  <Accordion title="Available placeholders">
    Use placeholders when a value depends on the server instance.

    | Placeholder                 | Value                           |
    | --------------------------- | ------------------------------- |
    | `%port%`                    | Assigned port                   |
    | `%group%`                   | Group or persistent server name |
    | `%numerical-id%`            | Instance number                 |
    | `%type%`                    | Server or proxy type            |
    | `%min-memory%`              | Minimum memory in MB            |
    | `%max-memory%`              | Maximum memory in MB            |
    | `%max-players%`             | Player limit                    |
    | `%forwarding-secret%`       | Proxy forwarding secret         |
    | `%velocity-config-version%` | Velocity configuration version  |

    Quote placeholders whose resulting value must be text:

    ```yaml theme={null}
    server-name: "%group%"
    server-port: %port%
    ```

    Custom properties from the group or persistent server are also available as placeholders. For example, a property named `motd` can be used as `%motd%`.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The configurator cannot be found">
    Confirm that `options/configurators/{name}.yml` exists on every serverhost that can run the server. The custom name in the dashboard must match the filename without `.yml`.
  </Accordion>

  <Accordion title="A setting does not change">
    Restart the server first. If the value still does not change, check that `path` is relative to the server directory, `type` matches the file format, and the setting is nested correctly under `data`.
  </Accordion>

  <Accordion title="A placeholder remains in the file">
    Check the placeholder spelling and use percent syntax such as `%port%`. For a custom placeholder, add a property with the same name to the group or persistent server.
  </Accordion>

  <Accordion title="The server does not start after selecting the configurator">
    Check the serverhost log for a configurator error. Common causes are invalid YAML, an unsupported `type`, or a value whose structure does not match the target file.
  </Accordion>
</AccordionGroup>