Skip to main content
Templates are the file structures that get copied to new server instances. They contain your server’s plugins, configurations, and any default world files.

​
How Templates Work

When SimpleCloud starts a server, templates are applied in a specific order. Each layer can add or overwrite files from previous layers, giving you flexible control over your server configurations.
Need persistent data that survives restarts? Use a Persistent Server instead of a group.

​
Template Directory Structure

templates
every
Applied to ALL servers
_tagged

​
Template Hierarchy

Templates are applied in order. Later templates overwrite earlier ones:
OrderDirectoryDescription
1every/Base files for all servers
2every_{type}/Type-specific (every_proxy/, every_server/)
3every_{software}/Software-specific (every_paper/, every_velocity/)
4_tagged/{tag}/Tag-based templates
5{group-name}/Group-specific templates
6cache/{group}/Cached files from previous runs

​
Example: How a Lobby Server Gets Built

For a server in the lobby group with Paper software and the premium tag:
  1. every/ - Base plugins like SimpleCloud-Plugin
  2. every_server/ - Common server configs (not proxy)
  3. every_paper/ - Paper-specific settings
  4. _tagged/premium/ - Premium-only plugins/configs
  5. lobby/ - Lobby-specific world and plugins

​
Base Template: every/

The every/ folder contains files applied to all servers - proxies and game servers alike. Use this for:
  • SimpleCloud plugins that every server needs
  • Universal configuration files
  • Shared resources
templates
every
plugins
simplecloud-plugin.jar

​
Type Templates: every_{type}/

Apply files based on server type:
  • every_proxy/ - All proxy servers (Velocity, BungeeCord)
  • every_server/ - All game servers (Paper, Spigot, etc.)
templates
every_proxy
plugins
proxy-essentials.jar
every_server
plugins
worldedit.jar

​
Software Templates: every_{software}/

Apply files based on server software:
  • every_paper/ - All Paper servers
  • every_velocity/ - All Velocity proxies
  • every_spigot/ - All Spigot servers
templates
every_paper
plugins
paper-specific-plugin.jar

​
Tagged Templates: _tagged/{tag}/

Tags let you share configurations across multiple groups. Assign tags to groups, and any server in those groups gets the tagged template applied.

​
Setting Up Tags

  1. Create a tag folder in templates/_tagged/:
templates
_tagged
minigames
plugins
minigame-core.jar
premium
plugins
premium-features.jar
  1. Assign tags to your groups via CLI or API when creating/updating the group.

​
Use Cases for Tags

TagPurpose
minigamesShared minigame plugins (BedWars, SkyWars, etc.)
premiumPremium-only features
developmentDebug plugins for dev servers
pvpCombat-related plugins

​
Group-Specific Templates

The traditional template folder named after your group:
templates
bedwars
plugins
bedwars-plugin.jar
world
level.dat
region
This is the most specific level - files here override everything else.

​
Managing Templates

​
Adding Plugins

Place plugin JARs in the appropriate template folder: 
# For all servers
cp simplecloud-plugin.jar templates/every/plugins/

# For all Paper servers
cp paper-plugin.jar templates/every_paper/plugins/

# For a specific group
cp bedwars.jar templates/bedwars/plugins/
New servers will include the plugin. Existing servers need a restart.

​
Configuring Plugins

  1. Start a server once to generate default configs
  2. Stop the server
  3. Copy configs from the running/ directory back to your template
  4. Edit as needed

​
World Files

Place world folders in the template for a default map:
templates
bedwars
world
level.dat
region
Every new server starts with this world. Changes during gameplay are lost when the server stops.

​
Caching

SimpleCloud caches certain files to speed up server starts:
  • Plugin remapping data (Paper)
  • Downloaded dependencies
  • Generated files
The cache is stored in templates/cache/{group}/ and automatically managed.
If you’re having issues with outdated files, you can clear the cache folder for a group to force a fresh setup.

​
When to Use Each Template Level

Template LevelUse For
every/Plugins needed on every server
every_{type}/Proxy-only or server-only plugins
every_{software}/Software-specific plugins/configs
_tagged/Shared features across multiple groups
{group}/Group-specific files and worlds

​
Templates and Persistent Servers

Templates are used for both group servers and persistent servers. The workflow runs on every server start, applying templates in the hierarchy order.

​
Key Difference

AspectGroup ServersPersistent Servers
DirectoryCreated fresh, deleted on stopPermanent, survives restarts
Template applicationOverwrites everythingMerges with existing files
World dataLost on stopKept between restarts
Use caseMinigames, lobbiesSMP, Skyblock, builds

​
How It Works for Persistent Servers

On each restart of a persistent server:
  1. The workflow runs and applies templates
  2. New files from templates are added
  3. Existing files in the server directory are not overwritten (unless replace: true)
  4. World data and player data remain intact
If you update a plugin in your template, the persistent server won’t automatically get the new version unless you manually delete the old plugin from the server’s directory.

​
When to Use What

ScenarioRecommendation
Minigames (BedWars, SkyWars)Group - fresh map each game
Lobby serversGroup - no persistent data needed
ProxiesGroup - configuration only
Skyblock, SMP, CitybuildPersistent Server - keeps world data

​
Troubleshooting

Symptom: New servers don’t include your template changes.Solution:
  1. Verify files are in the correct template directory
  2. Check if a later template is overwriting (hierarchy order)
  3. Clear cache: rm -rf templates/cache/{group}/
  4. Start a new server (running servers don’t update)
Symptom: Template changes only affect new servers, not existing ones.Cause: Templates are applied at server creation, not during runtime.Solution:
  • Group servers: Stop the old server, start a new one
  • Persistent servers: Manually update files or delete specific files so templates can replace them
Symptom: Plugin in template doesn’t load on server.Solution:
  1. Check file permissions on the JAR
  2. Verify the file exists in server’s plugins/ directory
  3. Check server logs for load errors
  4. Verify plugin compatibility with server software
Symptom: Updated plugins or configs not applying to servers.Cause: Old files cached in templates/cache/{group}/.Solution:
rm -rf templates/cache/{group}/
New servers will rebuild from templates.
Symptom: Files from _tagged/ folder not appearing on servers.Solution:
  1. Verify tag is assigned to the group in settings
  2. Check folder name matches exactly (case-sensitive)
  3. Ensure workflow includes for-each step for tags
Symptom: Your config keeps getting replaced by another template.Cause: Template hierarchy applies in order: every/ → every_{type}/ → every_{software}/ → _tagged/ → {group}/Solution:
  • Move your file to a more specific template level
  • Or use replace: false in a custom workflow step