Structure

SimpleCloud v3 has a new and more customizable structure. We have encapsulated all the core components to make it easier to extend your setup. This means you can easily replace all our droplets and plugins with your own implementations.

Key Components

• Controller: The heart of v3, managing server groups, online servers, and communicating with Server Hosts.
• CLI (Command Line Interface): A lightweight interface to connect to the Controller and manage your Cloud components. With the CLI, you can send commands to the controller or install and manage droplets.
• Server Host Droplet: Handles server startup/shutdown with templates, running on Screens or Docker containers.
• Droplets & Plugins:
  • Droplets: Microservices for non-Minecraft tasks like player data (Player Droplet) or stats (Metrics Droplet).
  • Plugins: Enhance server features with Proxy (e.g., Notify, CloudCommand) or Server Plugins (e.g., Signs, NPCs).

File structure

SimpleCloud has its core components that are needed, but they can be installed and used however you want. This means theoretically you can use any file structure you want. However, we don't recommend that and advise you to structure your files like this, as it works best in our experience and makes it easier to extend your setup with our CLI.

.
├── components
│   ├── .secrets
│   ├── auto-updater
│   │   ├── auto-updater.jar
│   │   ├── application.yml
│   │   ├── versions.yml
│   │   └── current_version.txt
│   ├── controller
│   │   ├── application.yml
│   │   ├── controller.properties
│   │   ├── controller-runtime.jar
│   │   ├── current_version.txt
│   │   └── database.db
│   ├── serverhost
│   │   ├── application.yml
│   │   ├── current_version.txt
│   │   ├── serverhost.properties
│   │   └── serverhost-runtime.jar
│   ├── libs
│   │   └── ...
│   └── scripts
│       ├── components
│       │   ├── controller.lua
│       │   ├── envoy.lua
│       │   └── serverhost.lua
│       ├── lib
│       │   ├── component.lua
│       │   ├── process.lua
│       │   └── auto_updater.lua
│       └── common.lua
├── groups
│   ├── proxy.yml
│   └── lobby.yml
├── templates
│   ├── proxy
│   │   └── ...
│   └── lobby
│       └── ...
└── running
├── proxy
│   └── proxy-1
│       └── ...
└── lobby
└── lobby-1
└── ...

Understanding Components

SimpleCloud v3 is structured into components - a broad category that includes both core system elements and dropelts. These components serve as the building blocks of the system, encompassing essential elements like the Controller, Envoy (necessary for the Dashboard), the Auto-updater, and the CLI, alongside droplets.

We chose to use the term "components" to reflect this inclusive scope. This generic terminology allows us to consistently refer to all parts of the system, whether they are core elements or droplets.

Auto-Updater

The auto-updater is a crucial part of SimpleCloud, ensuring that all components stay up-to-date with the latest features and security patches. It resides in the components/auto-updater directory and manages version control through versions.yml. The auto-updater is configured through its own application.yml file and updates itself before updating other components.

Scripts

SimpleCloud uses Lua scripts as a dynamic component management system that enables seamless integration between the CLI and various components. When you execute a CLI command, these scripts act as bridges between the components and the CLI, providing standardized methods for component control.

How Scripts Work

When a CLI command is executed, it runs all scripts in the components/scripts directory. Each script must return three essential methods that the CLI can call:

• start: Launches the component
• stop: Terminates the component
• status: Checks the component's current state

This design makes the CLI dynamically extendable - you can integrate any standalone program (component or droplet) into SimpleCloud by creating a corresponding Lua script that implements these methods.

Script Structure

The scripts are organized into two main directories:

• components/scripts/components/: Contains individual component scripts
• components/scripts/lib/: Contains shared libraries and utilities

Example Script

Here's an example of how a component script looks using our component factory:

local component = require("component")

return component.create({
    name = "controller",
    session = "simplecloud-controller",
    jar = "controller-runtime.jar"
})

component.create returns the start, stop, and status methods that the CLI can call to manage the component.

Creating Custom Components

You can easily create new components by adding a new Lua script in the components/scripts/components directory:

local component = require("component")

return component.create({
    name = "custom",
    session = "simplecloud-custom",
    jar = "custom-runtime.jar",
    -- Optional: Custom Java options
    java_opts = {
        "-Xmx1g",
        "-Xms512m",
        "-XX:+UseG1GC",
        -- Add more options as needed
    }
})

Creating Components that are not based on Java

We also support creating components that are not based on Java. It's basically the same as above, but you need to specify the command field instead of jar. Here's an example on how to do so:

local component = require("component")

return component.create({
    name = "envoy",
    session = "simplecloud-envoy",
    command = "envoy -c envoy-bootstrap.yaml"
})

Auto-Updater Configuration

The auto-updater has its own configuration:

github-repository: simplecloudapp/v3-releases
files:
  - release-file: controller-runtime.jar
    output-file: ../controller/controller-runtime.jar
  - release-file: controller-api.jar
    output-file: ../libs/controller-api.jar

Component Properties

Every component is built and configured to use properties files for configuration. The properties file is located in the components folder and named {component}.properties.

If you want to create an own component, feel free to structure it as you like. We like to use a .properties file for configuration and a .yml file for the configuration of the auto-updater.

Here's an example of a properties file:

DATABASE_URL=jdbc:sqlite:database.db
GROUPS_PATH=../../groups
# GRPC Uncomment and change this if you want to change grpc defintions
GRPC_HOST=0.0.0.0
# GRPC_PORT=5816
# PUBSUB Uncomment and change this if you want to run pubsub on another port
# PUBSUB_GRPC_PORT=5817
AUTH_SECRET_PATH=../.secrets/auth.secret

Cross-Platform Support

The scripts automatically handle platform-specific differences:

• Unix: Uses screen sessions for process management
• Windows: Uses background processes and batch files

What's next?

You have understood the basic structure of SimpleCloud. Here are a few links that might be helpful as you continue to explore SimpleCloud:

• Learn about the Controller
• Learn about the CLI
• Learn about the Dashboard
• Understand the Server Host Droplet