Templates

Templates in SimpleCloud v3 provide a powerful and flexible way to manage server configurations. Unlike v2's fixed directory structure, templates now use an action-based system that allows for dynamic file management and advanced templating features.

Understanding Templates

Templates consist of actions that are executed on certain triggers. Each action stands for a sorted list of references to other actions and standard behaviours, which are configurable with settings.

Template Triggers

Actions can be specified under each template trigger. These will then be executed in order.

Template Structure

Templates are defined in YAML files located in /droplets/serverhost-droplet/templates/definitions or its subdirectories. The template id of a YAML file is the name of the file (without extension). Each template defines which actions should be executed on what trigger:

when:
  start:
    - default/setup # references the default/setup action
    - ...
  stop:
    - default/delete # references the default/delete action
    - ...

Context

Each template trigger will create its own context and run in it. This means that actions can also influence each other.

Actions

Actions are reusable components for doing something (e.g. copy files from template folder to server). You can reference actions in other actions and in templates. This allows for creating a reusable toolchain, keeping config files minimal and extension of existing configs easy. All actions are located in /droplets/serverhost-droplet/templates/actions or its subdirectories. All actions support placeholder matching like %my-placeholder%.

Action referencing

Actions can be referenced in other actions or in templates. An actions ref name consists of the YAML file name it is located in and the name of the action. For example, an action in utils.yml called init-placeholders will have the ref utils/init-placeholders.

Config structure

An action in config files contains of a sorted list of action objects and references.

Action objects

Action objects consist of the type field, which will set the action type executed, and data that action requires.

cache-pull-libs:
  - from: "%libs-dir%"
    to: "%server-dir%/libraries"
    type: "copy"

References

A reference to another action can be made by setting ref to a action reference.

my-action:
    - ref: other/my-other-action

Mixed example

cache-pull:
- from: "%templates%/cache/%group%"
to: "%server-dir%"
type: "copy"
- ref: cache-pull-libs

cache-pull-libs:
- from: "%libs-dir%"
to: "%server-dir%/libraries"
type: "copy"

cache-push:
- ref: cache-push-paper
- ref: cache-push-spigot

cache-push-paper:
- from: "%server-dir%/plugins/.paper-remapped/"
to: "%templates%/cache/%group%/plugins/.paper-remapped"
type: "copy"

cache-push-spigot:
- from: "%server-dir%/libraries"
to: "%templates%/cache/%group%/libraries"
type: "copy"
- from: "%server-dir%/versions"
to: "%templates%/cache/%group%/versions"
type: "copy"

Placeholders

Actions support dynamic placeholders, these can also be altered by the placeholder action:

Action data

This is a list of all action data forms corresponding to the action type.

copy

This will copy files from a to b

configurate

This will configure servers using configurators

delete

This delete a file or folder on the specified path

infer

This infers data from the current server into placeholders

placeholder

This changes placeholders

modrinth_download

download

compress

decompress

Best Practices

1. Template Organization

• Use clear template naming
• Leverage referencing to keep files minimal and clean
• Document actions and references

2. Path Management

• Use relative paths when possible
• Leverage path variables for flexibility
• Keep consistent directory structure

What's Next?

Here are a few links that might be helpful as you continue to explore SimpleCloud:

• Learn about Server Groups
• Learn about Servers
• Learn about the Server Host droplet