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

# Templates

> Add plugins, configuration, worlds, and other files to the servers that need them.

Templates define the files a server starts with. Add a file to a template once, and SimpleCloud copies it to every matching server when it starts.

Templates work best for group servers, which start from a fresh directory. If files changed while a server is running must remain after it stops, use a [persistent server](/docs/en/manual/setup/persistent-servers).

## Choose a template folder

Open **Files** in the dashboard, select a serverhost, and open `templates`. Choose the folder by how widely the files should be shared:

* **One group or persistent server:** `templates/{name}/`
* **Servers with a tag:** `templates/_tagged/{tag}/`
* **One server software:** `templates/_every/every_{software}/`
* **All game servers:** `templates/_every/every_server/`
* **All proxies:** `templates/_every/every_proxy/`
* **Every server:** `templates/_every/every/`

For example, files used only by the `lobby` group belong in `templates/lobby/`. A plugin needed by every Paper server belongs in `templates/_every/every_paper/`.

<Tip>
  Use the narrowest folder that includes every server that needs the files. This keeps unrelated servers and templates easier to manage.
</Tip>

## Keep the server's folder structure

Everything below the chosen template folder maps directly to the server directory. Use the same relative path in both places.

For example, this template file:

```text theme={null}
templates/lobby/plugins/Lobby/config.yml
```

becomes this file in a running `lobby` server:

```text theme={null}
running/lobby/lobby-1/plugins/Lobby/config.yml
```

The generated server name, such as `lobby-1`, can differ between starts. The path below that name remains the same.

<Steps>
  <Step title="Open the matching template folder">
    Open the folder for the group, tag, software, or server type you want to change. Create the folder if it does not exist.
  </Step>

  <Step title="Add the files at their server-relative paths">
    To place a plugin in the server's `plugins` folder, create a `plugins` folder in the template and upload the JAR there. Keep any configuration and world folders in the same structure they use inside a running server.
  </Step>

  <Step title="Start a matching server">
    Start a server and open its **Files** page to confirm that the files appear in the expected locations.
  </Step>
</Steps>

## Apply template changes

Group servers receive their matching template files each time they start. A server that is already running does not change, so stop it and start another server after updating a template.

Persistent servers also read their templates when they start, but keep their server directory between starts. A template can add a missing file, but it does not replace a file that the persistent server already has. Edit an existing persistent-server file directly from its **Files** page.

## Reuse generated configuration

Some plugins create their configuration only after their first start. For a group server:

1. Start one server and let the plugin create its files.
2. While the server is still running, open its folder under `running/{group}/{server}/`.
3. Copy or download the generated file, then place it at the same relative path in the group's template.
4. Edit the template copy.
5. Stop the running server and start another one to test the template.

For example, copy:

```text theme={null}
running/lobby/lobby-1/plugins/Lobby/config.yml
```

to:

```text theme={null}
templates/lobby/plugins/Lobby/config.yml
```

<Warning>
  Copy files from a group server before stopping it. SimpleCloud removes that server's `running` directory when it stops.
</Warning>

For a persistent server, its files are stored in `running/persistent/{name}/` and remain after it stops. Edit those files directly unless you want a template to provide a file only when it is missing.

## Share files with tags

Tags let unrelated groups or persistent servers use the same files without duplicating them in each named template.

Create a folder such as `templates/_tagged/minigames/`, then add the `minigames` tag to every group or persistent server that should receive its files. The tag and folder names must match.

## Avoid conflicts between template folders

A server can match several template folders. SimpleCloud copies the matching template folders in this order:

1. `templates/_every/every/`
2. The matching server-type folder, such as `templates/_every/every_server/`
3. The mapped software family, such as `templates/_every/every_paper/` for Purpur
4. The exact software folder, such as `templates/_every/every_purpur/`
5. Each matching folder in `templates/_tagged/`
6. The named folder, such as `templates/lobby/`

If the same relative path appears more than once, the first file copied is kept. Later folders do not replace it. For example, `templates/lobby/server.properties` does not override `templates/_every/every/server.properties`.

Keep each file in only one matching template folder to make the result predictable. Do not rely on the order of multiple matching tag folders that contain the same path.

The `templates/cache/` folder is managed by SimpleCloud and should not be used for your own template files.

## Use templates on multiple serverhosts

Templates belong to the serverhost where they are stored. If a group can run on several serverhosts, each one needs the same template files. Use [Multi-root setup](/docs/en/manual/setup/multi-root) to synchronize the `templates` folder between them.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A file is missing">
    Check that the folder matches the group name, tag, software, or server type. Then confirm that the path below the template folder matches the path you expect inside the server. Start a new group server after making changes.
  </Accordion>

  <Accordion title="A template change does not appear">
    Templates do not change a running server. For a group, stop the current server and start another one. For a persistent server, edit an existing file directly because templates only add files that are missing.
  </Accordion>

  <Accordion title="The server uses a different version of a file">
    Search the other matching template folders for the same relative path. The first matching copy is kept, so remove the duplicate or keep the file in the earlier shared folder.
  </Accordion>

  <Accordion title="A tagged template does not apply">
    Confirm that the tag is assigned to the group or persistent server and that its spelling matches the folder below `templates/_tagged/`.
  </Accordion>

  <Accordion title="The change appears on only one serverhost">
    Synchronize the `templates` folder across every serverhost that can run the group.
  </Accordion>
</AccordionGroup>