# AutoStartStop

> AutoStartStop is a Velocity plugin for automated server management that lets you define rule-based automation with triggers, conditions, and actions.

AutoStartStop is a Velocity proxy plugin that automates Minecraft server management through a YAML-based, rule-driven configuration system. You define rules composed of triggers (player connections, cron schedules, proxy lifecycle, pings, empty server detection etc.), optional conditions (server status, player counts, comparisons etc.), and actions (start/stop/restart servers, connect/disconnect players, send messages, manage bossbars, customize ping responses, execute shell commands etc.). It supports multiple server control APIs (Shell commands, AMP API, Pterodactyl Panel API etc.). Built-in templates provide ready-to-use patterns for common scenarios like auto-start on connect, auto-stop when idle, and custom MOTD responses etc. All configuration lives in a single config.yml file with dynamic variable support.


# Overview

# AutoStartStop

AutoStartStop is a **Velocity** plugin for **automated server management** using a flexible, rule-based system. You define **rules** that react to **triggers** (events like proxy start, player connect, cron schedules, etc.) and execute **actions** (start/stop servers, connect/disconnect players, log messages, and more), optionally gated by **conditions**.

## How it works

AutoStartStop evaluates your configuration as:

- **Settings**: Global plugin settings (timeouts, intervals, etc.).
- **Servers**: Which backend servers are managed, and how to control them (Shell, AMP, or Pterodactyl API).
- **Rules**: What should happen under which circumstances.
  - **Triggers**: When should a rule fire? (e.g. `connection`, `proxy_start`, `cron`, `empty_server`)
  - **Conditions** *(optional)*: Should it run right now? (e.g. “server is offline”, “player count > 0”)
  - **Actions**: What should happen? (e.g. `start`, `stop`, `send_message`, `disconnect`)

Here’s the overall `config.yml` shape at a glance:

```
settings: { ... }  # Global plugin settings (timeouts, intervals, etc.).
defaults: { ... }  # Global defaults for server configurations.
servers: { ... }   # Which backend servers are managed, and how to control them.
rules: { ... }     # What should happen under which circumstances.
```

## Key features

- **Rule-based automation**: Define rules that react to triggers and execute actions
- **Multiple control APIs**: Support for Shell commands, AMP API, and Pterodactyl Panel API
- **Flexible triggers**: Proxy lifecycle, player connections, cron schedules, empty server detection, ping/MOTD requests
- **Built-in templates**: Pre-configured templates for common automation patterns

## Example use cases

- **Auto-start on demand**: Start a server when a player tries to connect and it’s offline.
- **Auto-stop when idle**: Stop game servers after they’ve been empty for a duration.
- **Scheduled tasks**: Nightly restart, backups, or maintenance actions via cron rules.
- **Smarter server list**: Adjust ping/MOTD behavior while a server is online/offline.
- **Graceful shutdown**: On proxy shutdown, stop selected servers with warning messages to players.
- **Scheduled rewards**: Send hourly rewards or messages to players using cron triggers.

## AI-friendly documentation

This documentation is available in an LLM-friendly format following the [llms.txt](https://llmstxt.org/) standard. You can use these files with any AI assistant (ChatGPT, Claude, Gemini, etc.) to ask questions about AutoStartStop or generate configurations:

- **[llms.txt](https://beyenilmez.github.io/autostartstop/llms.txt)**: Structured index of all documentation pages
- **[llms-full.txt](https://beyenilmez.github.io/autostartstop/llms-full.txt)**: Full documentation content in a single file

Generate configurations with AI

Copy the [llms-full.txt](https://beyenilmez.github.io/autostartstop/llms-full.txt) URL and paste it into your preferred AI assistant, then ask it to help you create or troubleshoot your `config.yml`.

## Statistics

This plugin uses [bStats](https://bstats.org/docs/server-owners) to collect anonymous usage statistics. You can opt out by editing `plugins/bStats/config.txt`.
# Getting Started

# Quick Start

Follow these steps to get AutoStartStop working in minutes. This guide will help you set up your first automation rule.

## Step 1: Install AutoStartStop

If you haven't installed AutoStartStop yet, see the [Installation](https://beyenilmez.github.io/autostartstop/getting-started/installation.html) guide.

After installation, the plugin will create a configuration file at `plugins/autostartstop/config.yml`.

## Step 2: Configure Your Server

Open `plugins/autostartstop/config.yml` and configure your server. You can find detailed information about server configuration in the [Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html) documentation.

## Step 3: Create Your First Rule

Add a rule to automate server management. For common patterns like "start server on connection", you can check out the [Rule Templates](https://beyenilmez.github.io/autostartstop/rule-templates/index.html) page.

If you want to understand how rules work, see [Basic Concepts](https://beyenilmez.github.io/autostartstop/getting-started/basic-concepts.html) for an explanation of triggers, conditions, and actions.

## Step 4: Reload Configuration

After making changes to `config.yml`, reload the configuration:

```
/ass reload
```

For more information about commands, see [Commands](https://beyenilmez.github.io/autostartstop/commands.html).

## Step 5: Test

Test your configuration to make sure everything works as expected.

## Next Steps

- [Commands](https://beyenilmez.github.io/autostartstop/commands.html) - Learn about available commands and permissions
- [Basic Concepts](https://beyenilmez.github.io/autostartstop/getting-started/basic-concepts.html) - Understand how rules, triggers, and actions work
- [Configuration](https://beyenilmez.github.io/autostartstop/configuration/index.html) - Learn about all configuration options
- [Rule Templates](https://beyenilmez.github.io/autostartstop/rule-templates/index.html) - Explore pre-built automation patterns
- [Examples](https://beyenilmez.github.io/autostartstop/examples/index.html) - Explore examples of how to use AutoStartStop

# Installation

## Requirements

- **Velocity 3.4.0** or higher
- **Java 21** or higher

## Steps

### 1. Download

Download the AutoStartStop JAR from one of the available platforms:

- [GitHub Releases](https://github.com/beyenilmez/autostartstop/releases)
- [Modrinth](https://modrinth.com/plugin/autostartstop)
- [Hangar](https://hangar.papermc.io/beyenilmez/AutoStartStop)

### 2. Install

To install AutoStartStop, place the JAR file in your Velocity server’s `plugins/` folder and restart Velocity if it is already running:

```
velocity/
└── plugins/
    └── AutoStartStop-<version>.jar
```

On first run, the plugin will create its default configuration file:

```
velocity/
└── plugins/
    └── autostartstop/
        └── config.yml
```

### 3. Verify

You can verify the installation by checking the console for the following message:

```
AutoStartStop enabled successfully
```

No success message?

If you don't see the message, confirm the plugin JAR is in `plugins/`, restart Velocity, and check the console for any AutoStartStop-related errors during startup.

## What's next

- [Basic Concepts](https://beyenilmez.github.io/autostartstop/getting-started/basic-concepts.html) - Learn how rules, triggers, conditions, and actions work
- [Configuration](https://beyenilmez.github.io/autostartstop/configuration/index.html) - Configure servers and rules
- [Rule Templates](https://beyenilmez.github.io/autostartstop/rule-templates/index.html) - Use pre-built templates for common patterns

# Basic Concepts

AutoStartStop uses a **rule-based automation system** to manage your servers. Understanding the core concepts will help you configure the plugin effectively.

## Overview

AutoStartStop works by defining **rules** that react to **triggers** and execute **actions**, optionally filtered by **conditions**. Think of it as:

```
Trigger → [Condition?] → Action
```

When a trigger fires, conditions are checked (if any), and if they pass, actions are executed.

## Core Components

### Rules

**Rules** are the foundation of AutoStartStop. Each rule defines what should happen when certain events occur.

A rule consists of:

- **Triggers**: When should this rule fire?
- **Conditions** *(optional)*: Should it execute right now?
- **Actions**: What should happen?

```
rules:
  my_rule:
    triggers: [ ... ]    # When to fire
    conditions: { ... }  # Optional: Should it run?
    action: [ ... ]      # What to do
```

See [Rules](https://beyenilmez.github.io/autostartstop/configuration/rules.html) for detailed documentation on rule configuration.

### Triggers

**Triggers** define **when** a rule should fire. They represent events that occur in your server environment.

Common triggers include:

- **`proxy_start`**: When the Velocity proxy starts
- **`connection`**: When a player connects to a server
- **`cron`**: When a scheduled time is reached
- **`manual`**: When a manual trigger is used

A rule can have multiple triggers. The rule fires when **any** of its triggers activate.

```
rules:
  example:
    triggers:
      - proxy_start:  # Fire on proxy start
      - connection:   # OR fire on player connection
          server: survival
```

See [Triggers](https://beyenilmez.github.io/autostartstop/triggers/index.html) for a complete list of available triggers and their configuration options.

### Conditions

**Conditions** are optional filters that determine **if** a rule should execute. They let you add logic like "only if the server is offline" or "only if player count is greater than 5".

Common conditions include:

- **`server_status`**: Check if a server is online/offline
- **`player_count`**: Check the number of players on a server
- **`string_equals`**: Compare two strings
- **`number_compare`**: Compare numeric values

By default, **all** conditions must pass (AND logic). You can change this to **any** (OR logic).

```
rules:
  example:
    triggers:
      - connection:
          server: survival
    conditions:
      mode: all  # All conditions must pass
      checks:
        - server_status:
            server: survival
            status: offline  # Only if server is offline
```

Inverting conditions

You can invert any condition using `invert: true` to reverse its logic.

See [Conditions](https://beyenilmez.github.io/autostartstop/conditions/index.html) for detailed documentation on all available conditions and their options.

### Actions

**Actions** define **what** should happen when a rule fires. They are executed sequentially in the order they are defined.

Common actions include:

- **`start`**: Start a server
- **`connect`**: Connect a player to a server
- **`send_message`**: Send a message to a player
- **`respond_ping`**: Respond to a ping request with a custom MOTD
- **`if`**: Conditional action execution
- **`sleep`**: Wait for a duration

```
rules:
  auto_start_on_connection:
    triggers:
      - connection:
          deny_connection: true
          server_list:
            mode: whitelist
            servers:
              - survival
    action:
      - start:
          server: ${connection.server.name}
      - while:
        timeout: 2m
        checks:
          - server_status:
              server: ${connection.server.name}
              status: offline
      - allow_connection:
```

See [Actions](https://beyenilmez.github.io/autostartstop/actions/index.html) for a complete list of available actions and their configuration options.

### Servers

**Servers** define which backend servers AutoStartStop can manage and how to control them.

Each server configuration includes:

- **`virtual_host`**: The hostname used to connect to this server
- **`control_api`**: How to control the server (Shell commands, AMP API, or Pterodactyl API)
- **`ping`**: Settings for checking server status
- **`startup_timer`**: Settings for tracking server startup progress

```
servers:
  survival:
    virtual_host: play.example.com
    control_api:
      type: shell
      start_command: "systemctl start minecraft-survival"
      stop_command: "systemctl stop minecraft-survival"
```

See [Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html) for detailed server configuration options, and [Control API](https://beyenilmez.github.io/autostartstop/control-api/index.html) for information about control methods.

### Templates

**Templates** are pre-built rule configurations for common automation patterns. They simplify configuration by providing ready-to-use setups.

Available templates:

- **`start_on_proxy_start`**: Start servers when the proxy starts
- **`stop_on_proxy_shutdown`**: Stop servers when the proxy shuts down
- **`start_on_connection`**: Start a server when a player tries to connect
- **`stop_on_empty`**: Stop a server after it's been empty for a duration
- **`respond_ping`**: Customize ping/MOTD responses

Instead of manually defining triggers, conditions, and actions, you can use a template:

```
rules:
  auto_start:
    template: 'start_on_connection'
    servers: ['survival']
    mode: waiting_server
    waiting_server:
      server: limbo
```

See [Rule Templates](https://beyenilmez.github.io/autostartstop/rule-templates/index.html) for a complete list of available templates and their configuration options.

## How It All Works Together

Here's a complete example that demonstrates all concepts:

```
servers:
  survival:  # Define a managed backend server named "survival"
    virtual_host: play.example.com  # Hostname players use to connect
    control_api:
      type: shell  # Use shell commands to control this server
      start_command: "systemctl start minecraft-survival"  # Command to start the server
      stop_command: "systemctl stop minecraft-survival"    # Command to stop the server

rules:
  auto_start_survival:  # Rule for starting "survival" server when a player connects
    triggers:
      - connection:  # Trigger on player connection
          deny_connection: true  # Initially deny connection (until server is ready)
          server_list:
            mode: whitelist  # Only act for specific servers
            servers:
              - survival     # Only "survival" server
    conditions:
      checks:
        - server_status:  # Only run if server is currently offline
            server: survival
            status: offline
    action:
      - start:           # Start the server
          server: survival
      - while:           # Wait until server is online (timeout: 2 minutes)
        timeout: 2m
        checks:
          - server_status:
              server: survival
              status: offline
      - allow_connection:    # Allow the previously denied connection so player can join
          connection: ${connection}
          server: ${connection.server}
```

**What happens:**

1. A player tries to connect to the `survival` server → **Trigger** fires
1. The plugin checks if `survival` is offline → **Condition** is evaluated
1. If the condition passes (server is offline), the **Actions** execute:
   - Start the server
   - Wait until the server is online
   - Allow the player to connect

## Next Steps

Now that you understand the basic concepts, you can:

- Learn how to [configure your first server](https://beyenilmez.github.io/autostartstop/configuration/servers.html)
- Explore available [triggers](https://beyenilmez.github.io/autostartstop/triggers/index.html), [conditions](https://beyenilmez.github.io/autostartstop/conditions/index.html), and [actions](https://beyenilmez.github.io/autostartstop/actions/index.html)
- Use [rule templates](https://beyenilmez.github.io/autostartstop/rule-templates/index.html) for common patterns
- Read the [configuration guide](https://beyenilmez.github.io/autostartstop/configuration/index.html) for detailed options
- Explore [examples](https://beyenilmez.github.io/autostartstop/examples/index.html) of how to use AutoStartStop
# Commands

# Commands

AutoStartStop provides commands for managing the plugin. All commands can be used with `/autostartstop` or `/ass`.

## Available commands

| Command                                                                  | Permission                      | Description                     |
| ------------------------------------------------------------------------ | ------------------------------- | ------------------------------- |
| `/autostartstop` or `/ass`                                               | `autostartstop.command`         | Shows available commands        |
| `/autostartstop reload` or `/ass reload`                                 | `autostartstop.command.reload`  | Reloads the configuration file  |
| `/autostartstop trigger <id> [args...]` or `/ass trigger <id> [args...]` | `autostartstop.command.trigger` | Manually fires a manual trigger |
# Configuration

# Configuration

AutoStartStop uses a single YAML configuration file located at:

```
plugins/autostartstop/config.yml
```

The configuration file is automatically created on first plugin startup with default values.

## Configuration structure

The `config.yml` file consists of several main sections:

```
version: 1         # Configuration version (do not modify)

settings: { ... }  # Global plugin settings
defaults: { ... }  # Default values for server configurations
servers: { ... }   # Server definitions and control API settings
rules: { ... }     # Automation rules (triggers, conditions, actions)
```

## Reloading configuration

After editing `config.yml`, reload the configuration using:

```
/autostartstop reload
```

Or use the alias:

```
/ass reload
```

Alternatively, you can restart Velocity to load the new configuration.

For detailed information about all available commands, see [Commands](https://beyenilmez.github.io/autostartstop/commands.html).

## Configuration sections

- **[Settings](https://beyenilmez.github.io/autostartstop/configuration/settings.html)**: Global plugin settings (timeouts, intervals, etc.)
- **[Defaults](https://beyenilmez.github.io/autostartstop/configuration/defaults.html)**: Default values merged into all server configurations
- **[Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html)**: Define which servers to manage and how to control them (Shell, AMP, or Pterodactyl API)
- **[Rules](https://beyenilmez.github.io/autostartstop/configuration/rules.html)**: Automation rules that execute actions based on triggers and conditions

## Next Steps

- **[Examples](https://beyenilmez.github.io/autostartstop/examples/index.html)**: Example configurations for common use cases

# Settings

The `settings:` section contains global plugin settings that affect overall behavior.

## Available settings

```
settings:
  shutdown_timeout: 30s            # Maximum time to wait for pending actions during proxy shutdown
  empty_server_check_interval: 5m  # Interval for checking if servers are empty (for empty_server trigger)
  motd_cache_interval: 15m         # Interval for caching MOTD responses (for respond_ping action)
  check_for_updates: true          # Check for plugin updates on startup
```

## Setting descriptions

### `shutdown_timeout`

Maximum time to wait for pending actions to complete during proxy shutdown.

- **Format**: Duration (e.g., `30s`, `2m`, `1h`)
- **Default**: `30s`

If actions are still running when this timeout is reached, they will be interrupted.

### `empty_server_check_interval`

Interval for checking if servers are empty (used by the `empty_server` trigger).

- **Format**: Duration (e.g., `5m`, `10m`, `1h`)
- **Default**: `5m`
- **Disable periodic checks**: Set to `0`

This interval determines how often the plugin checks for empty servers. The interval can be kept high since the plugin also detects empty servers when players disconnect. This check is mainly for servers that start without any player activity.

### `motd_cache_interval`

Interval for caching MOTD (Message of the Day) responses for virtual hosts (used by the `respond_ping` action).

- **Format**: Duration (e.g., `15m`, `30m`, `1h`)
- **Default**: `15m`
- **Disable interval-based caching**: Set to `0`

MOTD responses are cached in two scenarios:

1. **Interval-based**: Periodically at the configured interval
1. **Event-based**: When a server is stopped by the plugin

If `motd_cache_interval` is set to `0`, only event-based caching (when the plugin stops a server) is performed, and interval-based caching is disabled.

Caching MOTD allows you to respond with the same MOTD for a virtual host even if the server is offline.

### `check_for_updates`

Whether to check for plugin updates on startup.

- **Type**: Boolean
- **Default**: `true`

When enabled, the plugin checks for a newer version when the proxy starts. If an update is available, a visible message is logged with the current version and the new version. Set to `false` to disable the startup update check.

# Defaults

The `defaults:` section defines global default values that are merged into all server configurations. This allows you to set common settings once instead of repeating them for each server.

## Default structure

```
defaults:
  server:
    control_api: { ... }
    ping: { ... }
    startup_timer: { ... }
```

See the [Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html) page for detailed information about these settings.

## How defaults work

Default values are merged with individual server configurations. If a server doesn't specify a value, the default is used. If a server specifies a value, it overrides the default.

Example:

```
defaults:
  # Define common settings for all servers here
  server:
    control_api:
      type: 'amp'
      ads_url: 'http://localhost:8080/'
      username: 'instance_management_bot'
      password: 'your_password'

servers:
  # You only need to specify instance_id for these servers since other
  # settings are already defined in the defaults.
  lobby:
    control_api:
      instance_id: 'MinecraftLobby01'

  limbo:
    control_api:
      instance_id: 'MinecraftLimbo01'

  # You can override the default settings if needed
  survival:
    control_api:
      type: 'shell'
      start_command: './start.sh'
      stop_command: './stop.sh'
      working_directory: '/path/to/server'
```

# Servers

The `servers:` section defines which backend servers AutoStartStop can manage and how to control them.

## Overview

For full functionality, define servers in this plugin's `servers:` section (in `config.yml`). Some plugin features only work when servers are configured here.

## Server configuration structure

```
servers:
  <server_name>:
    virtual_host: <hostname>  # Virtual host
    control_api: { ... }      # Control API configuration
    ping: { ... }             # Ping settings
    startup_timer: { ... }    # Startup timer settings
```

## Control API types

Control APIs define how AutoStartStop manages your backend servers (start, stop, restart operations). The plugin supports three control API types:

- **[Shell](https://beyenilmez.github.io/autostartstop/control-api/shell.html)**: Execute shell commands to control servers
- **[AMP](https://beyenilmez.github.io/autostartstop/control-api/amp.html)**: Use AMP API to control servers
- **[Pterodactyl](https://beyenilmez.github.io/autostartstop/control-api/pterodactyl.html)**: Use Pterodactyl Panel Client API to control servers

For detailed configuration options and examples, see the [Control API](https://beyenilmez.github.io/autostartstop/control-api/index.html) page.

## Virtual host

The `virtual_host` field associates a server with a specific hostname or IP address. This is primarily used for MOTD caching and ping response customization.

```
servers:
  survival:
    virtual_host: play.example.com  # Virtual host for this server
```

- **`virtual_host`**: The hostname or IP address that clients use to connect to this server

This is used as a key to cache the server's MOTD. This allows the [`respond_ping`](https://beyenilmez.github.io/autostartstop/actions/ping-management/respond-ping.html) action to display the cached MOTD even when the server is offline.

MOTD cache requirement

To use `use_cached_motd: true` in the [`respond_ping`](https://beyenilmez.github.io/autostartstop/actions/ping-management/respond-ping.html) action, you must configure `virtual_host` in the server configuration. The cached MOTD is retrieved based on the client's virtual host from the ping request.

## Ping settings

Ping configuration for checking server status (online/offline).

```
servers:
  lobby:
    ping:
      timeout: 30s
      method: velocity
```

- **`timeout`**: Ping timeout when checking server status (default: `30s`)
- **`method`**: Method to check server status:
  - `velocity`: Uses Velocity's built-in ping (default, works with all servers)
  - `control_api`: Uses the control API to check status (supported by AMP and Pterodactyl, falls back to `velocity` if not supported)

## Startup timer settings

Startup timer configuration for tracking server startup progress. These settings are used to calculate the server startup progress to show to users.

```
servers:
  survival:
    startup_timer:
      expected_startup_time: 30s
      auto_calculate_expected_startup_time: false
```

- **`expected_startup_time`**: Expected startup time for progress calculations (default: `30s`)
- **`auto_calculate_expected_startup_time`**: Automatically calculate expected startup time from historical data (default: `false`)

# Rules

Rules execute **actions** based on **triggers**, optionally filtered by **conditions**. They define what should happen when certain events occur.

## Rule structure

```
rules:
  <rule_name>:
    enabled: true        # Optional: Enable/disable rule (default: true)
    triggers: [ ... ]    # What events should fire this rule
    conditions: { ... }  # Optional: Should the action execute
    action: [ ... ]      # What actions to perform
```

Or use a template:

```
rules:
  <rule_name>:
    enabled: true              # Optional: Enable/disable rule (default: true)
    template: <template_name>  # Use a built-in template
    # ... template-specific configuration
```

## Rule components

### Triggers

Triggers define **when** a rule should fire. A rule can have multiple triggers, and the rule fires when any trigger activates.

Available triggers:

| Trigger          | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `proxy_start`    | Fires when the proxy starts                                     |
| `proxy_shutdown` | Fires when the proxy shuts down                                 |
| `connection`     | Fires when a player connects to a server                        |
| `empty_server`   | Fires when a server has been empty for a duration               |
| `cron`           | Fires when a cron expression is matched                         |
| `ping`           | Fires when a client pings the proxy (server list/MOTD requests) |
| `manual`         | Fires via `/autostartstop trigger` command                      |

See the [Triggers](https://beyenilmez.github.io/autostartstop/triggers/index.html) section for detailed documentation on each trigger type.

### Conditions

Conditions define **if** a rule should execute (optional). They filter triggers to ensure actions only run under specific circumstances.

Available conditions:

| Condition        | Description                       |
| ---------------- | --------------------------------- |
| `server_status`  | Check if server is online/offline |
| `player_count`   | Check player count on a server    |
| `string_equals`  | Compare two strings               |
| `number_compare` | Compare numeric values            |

#### Condition evaluation mode

Conditions support two evaluation modes:

- **`all`** (default): All conditions must be `true` for the rule to execute (AND logic)
- **`any`**: At least one condition must be `true` for the rule to execute (OR logic)

Inverting conditions

All conditions support the `invert` parameter to negate the result. Set `invert: true` to reverse the condition's logic.

See the [Conditions](https://beyenilmez.github.io/autostartstop/conditions/index.html) section for detailed documentation.

### Actions

Actions define **what** should happen when a rule fires.

Available actions:

| Action             | Description                                   |
| ------------------ | --------------------------------------------- |
| `start`            | Start a server                                |
| `stop`             | Stop a server                                 |
| `restart`          | Restart a server                              |
| `send_command`     | Send a command to a server                    |
| `connect`          | Connect a player to a server                  |
| `disconnect`       | Disconnect one or more players from the proxy |
| `allow_connection` | Allow a player to connect to a server         |
| `send_message`     | Send a message to a player                    |
| `send_action_bar`  | Send an action bar message to a player        |
| `send_title`       | Send a title to a player                      |
| `clear_title`      | Clear a player's title                        |
| `show_bossbar`     | Show a bossbar to a player                    |
| `hide_bossbar`     | Hide a bossbar from a player                  |
| `deny_ping`        | Deny a ping request                           |
| `allow_ping`       | Allow a ping request to proceed normally      |
| `respond_ping`     | Respond to a ping request with a custom MOTD  |
| `if`               | Conditional action execution                  |
| `while`            | Loop while a condition is true                |
| `sleep`            | Wait for a duration                           |
| `log`              | Log a message to the console                  |
| `exec`             | Execute a shell command                       |

See the [Actions](https://beyenilmez.github.io/autostartstop/actions/index.html) section for detailed documentation.

## Example rules

### Simple manual trigger

```
rules:
  # Triggered by: /autostartstop trigger start_server <server_name>
  manual_start:
    triggers:
      - manual:
          id: 'start_server'
    action:
      - start:
          server: ${manual.args.0}  # Server name from command argument
```

### Stop on proxy shutdown

```
rules:
  stop_on_shutdown:
    triggers:
      - proxy_shutdown:
    action:
      - stop:
          server: lobby
```

### Scheduled task (cron)

```
rules:
  nightly_restart:
    triggers:
      - cron:
          expression: '0 3 * * *'  # 3 AM daily
    action:
      - send_message:
          server: survival
          message: "<yellow>Server will restart in 1 minute.</yellow>"
      - sleep:
          duration: 1m
      - restart:
          server: survival
```

## Rule templates

Instead of defining triggers, conditions, and actions manually, you can use built-in templates for common patterns. Templates simplify configuration for frequently used automation scenarios.

Available templates:

| Template                 | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| `start_on_proxy_start`   | Start servers when the proxy starts                  |
| `stop_on_proxy_shutdown` | Stop servers when the proxy shuts down               |
| `start_on_connection`    | Start a server when a player tries to connect        |
| `stop_on_empty`          | Stop servers after they've been empty for a duration |
| `respond_ping`           | Customize ping/MOTD responses based on server status |

Example:

```
rules:
  start_on_connect:
    template: 'start_on_connection'
    servers: ['survival']
    mode: waiting_server
    waiting_server:
      server: limbo
      start_waiting_server_on_connection: true
```

See the [Templates](https://beyenilmez.github.io/autostartstop/rule-templates/index.html) section for detailed configuration options.
# Control API

# Control API

Control APIs define how AutoStartStop manages your backend servers. They handle start, stop, and restart operations.

## Available control APIs

AutoStartStop supports three control API types:

- **[Shell](https://beyenilmez.github.io/autostartstop/control-api/shell.html)**: Execute shell commands to control servers
- **[AMP](https://beyenilmez.github.io/autostartstop/control-api/amp.html)**: Use AMP API to control servers
- **[Pterodactyl](https://beyenilmez.github.io/autostartstop/control-api/pterodactyl.html)**: Use Pterodactyl Panel Client API to control servers

# Shell Control API

Use shell commands to start, stop restart servers and send commands to the server console.

## Configuration

```
servers:
  lobby:
    control_api:
      type: 'shell'
      start_command: './start.sh'
      stop_command: './stop.sh'
      restart_command: './restart.sh'
      send_command_command: './send.sh "${command}"'
      working_directory: '/path/to/server'
      command_timeout: 60s
      environment:
        JAVA_HOME: '/usr/lib/jvm/java-17'
        SERVER_NAME: 'lobby'
```

## Configuration fields

| Field                  | Default           | Description                                                                                                  |
| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `type`                 | -                 | Must be `shell`                                                                                              |
| `start_command`        | -                 | Command to start the server                                                                                  |
| `stop_command`         | -                 | Command to stop the server                                                                                   |
| `restart_command`      | -                 | Command to restart the server                                                                                |
| `send_command_command` | -                 | Command template for sending commands to server console. Use `${command}` placeholder for the actual command |
| `working_directory`    | Current directory | Working directory for commands                                                                               |
| `command_timeout`      | `60s`             | Timeout for commands (e.g., `500ms`, `30s`, `2m`)                                                            |
| `environment`          | -                 | Environment variables to set when executing commands                                                         |

## Examples

### Minimal configuration

```
servers:
  survival:
    control_api:
      type: 'shell'
      start_command: './start.sh'
      stop_command: './stop.sh'
      restart_command: './stop.sh && ./start.sh'
      send_command_command: './send.sh "${command}"'
      working_directory: '/home/minecraft/survival'
```

### Using systemd

```
servers:
  survival:
    control_api:
      type: 'shell'
      start_command: 'systemctl start minecraft-survival'
      stop_command: 'systemctl stop minecraft-survival'
      restart_command: 'systemctl restart minecraft-survival'
```

### With environment variables

```
servers:
  lobby:
    control_api:
      type: 'shell'
      start_command: './start.sh'
      stop_command: './stop.sh'
      working_directory: '/home/minecraft/lobby'
      environment:
        JAVA_HOME: '/usr/lib/jvm/java-17'
        SERVER_NAME: 'lobby'
```

# AMP Control API

Use AMP API to control servers. This provides integration with CubeCoders™ AMP software for centralized server management.

First time setting up?

If you're setting up AMP integration for the first time, see the [AMP Control API User Setup](https://beyenilmez.github.io/autostartstop/guides/amp-user-setup.html) guide for step-by-step instructions on creating a dedicated user and configuring permissions.

## Configuration

```
servers:
  lobby:
    control_api:
      type: 'amp'
      ads_url: 'http://localhost:8080/'
      username: 'your_username'
      password: 'your_password'
      token: 'your_2fa_token'
      remember_me: false
      instance_id: 'MinecraftLobby01'
      start: 'instance_and_server'
      stop: 'server'
      instance_start_timeout: 30s
```

## Configuration fields

| Field                    | Default               | Description                                           |
| ------------------------ | --------------------- | ----------------------------------------------------- |
| `type`                   | -                     | Must be `amp`                                         |
| `ads_url`                | -                     | URL of the ADS panel (e.g., `http://localhost:8080/`) |
| `username`               | -                     | AMP panel username                                    |
| `password`               | -                     | AMP panel password                                    |
| `token`                  | -                     | 2FA token (if two-factor authentication is enabled)   |
| `remember_me`            | `false`               | Remember login session to avoid re-authentication     |
| `instance_id`            | -                     | Instance name or UUID as configured in AMP            |
| `start`                  | `instance_and_server` | Start mode: `instance_and_server` or `server`         |
| `stop`                   | `server`              | Stop mode: `instance_and_server` or `server`          |
| `instance_start_timeout` | `30s`                 | Timeout for instance startup (e.g., `30s`, `1m`)      |

## Instance ID

The `instance_id` can be either:

- **UUID**: Full instance UUID (e.g., `31d9266e-8b92-44dc-8098-ddc85815f20a`)
- **Name**: Instance name (e.g., `MinecraftLobby01`)

You can find the instance ID in the AMP panel:

- **UUID**: Go to **Support and Updates** → **InstanceID** for each instance
- **Name**: View the instance name in parentheses next to the friendly name (e.g., `MinecraftLobby01`)

## Start and stop modes

### Start modes

| Mode                  | Description                                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instance_and_server` | Starts the AMP instance first, then the server. Use this if the instance might be stopped. This is the recommended mode even if the instance is always running. |
| `server`              | Starts only the server. Use this if you do not want to start the instance if it is stopped.                                                                     |

### Stop modes

| Mode                  | Description                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `instance_and_server` | Stops both the server and the instance. Use this for complete shutdown.                                                                 |
| `server`              | Stops only the server, leaving the instance running. Use this if you want to keep the instance available. This is the recommended mode. |

## Examples

### Basic AMP configuration

```
servers:
  survival:
    control_api:
      type: 'amp'
      ads_url: 'http://localhost:8080/'
      username: 'instance_management_bot'
      password: '123456+Abc'
      instance_id: 'eaa348b0-032a-476a-bdc6-6307330876de'
```

### Multiple servers with same panel

```
defaults:
  server:
    control_api:
      type: 'amp'
      ads_url: 'http://localhost:8080/'
      username: 'instance_management_bot'
      password: '123456+Abc'

servers:
  lobby:
    control_api:
      instance_id: '5e81b7e1-d7a2-49ae-82c7-0c340c324b61'

  survival:
    control_api:
      instance_id: '31d0a69c-9a25-48de-92af-334d475e8bcf'

  creative:
    control_api:
      instance_id: '01c46788-d75a-49eb-98fb-b5f3fbe3498f'
```

# Pterodactyl Control API

Use Pterodactyl Panel Client API to control servers. This provides integration with Pterodactyl Panel for centralized server management.

## Configuration

```
servers:
  lobby:
    control_api:
      type: 'pterodactyl'
      panel_url: 'http://localhost/'
      api_key: 'ptlc_xxxxxxxxxxxxx'
      server_id: 'a84e3333'
```

## Configuration fields

| Field       | Default | Description                                                           |
| ----------- | ------- | --------------------------------------------------------------------- |
| `type`      | -       | Must be `pterodactyl`                                                 |
| `panel_url` | -       | Base URL of the Pterodactyl panel (e.g., `https://panel.example.com`) |
| `api_key`   | -       | Client API key (format: `ptlc_...`)                                   |
| `server_id` | -       | Server identifier (UUID or short ID)                                  |

## API Key

Pterodactyl uses Client API keys for server management. To create an API key:

1. Log in to your Pterodactyl panel
1. Go to **Account Settings** → **API Credentials**
1. Create and copy the API key (starts with `ptlc_`)

Warning

Copy the API key as soon as you create it, as you will not be able to access it again.

## Server ID

The `server_id` can be either:

- **UUID**: Full server UUID (e.g., `a84e3333-5cb1-4554-8a6a-79b61a77b163`)
- **Short ID**: Server identifier (e.g., `a84e3333`)

You can find the server ID in the Pterodactyl panel URL when viewing a server, or under **Settings** → **Debug Information** → **Server ID** for the server.

## Examples

### Basic Pterodactyl configuration

```
servers:
  survival:
    control_api:
      type: 'pterodactyl'
      panel_url: 'https://panel.example.com'
      api_key: 'ptlc_xxxxxxxxxxxxx'
      server_id: '87894d2a-e9a6-4302-abdb-3b1a01a5ec40'
```

### Multiple servers with same panel

```
defaults:
  server:
    control_api:
      type: 'pterodactyl'
      panel_url: 'https://panel.example.com'
      api_key: 'ptlc_xxxxxxxxxxxxx'

servers:
  lobby:
    control_api:
      server_id: 'd3aac109'

  survival:
    control_api:
      server_id: 'e4bcd210'

  creative:
    control_api:
      server_id: 'f5cde321'
```
# Variables

# Variables

Variables allow you to use dynamic values in actions and conditions. They are resolved at runtime and can reference context data from triggers, server states, and more.

## Variable syntax

Variables use the `${variable_name}` syntax and can be used in any string field in your configuration:

```
action:
  - allow_connection:
      connection: ${connection}  # Use variable for connection
      server: ${connection.server}  # Use variable for server
  - log:
      message: "<yellow><bold>${connection.player.name} connected</bold></yellow>"  # Use variable in message
```

## Variable types

AutoStartStop supports two main types of variables:

1. **Context variables**: Provided by triggers and available during rule execution
1. **Global server variables**: Access server state and properties from anywhere

## Context variables

Context variables are provided by triggers when they fire. Each trigger type provides its own set of variables.

### Common context variables

All rule executions provide the following common context variables:

| Variable        | Description                                                                          |
| --------------- | ------------------------------------------------------------------------------------ |
| `_rule_name`    | The name of the rule being executed (as defined in `rules:` section)                 |
| `_trigger_type` | The type of trigger that fired (e.g., `proxy_start`, `connection`, `cron`, `manual`) |

These variables are useful for:

- **`_rule_name`**: Identifying which rule is executing, useful for logging and debugging
- **`_trigger_type`**: Determining which trigger activated the rule, especially useful when a rule has multiple triggers

### Trigger-specific variables

Each trigger type provides its own set of context variables. For detailed information about variables available from each trigger, see the individual trigger documentation:

- **[proxy_start](https://beyenilmez.github.io/autostartstop/triggers/proxy-start.html#context-variables)**: No additional variables (only `_trigger_type`)
- **[proxy_shutdown](https://beyenilmez.github.io/autostartstop/triggers/proxy-shutdown.html#context-variables)**: No additional variables (only `_trigger_type`)
- **[connection](https://beyenilmez.github.io/autostartstop/triggers/connection.html#context-variables)**: Player and server information from connection events
- **[empty_server](https://beyenilmez.github.io/autostartstop/triggers/empty-server.html#context-variables)**: Server information and empty time data
- **[cron](https://beyenilmez.github.io/autostartstop/triggers/cron.html#context-variables)**: Cron expression, format, timezone, and execution times
- **[ping](https://beyenilmez.github.io/autostartstop/triggers/ping.html#context-variables)**: Server and client information from ping requests
- **[manual](https://beyenilmez.github.io/autostartstop/triggers/manual.html#context-variables)**: Command arguments and trigger ID

## Global server variables

Global server variables allow you to access server state and properties from anywhere in your configuration. They use the format `${server-name.property}`.

### Available server properties

| Property                       | Description                                                                                            | Type       |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ | ---------- |
| `.name`                        | Server name                                                                                            | String     |
| `.status`                      | Server status (`online` or `offline`)                                                                  | String     |
| `.state`                       | Detailed server state (`unknown`, `offline`, `starting`, `stopping`, `restarting`, `online`, `failed`) | String     |
| `.player_count`                | Number of players on the server                                                                        | Integer    |
| `.players`                     | Collection of Player objects on the server                                                             | Collection |
| `.startup_timer`               | Seconds elapsed since startup began                                                                    | Long       |
| `.startup_progress`            | Startup progress as a decimal (0.0-1.0)                                                                | Double     |
| `.startup_progress_percentage` | Startup progress as a percentage (0-100)                                                               | Integer    |

Server state vs status

- `status`: Simple binary state (`online` or `offline`)
- `state`: Detailed state that includes transitional states like `starting`, `stopping`, `restarting`

Not all control APIs support all states. If a control API doesn't support a state, it will fall back to `online` or `offline`.

### Examples

**Get player count:**

```
action:
  - send_message:
      server: survival
      message: "<green>Players online: ${survival.player_count}</green>"
```

**Use server name directly:**

```
action:
  - start:
      server: ${survival.name}  # Returns "survival"
```

**Access server players:**

```
action:
  - connect:
      server: target
      players: ${survival.players}  # All players from survival server
```

**Startup progress tracking:**

```
action:
  - show_bossbar:
      server: survival
      id: "startup"
      message: "<yellow>Server starting... ${survival.startup_progress_percentage}%</yellow>"
      progress: ${survival.startup_progress}  # 0.0 to 1.0
```

## Nested variables

Variables can be nested to access properties of objects. For example:

```
action:
  - connect:
      server: ${manual.args.1}  # Target server from command argument
      players: ${${manual.args.0}.players}  # Players from source server (nested variable)
```

In this example:

1. `${manual.args.0}` resolves to a server name (e.g., `"survival"`)
1. The outer `${...}` then resolves `${survival.players}` to get all players from that server

## Variable resolution

Variables are resolved in the following order:

1. **Context variables**: Variables set by the trigger that fired the rule
1. **Global server variables**: Server properties accessed via `${server-name.property}`

If a variable can not be resolved, it will remain as-is in the string (e.g., `${unknown_variable}` will not be replaced).

Variable resolution passes

Variable resolution supports up to 5 passes to handle nested variables. This allows complex expressions like `${${manual.args.0}.players}` to work correctly.

## Common use cases

### Dynamic server selection

```
rules:
  auto_start:
    triggers:
      - connection:
          server_list:
            mode: whitelist
            servers:
              - survival
              - creative
    action:
      - start:
          server: ${connection.server.name}  # Start the server the player is trying to connect to
```

### Player information

```
rules:
  log_connection:
    triggers:
      - connection:
    action:
      - log:
          message: "Player ${connection.player.name} (${connection.player.uuid}) connected to ${connection.server.name}"
```

### Conditional logic based on trigger type

```
rules:
  multi_trigger:
    triggers:
      - manual:
          id: 'test'
      - cron:
          expression: '0 * * * *'
    action:
      - if:
          mode: all
          checks:
            - string_equals:
                value: ${_trigger_type}
                equals: manual
          then:
            - log:
                message: "Manual trigger executed"
          else:
            - log:
                message: "Cron trigger executed"
```
# Triggers

# Triggers

Triggers define **when** a rule should fire. A rule can have multiple triggers, and the rule fires when any trigger activates.

## Available triggers

- **[proxy_start](https://beyenilmez.github.io/autostartstop/triggers/proxy-start.html)**: Fires when the proxy starts
- **[proxy_shutdown](https://beyenilmez.github.io/autostartstop/triggers/proxy-shutdown.html)**: Fires when the proxy shuts down
- **[connection](https://beyenilmez.github.io/autostartstop/triggers/connection.html)**: Fires when a player connects to a server
- **[empty_server](https://beyenilmez.github.io/autostartstop/triggers/empty-server.html)**: Fires when a server has been empty for a duration
- **[cron](https://beyenilmez.github.io/autostartstop/triggers/cron.html)**: Fires when a cron expression is matched
- **[ping](https://beyenilmez.github.io/autostartstop/triggers/ping.html)**: Fires when a client pings the proxy (server list/MOTD requests)
- **[manual](https://beyenilmez.github.io/autostartstop/triggers/manual.html)**: Fires via `/autostartstop trigger` command

## Common context variables

All triggers emit a common context variable:

| Variable        | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| `_trigger_type` | The type of trigger that fired (e.g., `proxy_start`, `proxy_shutdown`, etc.) |

This variable can be used in actions and conditions to determine which trigger activated the rule, which is especially useful when a rule has multiple triggers.

Each trigger also emits trigger-specific context variables. See the individual trigger documentation pages for details.

# proxy_start Trigger

Fires when the Velocity proxy starts.

## Configuration

This trigger has no configuration options.

```
triggers:
  - proxy_start:
```

## Context variables

This trigger does not emit any context variables.

## Example

```
rules:
  start_lobby_on_proxy_start:
    triggers:
      - proxy_start:
    action:
      - start:
          server: lobby
```

# proxy_shutdown Trigger

Fires when the Velocity proxy shuts down.

## Configuration

This trigger has no configuration options.

```
triggers:
  - proxy_shutdown:
```

## Context variables

This trigger does not emit any context variables.

## Example

```
rules:
  stop_lobby_on_shutdown:
    triggers:
      - proxy_shutdown:
    action:
      - stop:
          server: lobby
```

# connection Trigger

Fires when a player attempts to connect to a server.

## Configuration

```
triggers:
  - connection:
      server_list:            # Optional: Filter by server list
        mode: whitelist       # 'whitelist' or 'blacklist'
        servers:              # List of server names (as defined in velocity.toml)
          - survival
          - creative
      player_list:            # Optional: Filter by player list
        mode: whitelist       # 'whitelist' or 'blacklist'
        players:              # List of player names
          - Admin1
          - Admin2
      deny_connection: false  # Optional: Deny connection (default: false)
```

## Configuration fields

| Field             | Default | Description                                                                                                                                                                   |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server_list`     | -       | Filter which servers can trigger this. See [Server list filtering](#server-list-filtering) for details.                                                                       |
| `player_list`     | -       | Filter which players can trigger this. See [Player list filtering](#player-list-filtering) for details.                                                                       |
| `deny_connection` | `false` | If `true`, the connection is denied. Use [`allow_connection`](https://beyenilmez.github.io/autostartstop/actions/player-management/allow-connection.html) action to allow it. |

### Server list filtering

Filter which servers can trigger this rule.

```
server_list:
  mode: whitelist
  servers:
    - survival
    - creative
```

- **`mode`**: `whitelist` (only listed servers) or `blacklist` (all except listed servers)
- **`servers`**: List of server names (as defined in `velocity.toml`)

### Player list filtering

Filter which players can trigger this rule.

```
player_list:
  mode: whitelist
  players:
    - Admin1
    - Admin2
```

- **`mode`**: `whitelist` (only listed players) or `blacklist` (all except listed players)
- **`players`**: List of player names

## Context variables

| Variable                         | Description                        |
| -------------------------------- | ---------------------------------- |
| `connection`                     | Connection event                   |
| `connection.player`              | Player object                      |
| `connection.player.name`         | Username                           |
| `connection.player.uuid`         | Player UUID                        |
| `connection.server`              | RegisteredServer object            |
| `connection.server.name`         | Server name                        |
| `connection.server.status`       | Server status (`online`/`offline`) |
| `connection.server.players`      | Collection of players on server    |
| `connection.server.player_count` | Number of players on server        |

## Example

```
rules:
  auto_start_on_connect:
    triggers:
      - connection:
          server_list:
            mode: whitelist
            servers:  # Only trigger for connections to these servers
              - survival
              - creative
          player_list:
            mode: whitelist
            players:  # Only these players can trigger auto-start
              - Admin1
              - Admin2
          deny_connection: true  # Deny connection, allow it later if needed
    conditions:
      mode: all
      checks:
        - server_status:
            server: ${connection.server.name}
            status: offline  # Only start if server is offline
    action:
      - start:
          server: ${connection.server.name}  # Start the server
      - sleep:
          duration: 20s  # Wait for server to start
      - allow_connection:  # Allow the player to connect after server is ready
          connection: ${connection}  # Connection event (default: ${connection})
          server: ${connection.server}  # Server to allow connection to (default: ${connection.server})
```

# empty_server Trigger

Fires when a server has been empty (no players) for a specified duration.

## Configuration

```
triggers:
  - empty_server:
      empty_time: 15m    # Duration the server must be empty (default: 15m)
      server_list:       # Optional: Filter which servers to monitor
        mode: whitelist  # 'whitelist' or 'blacklist'
        servers:         # List of server names (as defined in velocity.toml)
          - survival
          - creative
```

## Configuration fields

| Field         | Default | Description                                                                                       |
| ------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `empty_time`  | `15m`   | Duration the server must be empty before triggering (e.g., `15m`, `30m`, `1h`)                    |
| `server_list` | -       | Filter which servers to monitor. See [Server list filtering](#server-list-filtering) for details. |

How empty servers are detected

Empty servers are primarily detected when players disconnect. Additionally, the plugin performs periodic checks based on the [`empty_server_check_interval`](https://beyenilmez.github.io/autostartstop/configuration/settings.html#empty_server_check_interval) setting (default: `5m`) to catch servers that start without players or become empty through other means.

### Server list filtering

Filter which servers to monitor for empty state.

```
server_list:
  mode: whitelist
  servers:
    - survival
    - creative
```

- **`mode`**: `whitelist` (only listed servers) or `blacklist` (all except listed servers)
- **`servers`**: List of server names (as defined in velocity.toml)

## Context variables

| Variable                   | Description                                 |
| -------------------------- | ------------------------------------------- |
| `empty_server.server`      | RegisteredServer object                     |
| `empty_server.server.name` | Server name                                 |
| `empty_server.empty_time`  | Configured empty time duration              |
| `empty_server.empty_since` | ISO-8601 timestamp when server became empty |

## Example

```
rules:
  stop_empty_servers:
    triggers:
      - empty_server:
          empty_time: 15m  # Trigger after server is empty for 15 minutes
          server_list:
            mode: whitelist
            servers:  # Only monitor these servers
              - survival
              - creative
    action:
      - log:
          message: "Stopping ${empty_server.server.name} after ${empty_server.empty_time} of inactivity"  # Log the action
      - stop:
          server: ${empty_server.server.name}  # Stop the empty server
```

# cron Trigger

Fires on a schedule defined by a cron expression.

## Configuration

```
triggers:
  - cron:
      expression: '0 3 * * *'  # Required: Cron expression
      time_zone: 'UTC'         # Optional: Time zone (default: UTC)
      format: 'UNIX'           # Optional: Cron format (default: UNIX)
```

## Configuration fields

| Field        | Default | Description                                                                                                                     |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `expression` | -       | The cron expression (required)                                                                                                  |
| `time_zone`  | `UTC`   | The time zone for the schedule (e.g., `Europe/Istanbul`, `America/New_York`, `UTC`, `UTC+3`, `UTC-5:30:00`)                     |
| `format`     | `UNIX`  | The cron format. Valid values: `UNIX`, `QUARTZ`, `CRON4J`, `SPRING`, `SPRING53`. See [Cron formats](#cron-formats) for details. |

## Cron formats

| Format     | Description                         |
| ---------- | ----------------------------------- |
| `UNIX`     | Standard UNIX cron format (default) |
| `QUARTZ`   | Quartz scheduler format             |
| `CRON4J`   | Cron4j format                       |
| `SPRING`   | Spring framework format             |
| `SPRING53` | Spring 5.3+ format                  |

Cron expression helper

You can use [crontab.guru](https://crontab.guru) to help create and understand UNIX cron expressions.

## Context variables

| Variable              | Description                             |
| --------------------- | --------------------------------------- |
| `cron.expression`     | The cron expression                     |
| `cron.format`         | The cron format used                    |
| `cron.time_zone`      | The time zone used (ISO-8601)           |
| `cron.scheduled_time` | The scheduled execution time (ISO-8601) |
| `cron.actual_time`    | The actual execution time (ISO-8601)    |

## Examples

### Daily restart

```
rules:
  nightly_restart:
    triggers:
      - cron:
          expression: '0 3 * * *'  # Every day at 3 AM
          time_zone: 'Europe/Istanbul'  # Use Istanbul timezone
    action:
      - send_message:
          server: survival
          message: "<yellow>Server will restart in 1 minute.</yellow>"  # Notify players
      - sleep:
          duration: 1m  # Wait 1 minute
      - restart:
          server: survival  # Restart the server
      - log:
          message: "Nightly restart completed at ${cron.actual_time}"  # Log the restart
```

### Complex schedule

```
rules:
  weekly_maintenance:
    triggers:
      - cron:
          expression: '0 2 * * 0'  # Every Sunday at 2 AM
          time_zone: 'UTC+3'  # Use UTC+3 offset
    action:
      - log:
          message: "Starting weekly maintenance at ${cron.actual_time}"  # Log start time
      - send_message:
          servers: [survival, creative]
          message: "<red>Weekly maintenance in progress. Some servers may be unavailable.</red>"  # Notify all players
      - exec:
          command: './maintenance.sh'  # Run maintenance script
          working_directory: '/opt/minecraft/scripts'
      - log:
          message: "Weekly maintenance completed"  # Log completion
```

# ping Trigger

Fires when a client pings the proxy server (server list/MOTD requests).

## Configuration

```
triggers:
  - ping:
      virtual_host_list:    # Optional: Filter by virtual host
        mode: whitelist     # 'whitelist' or 'blacklist'
        virtual_hosts:
          - example.com
          - mc.example.com
          - 192.168.1.100
      server_list:          # Optional: Filter by server names (maps to virtual_hosts from config)
        mode: whitelist     # 'whitelist' or 'blacklist'
        servers:
          - survival
          - creative
      hold_response: false  # Optional: Hold response until rule completes or an action signals early release (default: false)
```

## Configuration fields

| Field               | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `virtual_host_list` | -       | Filter which virtual hosts can trigger this. See [Virtual host filtering](#virtual-host-filtering) for details.                                                                                                                                                                                                                                                                                                          |
| `server_list`       | -       | Filter by server names. Maps server names to their `virtual_host` values from the `servers:` configuration. See [Server filtering](#server-filtering) for details.                                                                                                                                                                                                                                                       |
| `hold_response`     | `false` | If `true`, holds the ping response until the rule execution completes or an action ([`allow_ping`](https://beyenilmez.github.io/autostartstop/actions/ping-management/allow-ping.html), [`deny_ping`](https://beyenilmez.github.io/autostartstop/actions/ping-management/deny-ping.html), [`respond_ping`](https://beyenilmez.github.io/autostartstop/actions/ping-management/respond-ping.html)) signals early release. |

### Virtual host filtering

Filter which virtual hosts can trigger this rule.

```
virtual_host_list:
  mode: whitelist
  virtual_hosts:
    - example.com
    - mc.example.com
    - 192.168.1.100
```

- **`mode`**: `whitelist` (only listed hosts) or `blacklist` (all except listed hosts)
- **`virtual_hosts`**: List of virtual host names or addresses

### Server filtering

Filter which servers can trigger this rule by server name. The trigger will match pings based on the `virtual_host` configured for each server in the `servers:` section of your configuration.

```
server_list:
  mode: whitelist
  servers:
    - survival
    - creative
```

- **`mode`**: `whitelist` (only listed servers) or `blacklist` (all except listed servers)
- **`servers`**: List of server names (as defined in the `servers:` section of your configuration)

Server to virtual host mapping

When using `server_list`, the trigger automatically maps server names to their `virtual_host` values from your server configuration. Only servers with a configured `virtual_host` will be matched. Check [servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html#virtual-host) for more information.

Conflicting filter modes

When both `virtual_host_list` and `server_list` are specified with different modes (e.g., one is `whitelist` and the other is `blacklist`), the trigger will log a warning and default to `whitelist` mode. To avoid confusion, use the same mode for both filters, or use only one filter type.

## Context variables

| Variable                       | Description                                                                 |
| ------------------------------ | --------------------------------------------------------------------------- |
| `ping`                         | ProxyPingEvent object                                                       |
| `ping.server`                  | Backend server name (resolved from virtual host; null if no server matches) |
| `ping.server.motd`             | Server MOTD (in MiniMessage format)                                         |
| `ping.server.player_count`     | Current player count                                                        |
| `ping.server.max_players`      | Maximum players                                                             |
| `ping.server.protocol_version` | Server protocol version                                                     |
| `ping.server.version_name`     | Server version name                                                         |
| `ping.player.remote_address`   | Client remote address                                                       |
| `ping.player.virtual_host`     | Client virtual host                                                         |
| `ping.player.protocol_version` | Client protocol version                                                     |

## Examples

### Show cached MOTD for offline server

```
rules:
  cached_motd:
    triggers:
      - ping:
          hold_response: true  # Hold response until respond_ping action is executed
          virtual_host_list:
            mode: whitelist
            virtual_hosts:
              - survival.example.com # Only show cached MOTD for survival.example.com
    conditions:
      mode: all
      checks:
        - server_status:
            server: survival
            status: offline  # Check if survival server is offline
    action:
      - respond_ping:
          ping: "${ping}"  # Ping event object (default: ${ping})
          use_cached_motd: true  # Show cached MOTD
          player_count: 0  # Show 0 players
          max_players: 0  # Show 0 max players
          protocol_version: -1  # Use -1 protocol version to show version name text
          version_name: "<blue>◉ Sleeping"  # Show version name text as sleeping
```

### Deny ping

```
rules:
  deny_maintenance_ping:
    triggers:
      - ping:
          hold_response: true  # Hold response to use deny_ping action later
          virtual_host_list:
            mode: whitelist
            virtual_hosts:
              - survival.example.com  # Only deny ping for survival.example.com
    action:
      - deny_ping:  # Deny the ping request
          ping: "${ping}"  # Ping event object (default: ${ping})
```

### Dynamic MOTD with variables

```
rules:
  dynamic_motd:
    triggers:
      - ping:
          hold_response: true  # Hold response to customize MOTD
    action:
      - respond_ping:
          motd: "<yellow>Players: ${ping.server.player_count}/${ping.server.max_players}</yellow>"  # Use variables in MOTD
```

# manual Trigger

Fires via `/autostartstop trigger <id> [args...]` command.

## Configuration

```
triggers:
  - manual:
      id: 'start_server'  # Required: Trigger ID
```

## Configuration fields

| Field | Default | Description                                          |
| ----- | ------- | ---------------------------------------------------- |
| `id`  | -       | Unique identifier for this manual trigger (required) |

## Context variables

| Variable                              | Description                        |
| ------------------------------------- | ---------------------------------- |
| `manual.id`                           | The trigger ID                     |
| `manual.args.0`, `manual.args.1`, ... | Command arguments (indexed from 0) |
| `manual.args.length`                  | Number of arguments                |

## Usage

To fire a manual trigger, use the command:

```
/autostartstop trigger <id> [args...]
```

Or use the alias:

```
/ass trigger <id> [args...]
```

## Examples

### Connect player to server

```
rules:
  manual_connect:
    triggers:
      - manual:
          id: 'connect'  # Trigger ID: /ass trigger connect <player_name> <server_name>
    action:
      - log:
          message: "Connecting ${manual.args.0} to ${manual.args.1}"  # Log the connection
      - connect:
          player: ${manual.args.0}  # First argument: player name
          server: ${manual.args.1}  # Second argument: server name
```

Usage: `/ass trigger connect PlayerName survival`

### Disconnect player

```
rules:
  manual_kick:
    triggers:
      - manual:
          id: 'kick'  # Trigger ID: /ass trigger kick <player_name> [reason]
    action:
      - log:
          message: "Kicking player ${manual.args.0} (reason: ${manual.args.1})"  # Log the kick
      - disconnect:
          player: ${manual.args.0}
          reason: "<red>You have been kicked by an administrator.</red><br><yellow>Reason: ${manual.args.1}</yellow>"  # Kick with reason
```

Usage: `/ass trigger kick PlayerName "Reason for kick"`
# Conditions

# Conditions

Conditions define **if** a rule should execute. They filter triggers to ensure actions only run under specific circumstances.

## Available conditions

- **[server_status](https://beyenilmez.github.io/autostartstop/conditions/server-status.html)**: Check if server is online/offline
- **[player_count](https://beyenilmez.github.io/autostartstop/conditions/player-count.html)**: Check player count on a server
- **[string_equals](https://beyenilmez.github.io/autostartstop/conditions/string-equals.html)**: Compare two strings
- **[number_compare](https://beyenilmez.github.io/autostartstop/conditions/number-compare.html)**: Compare numeric values

## Condition evaluation mode

Conditions support two evaluation modes:

- **`all`** (default): All conditions must be `true` for the rule to execute (AND logic)
- **`any`**: At least one condition must be `true` for the rule to execute (OR logic)

```
conditions:
  mode: all  # All conditions must pass (default)
  checks:
    - server_status:
        server: survival
        status: online
    - player_count:
        server: survival
        min: 1
```

```
conditions:
  mode: any  # At least one condition must pass
  checks:
    - server_status:
        server: survival
        status: online
    - server_status:
        server: creative
        status: online
```

## Inverting conditions

All conditions support the `invert` parameter to negate the result. Set `invert: true` to reverse the condition's logic.

```
server_status:
  server: survival
  status: online
  invert: true  # Returns true if server is NOT online
```

# server_status Condition

Checks if a server is online or offline.

## Configuration

```
conditions:
  mode: all
  checks:
    - server_status:
        server: survival  # Server name (required)
        status: online    # Expected status: 'online' or 'offline' (required)
        invert: false     # Optional: Invert the result (default: false)
```

## Configuration fields

| Field    | Default | Description                                       |
| -------- | ------- | ------------------------------------------------- |
| `server` | -       | The server name to check (required)               |
| `status` | -       | Expected status: `online` or `offline` (required) |
| `invert` | `false` | If `true`, negates the condition result           |

## Example

```
rules:
  auto_start_on_connect:
    triggers:
      - connection:
          server_list:
            mode: whitelist
            servers: [survival]
          deny_connection: true  # Deny connection
    conditions:
      mode: all
      checks:
        - server_status:
            server: ${connection.server.name}
            status: offline  # Only start if server is offline
    action:
      - start:
          server: ${connection.server.name}  # Start the server
      - sleep:
          duration: 20s  # Wait for server to start
      - allow_connection:  # Allow the player to connect after server is ready
```

# player_count Condition

Checks player count on a server against min, max, or equals constraints.

## Configuration

```
conditions:
  mode: all
  checks:
    - player_count:
        server: survival  # Server name (required)
        min: 0            # Optional: Minimum player count
        max: 10           # Optional: Maximum player count
        equals: 5         # Optional: Exact player count
        invert: false     # Optional: Invert the result (default: false)
```

## Configuration fields

| Field    | Default | Description                             |
| -------- | ------- | --------------------------------------- |
| `server` | -       | The server name to check (required)     |
| `min`    | -       | Minimum player count (inclusive)        |
| `max`    | -       | Maximum player count (inclusive)        |
| `equals` | -       | Exact player count                      |
| `invert` | `false` | If `true`, negates the condition result |

Constraint evaluation

The condition evaluates to `true` if the player count satisfies all specified constraints:

- If `equals` is specified, player count must equal this value
- If `min` is specified, player count must be >= `min`
- If `max` is specified, player count must be \<= `max`

You can use `min` and `max` together to check if player count is within a range.

## Examples

### Check if server is empty

```
rules:
  stop_empty_server:
    triggers:
      - cron:
          expression: '0 * * * *'  # Every hour
    conditions:
      mode: all
      checks:
        - player_count:
            server: survival
            equals: 0  # Server has no players
    action:
      - stop:
          server: survival
```

### Check if server has players

```
rules:
  notify_when_busy:
    triggers:
      - cron:
          expression: '*/5 * * * *'  # Every 5 minutes
    conditions:
      mode: all
      checks:
        - player_count:
            server: survival
            min: 10  # At least 10 players
    action:
      - log:
          message: "Survival server is busy with ${survival.player_count} players"
```

### Check player count range

```
rules:
  moderate_load:
    triggers:
      - cron:
          expression: '*/10 * * * *'  # Every 10 minutes
    conditions:
      mode: all
      checks:
        - player_count:
            server: survival
            min: 5   # At least 5 players
            max: 20  # At most 20 players
    action:
      - log:
          message: "Survival server has moderate load: ${survival.player_count} players"
```

# string_equals Condition

Compares two string values for equality.

## Configuration

```
conditions:
  mode: all
  checks:
    - string_equals:
        value: ${connection.player.name}  # First value (required)
        equals: Admin1                    # Second value to compare (required)
        ignore_case: false                # Optional: Case-insensitive comparison (default: false)
        invert: false                     # Optional: Invert the result (default: false)
```

## Configuration fields

| Field         | Default | Description                                     |
| ------------- | ------- | ----------------------------------------------- |
| `value`       | -       | First string value to compare (required)        |
| `equals`      | -       | Second string value to compare (required)       |
| `ignore_case` | `false` | If `true`, performs case-insensitive comparison |
| `invert`      | `false` | If `true`, negates the condition result         |

## Examples

### Case-insensitive comparison

```
rules:
  case_insensitive_check:
    triggers:
      - manual:
          id: 'check'
    conditions:
      mode: all
      checks:
        - string_equals:
            value: ${manual.args.0}
            equals: 'admin'
            ignore_case: true  # 'Admin', 'ADMIN', 'admin' all match
    action:
      - log:
          message: "Admin command executed"
```

### Check trigger type

```
rules:
  test_rule:
    triggers:
      - manual:
          id: 'test'
      - cron:
          expression: '0 * * * *'
    action:
      - if:
          mode: all
          checks:
            - string_equals: # Compare the trigger type with the value
                value: ${_trigger_type}
                equals: manual
          then:
            - log:
                message: "Manual trigger executed"
          else:
            - log:
                message: "Cron trigger executed"
```

# number_compare Condition

Compares a numeric value against min, max, or equals constraints.

## Configuration

```
conditions:
  mode: all
  checks:
    - number_compare:
        value: ${ping.server.player_count}  # Value to compare (required)
        min: 0                              # Optional: Minimum value
        max: 100                            # Optional: Maximum value
        equals: 50                          # Optional: Exact value
        invert: false                       # Optional: Invert the result (default: false)
```

## Configuration fields

| Field    | Default | Description                             |
| -------- | ------- | --------------------------------------- |
| `value`  | -       | Numeric value to compare (required)     |
| `min`    | -       | Minimum value (inclusive)               |
| `max`    | -       | Maximum value (inclusive)               |
| `equals` | -       | Exact value                             |
| `invert` | `false` | If `true`, negates the condition result |

Constraint evaluation

The condition evaluates to `true` if the value satisfies all specified constraints:

- If `equals` is specified, value must equal this number
- If `min` is specified, value must be >= `min`
- If `max` is specified, value must be \<= `max`

You can use `min` and `max` together to check if a value is within a range.

## Examples

### Check exact value

```
rules:
  exact_player_count:
    triggers:
      - cron:
          expression: '*/5 * * * *'  # Every 5 minutes
    conditions:
      mode: all
      checks:
        - number_compare:
            value: ${surival.player_count}
            equals: 0  # Exactly 0 players
    action:
      - log:
          message: "Survival server is empty"
```

### Check value range

```
rules:
  moderate_load:
    triggers:
      - cron:
          expression: '*/10 * * * *'  # Every 10 minutes
    conditions:
      mode: all
      checks:
        - number_compare:
            value: ${survival.player_count}
            min: 5   # At least 5
            max: 20  # At most 20
    action:
      - log:
          message: "Survival server has moderate load: ${survival.player_count} players"
```

### Check minimum value

```
rules:
  high_load:
    triggers:
      - cron:
          expression: '*/15 * * * *'  # Every 15 minutes
    conditions:
      mode: all
      checks:
        - number_compare:
            value: ${survival.player_count}
            min: 50  # At least 50 players
    action:
      - log:
          message: "Survival server is under high load: ${survival.player_count} players"
```
# Actions

# Actions

Actions define **what** should happen when a rule fires. A rule can have multiple actions, and they execute sequentially.

## Action execution

Actions execute sequentially in the order they are defined. By default, actions execute synchronously. You can use `wait_for_completion: false` on individual actions to execute them asynchronously.

## Available actions

### [Server Management](https://beyenilmez.github.io/autostartstop/actions/server-management/index.html)

Actions for managing server lifecycle: starting, stopping, and restarting servers.

- **[start](https://beyenilmez.github.io/autostartstop/actions/server-management/start.html)**: Start a server
- **[stop](https://beyenilmez.github.io/autostartstop/actions/server-management/stop.html)**: Stop a server
- **[restart](https://beyenilmez.github.io/autostartstop/actions/server-management/restart.html)**: Restart a server
- **[send_command](https://beyenilmez.github.io/autostartstop/actions/server-management/send-command.html)**: Send a command to a server's console

### [Player Management](https://beyenilmez.github.io/autostartstop/actions/player-management/index.html)

Actions for managing player connections and disconnections.

- **[connect](https://beyenilmez.github.io/autostartstop/actions/player-management/connect.html)**: Connect a player to a server
- **[disconnect](https://beyenilmez.github.io/autostartstop/actions/player-management/disconnect.html)**: Disconnect one or more players from the proxy
- **[allow_connection](https://beyenilmez.github.io/autostartstop/actions/player-management/allow-connection.html)**: Allow a previously denied connection

### [Player Communication](https://beyenilmez.github.io/autostartstop/actions/player-communication/index.html)

Actions for sending messages, action bars, titles, and bossbars to players.

- **[send_message](https://beyenilmez.github.io/autostartstop/actions/player-communication/send-message.html)**: Send a message to one or more players
- **[send_action_bar](https://beyenilmez.github.io/autostartstop/actions/player-communication/send-action-bar.html)**: Send an action bar message to one or more players
- **[send_title](https://beyenilmez.github.io/autostartstop/actions/player-communication/send-title.html)**: Send a title to one or more players
- **[clear_title](https://beyenilmez.github.io/autostartstop/actions/player-communication/clear-title.html)**: Clear title of one or more players
- **[show_bossbar](https://beyenilmez.github.io/autostartstop/actions/player-communication/show-bossbar.html)**: Show a bossbar to one or more players
- **[hide_bossbar](https://beyenilmez.github.io/autostartstop/actions/player-communication/hide-bossbar.html)**: Hide a bossbar from one or more players

### [Ping Management](https://beyenilmez.github.io/autostartstop/actions/ping-management/index.html)

Actions for managing ping requests and customizing server list responses.

- **[deny_ping](https://beyenilmez.github.io/autostartstop/actions/ping-management/deny-ping.html)**: Deny a ping request
- **[allow_ping](https://beyenilmez.github.io/autostartstop/actions/ping-management/allow-ping.html)**: Allow a ping request to proceed normally
- **[respond_ping](https://beyenilmez.github.io/autostartstop/actions/ping-management/respond-ping.html)**: Respond to a ping request with custom ping data

### [Control Flow](https://beyenilmez.github.io/autostartstop/actions/control-flow/index.html)

Actions for conditional execution and looping.

- **[if](https://beyenilmez.github.io/autostartstop/actions/control-flow/if.html)**: Conditional action execution
- **[while](https://beyenilmez.github.io/autostartstop/actions/control-flow/while.html)**: Loop while a condition is true

### [Utility](https://beyenilmez.github.io/autostartstop/actions/utility/index.html)

General-purpose utility actions for logging, waiting, and executing commands.

- **[sleep](https://beyenilmez.github.io/autostartstop/actions/utility/sleep.html)**: Wait for a duration
- **[log](https://beyenilmez.github.io/autostartstop/actions/utility/log.html)**: Log a message to the console
- **[exec](https://beyenilmez.github.io/autostartstop/actions/utility/exec.html)**: Execute a shell command

# start Action

Starts a server using the configured control API.

Control API required

All server management actions require:

- Server configuration in the [`servers:`](https://beyenilmez.github.io/autostartstop/configuration/servers.html) section of `config.yml`
- A configured [control API](https://beyenilmez.github.io/autostartstop/control-api/index.html)

See [Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html) for configuration details.

Shell Control API

When using the [Shell Control API](https://beyenilmez.github.io/autostartstop/control-api/shell.html), the `start_command` is required in the server's control API configuration.

## Configuration

```
action:
  - start:
      server: survival  # Required: Server name
```

## Configuration fields

| Field    | Default | Description              |
| -------- | ------- | ------------------------ |
| `server` | -       | The server name to start |

## How it works

When the `start` action is executed, AutoStartStop sends the start command to the server using the configured [Control API](https://beyenilmez.github.io/autostartstop/control-api/index.html) and automatically begins tracking the startup process.

The startup tracker monitors the server state in the background (polls every second) and calculates progress based on elapsed time and the expected startup time configured in the server's [`startup_timer`](https://beyenilmez.github.io/autostartstop/configuration/servers.html#startup-timer-settings) setting. Tracking stops when the server comes online or after a timeout (10 minutes).

### Startup progress variables

The following variables become available globally for tracking startup progress:

| Variable                                    | Description                                                                                                                                    |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `<server_name>.state`                       | Current server state: `unknown`, `offline`, `starting`, `stopping`, `restarting`, `online`, `failed` (Not all control APIs support all states) |
| `<server_name>.startup_timer`               | Seconds elapsed since startup began                                                                                                            |
| `<server_name>.startup_progress`            | Startup progress as a decimal (0.0-1.0), useful for bossbars                                                                                   |
| `<server_name>.startup_progress_percentage` | Startup progress as a percentage (0-100)                                                                                                       |

Progress increases from 0% to 99% as time passes, reaching 100% only when the server comes online.

## Example

```
rules:
  auto_start_on_connection:
    triggers:
      - connection:
          deny_connection: true
          server_list:
            mode: whitelist
            servers:
              - survival  # Only trigger for connections to survival server
    action:
      - start:
          server: ${connection.server.name}  # Start the server that player is trying to connect to
      - while:  # Wait for server to start
        timeout: 2m
        checks:
          - server_status:
              server: ${connection.server.name}
              status: offline
      - allow_connection:  # Allow the connection after server is ready
```

This rule will automatically start the server when a player tries to connect to it, wait for it to start, and then allow the connection.

# stop Action

Stops a server using the configured control API.

Control API required

All server management actions require:

- Server configuration in the [`servers:`](https://beyenilmez.github.io/autostartstop/configuration/servers.html) section of `config.yml`
- A configured [control API](https://beyenilmez.github.io/autostartstop/control-api/index.html)

See [Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html) for configuration details.

Shell Control API

When using the [Shell Control API](https://beyenilmez.github.io/autostartstop/control-api/shell.html), the `stop_command` is required in the server's control API configuration.

MOTD caching

Before stopping a server, AutoStartStop automatically caches the server's MOTD (Message of the Day). This cached MOTD can be displayed when the server is offline using the [`respond_ping`](https://beyenilmez.github.io/autostartstop/actions/ping-management/respond-ping.html) action with `use_cached_motd: true`.

## Configuration

```
action:
  - stop:
      server: survival  # Required: Server name
```

## Configuration fields

| Field    | Default | Description             |
| -------- | ------- | ----------------------- |
| `server` | -       | The server name to stop |

## How it works

When the `stop` action is executed, AutoStartStop caches the server's MOTD (while the server is still online) and sends the stop command to the server using the configured [Control API](https://beyenilmez.github.io/autostartstop/control-api/index.html).

## Example

```
rules:
  stop_empty:
    triggers:
      - empty_server:
          empty_time: 15m  # Trigger after server is empty for 15 minutes
          server_list:
            mode: whitelist
            servers:
              - survival  # Only monitor survival server
    action:
      - stop:
          server: survival  # Stop the empty server
```

This rule will automatically stop the server after it has been empty for 15 minutes.

# restart Action

Restarts a server using the configured control API.

Control API required

All server management actions require:

- Server configuration in the [`servers:`](https://beyenilmez.github.io/autostartstop/configuration/servers.html) section of `config.yml`
- A configured [control API](https://beyenilmez.github.io/autostartstop/control-api/index.html)

See [Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html) for configuration details.

Shell Control API

When using the [Shell Control API](https://beyenilmez.github.io/autostartstop/control-api/shell.html), the `restart_command` is required in the server's control API configuration.

MOTD caching

Before restarting a server, AutoStartStop automatically caches the server's MOTD (Message of the Day). This cached MOTD can be displayed when the server is offline using the [`respond_ping`](https://beyenilmez.github.io/autostartstop/actions/ping-management/respond-ping.html) action with `use_cached_motd: true`.

## Configuration

```
action:
  - restart:
      server: survival  # Required: Server name
```

## Configuration fields

| Field    | Default | Description                |
| -------- | ------- | -------------------------- |
| `server` | -       | The server name to restart |

## How it works

When the `restart` action is executed, AutoStartStop caches the server's MOTD (while the server is still online) and sends the restart command to the server using the configured [Control API](https://beyenilmez.github.io/autostartstop/control-api/index.html).

## Example

```
rules:
  nightly_restart:
    triggers:
      - cron:
          expression: '0 3 * * *'  # Every day at 3 AM
    action:
      - send_message:
          server: survival
          message: "<yellow>Server will restart in 1 minute.</yellow>"  # Notify players
      - sleep:
          duration: 1m  # Wait 1 minute
      - restart:
          server: survival  # Restart the server
```

This rule will notify players 1 minute before restarting the server, then restart it at the scheduled time.

# send_command Action

Sends a command to a server's console using the configured control API.

Control API required

All server management actions require:

- Server configuration in the [`servers:`](https://beyenilmez.github.io/autostartstop/configuration/servers.html) section of `config.yml`
- A configured [control API](https://beyenilmez.github.io/autostartstop/control-api/index.html)

See [Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html) for configuration details.

Shell Control API Support

When using the [Shell Control API](https://beyenilmez.github.io/autostartstop/control-api/shell.html), the `send_command_command` is required in the server's control API configuration.

## Configuration

```
action:
  - send_command:
      server: survival  # Server name
      command: "say Welcome to the server!"  # Command to send
```

## Configuration fields

| Field     | Default | Description                               |
| --------- | ------- | ----------------------------------------- |
| `server`  | -       | The server name to send the command to    |
| `command` | -       | The command to send to the server console |

## How it works

When the `send_command` action is executed, AutoStartStop sends the command to the server's console using the configured [Control API](https://beyenilmez.github.io/autostartstop/control-api/index.html).

## Example

```
rules:
  give_diamond_every_hour:
    triggers:
      - cron:
          expression: '0 * * * *'
    actions:
      - send_command:
          server: survival
          command: "give @r diamond"
```

This rule will give a diamond to a random player in the survival server every hour.

# connect Action

Connects one or more players to the specified server.

## Configuration

```
action:
  - connect:
      player: PlayerName  # Single player
      players:            # Multiple players
        - Player1
        - Player2
      server: survival    # Target server
      error_message: '<red>Could not connect to the server.</red>'  # Optional; sent to player on connection failure
```

## Configuration fields

| Field           | Default                                                                      | Description                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `player`        | -                                                                            | Single player name or UUID                                                                                                                                                                         |
| `players`       | -                                                                            | List of player names or UUIDs                                                                                                                                                                      |
| `server`        | -                                                                            | Target server name                                                                                                                                                                                 |
| `error_message` | `<red>Could not connect to ${connect_server}: ${connect_error_reason}</red>` | MiniMessage sent to the player when the connection fails. Supports variables: `connect_server` (target server name), `connect_error_reason` (failure reason from the server or exception message). |

## Example

```
rules:
  transfer_players:
    triggers:
      - manual:
          id: 'transfer'  # Trigger with: /autostartstop trigger transfer <source_server> <target_server>
    action:
      - connect:
          server: ${manual.args.1}  # Target server (second argument)
          players: ${${manual.args.0}.players}  # All players from source server (first argument)
```

This will transfer all players from the source server to the target server when the command is executed.

# disconnect Action

Disconnects one or more players from the proxy.

## Configuration

```
action:
  - disconnect:
      player: PlayerName  # Single player
      players:            # Multiple players
        - Player1
        - Player2
      server: survival    # All players on server
      servers:            # All players on servers
        - survival
        - creative
      reason: "<red>Disconnected</red>"  # Optional: Disconnect reason (MiniMessage format)
```

## Configuration fields

| Field     | Default | Description                             |
| --------- | ------- | --------------------------------------- |
| `player`  | -       | Single player name or UUID              |
| `players` | -       | List of player names or UUIDs           |
| `server`  | -       | All players on a single server          |
| `servers` | -       | All players on multiple servers         |
| `reason`  | -       | Disconnect reason in MiniMessage format |

Player targeting

At least one of `player`, `players`, `server`, or `servers` must be provided.

## Example

```
rules:
  disconnect_server:
    triggers:
      - manual:
          id: 'disconnect'  # Trigger with: /autostartstop trigger disconnect <server_name> <reason>
    action:
      - disconnect:
          server: ${manual.args.0}  # Server name from command argument
          reason: ${manual.args.1}  # Disconnect reason from command argument (optional)
```

This rule allows you to manually disconnect all players from a specified server with a custom reason.

# allow_connection Action

Allows a previously denied connection to proceed. Use this action when a connection trigger has `deny_connection: true` and you want to allow the connection to proceed. See [connection](https://beyenilmez.github.io/autostartstop/triggers/connection.html) for more information.

## Configuration

```
action:
  - allow_connection:
      connection: ${connection}     # Connection event (default: ${connection})
      server: ${connection.server}  # Target server (default: ${connection.server})
```

## Configuration fields

| Field        | Default                | Description                              |
| ------------ | ---------------------- | ---------------------------------------- |
| `connection` | `${connection}`        | The connection event object              |
| `server`     | `${connection.server}` | The target server to allow connection to |

## Example

```
rules:
  auto_start_on_connection:
    triggers:
      - connection:
          deny_connection: true
          server_list:
            mode: whitelist
            servers:
              - survival  # Only trigger for connections to survival server
    action:
      - start:
          server: ${connection.server.name}  # Start the server that player is trying to connect to
      - while:  # Wait for server to start
        timeout: 2m
        checks:
          - server_status:
              server: ${connection.server.name}
              status: offline
      - allow_connection:  # Allow the connection after server is ready
          connection: ${connection}     # Connection event
          server: ${connection.server}  # Target server
```

This rule will automatically start the server when a player tries to connect to it, wait for it to start, and then allow the connection.

# send_message Action

Sends a message to one or more players.

## Configuration

```
action:
  - send_message:
      player: PlayerName  # Single player
      players:            # Multiple players
        - Player1
        - Player2
      server: survival    # All players on server
       servers:           # All players on servers
        - survival
        - creative
      message: "<yellow>Hello!</yellow>"  # Message (MiniMessage format)
```

## Configuration fields

| Field     | Default | Description                           |
| --------- | ------- | ------------------------------------- |
| `player`  | -       | Single player name or UUID            |
| `players` | -       | List of player names or UUIDs         |
| `server`  | -       | All players on a single server        |
| `servers` | -       | All players on multiple servers       |
| `message` | -       | Message to send in MiniMessage format |

Player targeting

At least one of `player`, `players`, `server`, or `servers` must be provided.

## Example

```
rules:
  send_message:
    triggers:
      - manual:
          id: 'message'  # Trigger with: /autostartstop trigger message <server_name> <message>
    action:
      - send_message:
          server: ${manual.args.0}  # Server name from command argument
          message: ${manual.args.1}  # Message from command argument
```

This action will send the specified message to all players on the specified server.

# send_action_bar Action

Sends an action bar message to one or more players.

## Configuration

```
action:
  - send_action_bar:
      player: PlayerName  # Single player
      players:            # Multiple players
        - Player1
        - Player2
      server: survival    # All players on server
      servers:            # All players on servers
        - survival
        - creative
      message: "<yellow>Action bar message</yellow>"  # Message (MiniMessage format)
```

## Configuration fields

| Field     | Default | Description                           |
| --------- | ------- | ------------------------------------- |
| `player`  | -       | Single player name or UUID            |
| `players` | -       | List of player names or UUIDs         |
| `server`  | -       | All players on a single server        |
| `servers` | -       | All players on multiple servers       |
| `message` | -       | Message to send in MiniMessage format |

Player targeting

At least one of `player`, `players`, `server`, or `servers` must be provided.

## Example

```
rules:
  send_action_bar:
    triggers:
      - manual:
          id: 'actionbar'  # Trigger with: /autostartstop trigger actionbar <player_name> <message>
    action:
      - send_action_bar:
          player: ${manual.args.0}  # Player name from command argument
          message: ${manual.args.1}  # Message from command argument
```

This action will send the specified action bar message to the specified player.

# send_title Action

Sends a title and optional subtitle to one or more players. The title can be cleared later using the `clear_title` action. See [clear_title](https://beyenilmez.github.io/autostartstop/actions/player-communication/clear-title.html) for more information.

## Configuration

```
action:
  - send_title:
      player: PlayerName  # Single player
      players:            # Multiple players
        - Player1
        - Player2
      server: survival    # All players on server
       servers:           # All players on servers
        - survival
        - creative
      title: "<yellow>Welcome!</yellow>"        # Title (MiniMessage format)
      subtitle: "<gray>Enjoy your stay</gray>"  # Subtitle (MiniMessage format)
      fade_in: 500ms                            # Fade in duration (default: 500ms)
      stay: 3s                                  # Stay duration (default: 3s)
      fade_out: 500ms                           # Fade out duration (default: 500ms)
```

## Configuration fields

| Field      | Default | Description                            |
| ---------- | ------- | -------------------------------------- |
| `player`   | -       | Single player name or UUID             |
| `players`  | -       | List of player names or UUIDs          |
| `server`   | -       | All players on a single server         |
| `servers`  | -       | All players on multiple servers        |
| `title`    | -       | Title text in MiniMessage format       |
| `subtitle` | -       | Subtitle text in MiniMessage format    |
| `fade_in`  | `500ms` | Fade in duration (e.g., `500ms`, `1s`) |
| `stay`     | `3s`    | How long the title stays visible       |
| `fade_out` | `500ms` | Fade out duration                      |

Duration format

Duration fields (`fade_in`, `stay`, `fade_out`) support multiple formats:

- **Ticks**: `10t`, `20t` (1 tick = 50ms, 20 ticks per second)
- **Milliseconds**: `500ms`, `1000ms`
- **Seconds**: `1s`, `3s`, `5s`
- **Minutes**: `1m`, `2m`
- **Hours**: `1h`, `2h`

Player targeting

At least one of `player`, `players`, `server`, or `servers` must be provided.

## Example

```
rules:
  send_title:
    triggers:
      - manual:
          id: 'title'  # Trigger with: /autostartstop trigger title <player_name>
    action:
      - send_title:
          player: ${manual.args.0}  # Player name from command argument
          title: "<yellow><bold>Welcome!</bold></yellow>"  # Title message
          subtitle: "<gray>Enjoy your stay</gray>"  # Subtitle message
          stay: 5s  # How long the title stays visible
```

This action will send a title and subtitle to the specified player.

# clear_title Action

Clears the title for one or more players.

## Configuration

```
action:
  - clear_title:
      player: PlayerName  # Single player
      players:            # Multiple players
        - Player1
        - Player2
      server: survival    # All players on server
       servers:           # All players on servers
        - survival
        - creative
```

## Configuration fields

| Field     | Default | Description                     |
| --------- | ------- | ------------------------------- |
| `player`  | -       | Single player name or UUID      |
| `players` | -       | List of player names or UUIDs   |
| `server`  | -       | All players on a single server  |
| `servers` | -       | All players on multiple servers |

Player targeting

At least one of `player`, `players`, `server`, or `servers` must be provided.

## Example

```
rules:
  clear_title:
    triggers:
      - manual:
          id: 'cleartitle'  # Trigger with: /autostartstop trigger cleartitle <server_name>
    action:
      - clear_title:
          server: ${manual.args.0}  # Server name from command argument
```

This action will clear the title for all players on the specified server.

# show_bossbar Action

Shows a bossbar to one or more players. The bossbar can be hidden later using the `hide_bossbar` action with the same ID. See [hide_bossbar](https://beyenilmez.github.io/autostartstop/actions/player-communication/hide-bossbar.html) for more information.

## Configuration

```
action:
  - show_bossbar:
      player: PlayerName  # Single player
      players:            # Multiple players
        - Player1
        - Player2
      server: survival    # All players on server
      servers:            # All players on servers
        - survival
        - creative
      id: "maintenance"                              # Unique bossbar ID
      message: "<red>Maintenance in progress</red>"  # Message (MiniMessage format)
      color: WHITE                                   # Color (default: WHITE)
      overlay: PROGRESS                              # Overlay (default: PROGRESS)
      progress: 1.0                                  # Progress (0.0-1.0, default: 1.0)
```

## Configuration fields

| Field      | Default    | Description                                                                                    |
| ---------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `player`   | -          | Single player name or UUID                                                                     |
| `players`  | -          | List of player names or UUIDs                                                                  |
| `server`   | -          | All players on a single server                                                                 |
| `servers`  | -          | All players on multiple servers                                                                |
| `id`       | -          | Unique bossbar ID for later reference                                                          |
| `message`  | -          | Bossbar message in MiniMessage format                                                          |
| `color`    | `WHITE`    | Bossbar color. Valid values: `PINK`, `BLUE`, `RED`, `GREEN`, `YELLOW`, `PURPLE`, `WHITE`       |
| `overlay`  | `PROGRESS` | Overlay style. Valid values: `PROGRESS`, `NOTCHED_6`, `NOTCHED_10`, `NOTCHED_12`, `NOTCHED_20` |
| `progress` | `1.0`      | Progress value between 0.0 and 1.0                                                             |

Player targeting

At least one of `player`, `players`, `server`, or `servers` must be provided.

## Example

```
rules:
  show_bossbar:
    triggers:
      - manual:
          id: 'bossbar'  # Trigger with: /autostartstop trigger bossbar <server_name> <id> <message>
    action:
      - show_bossbar:
          server: ${manual.args.0}  # Server name from command argument
          id: ${manual.args.1}  # Bossbar ID from command argument
          message: ${manual.args.2}  # Message from command argument
          color: RED  # Bossbar color
          progress: 0.5  # Progress value (0.0-1.0)
```

This action will show a bossbar with the specified ID and message to all players on the specified server.

# hide_bossbar Action

Hides a bossbar from one or more players using the bossbar ID that was used when showing it.

## Configuration

```
action:
  - hide_bossbar:
      player: PlayerName  # Single player
      players:            # Multiple players
        - Player1
        - Player2
      server: survival    # All players on server
      servers:            # All players on servers
        - survival
        - creative
      id: "maintenance"   # Bossbar ID to hide
```

## Configuration fields

| Field     | Default | Description                                                   |
| --------- | ------- | ------------------------------------------------------------- |
| `player`  | -       | Single player name or UUID                                    |
| `players` | -       | List of player names or UUIDs                                 |
| `server`  | -       | All players on a single server                                |
| `servers` | -       | All players on multiple servers                               |
| `id`      | -       | Bossbar ID to hide (must match the ID used in `show_bossbar`) |

Player targeting

At least one of `player`, `players`, `server`, or `servers` must be provided.

## Example

```
rules:
  hide_bossbar:
    triggers:
      - manual:
          id: 'hidebossbar'  # Trigger with: /autostartstop trigger hidebossbar <server_name> <id>
    action:
      - hide_bossbar:
          server: ${manual.args.0}  # Server name from command argument
          id: ${manual.args.1}  # Bossbar ID to hide
```

This action will hide the bossbar with the specified ID from all players on the specified server.

# deny_ping Action

Denies a ping request, preventing the ping response from being sent. Use this action when a ping trigger has `hold_response: true` and you want to deny the ping request. See [ping](https://beyenilmez.github.io/autostartstop/triggers/ping.html) for more information.

## Configuration

```
action:
  - deny_ping:
      ping: ${ping}  # Ping event (default: ${ping})
```

## Configuration fields

| Field  | Default   | Description           |
| ------ | --------- | --------------------- |
| `ping` | `${ping}` | The ping event object |

## Example

```
rules:
  deny_ping:
    triggers:
      - ping:
          hold_response: true  # Hold the ping response
          virtual_host_list:  # Only trigger for ping requests from the specified virtual hosts
            mode: whitelist
            virtual_hosts:
              - mc.example.com
              - 192.168.1.100
    action:
      - deny_ping:  # Deny the ping request
          ping: ${ping}  # Ping event
```

This rule will deny ping requests for the specified virtual hosts.

# allow_ping Action

Allows a ping request to proceed normally. Use this action when a ping trigger has `hold_response: true` and you want to allow the ping request to proceed. See [ping](https://beyenilmez.github.io/autostartstop/triggers/ping.html) for more information.

## Configuration

```
action:
  - allow_ping:
      ping: ${ping}  # Ping event (default: ${ping})
```

## Configuration fields

| Field  | Default   | Description           |
| ------ | --------- | --------------------- |
| `ping` | `${ping}` | The ping event object |

## Example

```
rules:
  allow_ping:
    triggers:
      - ping:
          hold_response: true  # Hold the ping response
    action:
      - allow_ping:  # Allow the ping request to proceed
          ping: ${ping}  # Ping event
      - log:
          message: "Ping request replied for ${ping.player.remote_address}"
```

This action will allow the ping request to proceed normally for the specified ping event, and log a message to the console.

# respond_ping Action

Responds to a ping request with custom MOTD, version, and icon. Use this action when a ping trigger has `hold_response: true` and you want to respond to the ping request with custom ping data. See [ping](https://beyenilmez.github.io/autostartstop/triggers/ping.html) for more information.

Only modifies the ping response for the fields specified in the action configuration. Any fields not specified will use the existing ping response for that field.

## Configuration

```
action:
  - respond_ping:
      ping: ${ping}                         # Ping event (default: ${ping})
      use_cached_motd: true                 # Use cached MOTD if available
      use_backend_motd: false               # Use live backend MOTD (pings `${ping.server}`)
      motd: "<yellow>Custom MOTD</yellow>"  # Custom MOTD (MiniMessage format)
      version_name: "Custom Version"        # Version name
      protocol_version: -1                  # Protocol version
      icon: "/path/to/icon.png"             # Server icon (64x64 PNG)
```

## Configuration fields

| Field              | Default   | Description                                                                                                                                                                           |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ping`             | `${ping}` | The ping event object                                                                                                                                                                 |
| `use_cached_motd`  | `false`   | If `true`, uses cached MOTD if available                                                                                                                                              |
| `use_backend_motd` | `false`   | If `true`, uses live backend MOTD (pings `${ping.server}`). Requires `ping.server` to be set (done by [ping](https://beyenilmez.github.io/autostartstop/triggers/ping.html) trigger). |
| `motd`             | -         | Custom MOTD in MiniMessage format. Used when cached and backend MOTD are not used. Supports variables.                                                                                |
| `version_name`     | -         | Version name to display. Supports variables.                                                                                                                                          |
| `protocol_version` | -         | Protocol version (use `-1` to show version name text to clients)                                                                                                                      |
| `icon`             | -         | Server icon file path or base64 string (must be 64x64 PNG)                                                                                                                            |

MOTD cache and virtual hosts

To use `use_cached_motd: true`, you must configure `virtual_host` in the server configuration. The MOTD cache is organized by virtual host, and the cached MOTD is retrieved based on the client's virtual host from the ping request.

**Server configuration:**

```
servers:
  survival:
    virtual_host: play.example.com  # Virtual host for this server
```

**How it works:**

1. MOTD is cached automatically when:

   - A server is stopped by the plugin (via [`stop`](https://beyenilmez.github.io/autostartstop/actions/server-management/stop.html) or [`restart`](https://beyenilmez.github.io/autostartstop/actions/server-management/restart.html) actions)
   - Periodically at the interval specified in [`motd_cache_interval`](https://beyenilmez.github.io/autostartstop/configuration/settings.html#motd_cache_interval) setting

1. When `use_cached_motd: true` is used, the action retrieves the cached MOTD based on the client's virtual host from the ping request (`${ping.player.virtual_host}`).

1. MOTD priority: **cached** (if `use_cached_motd` and cache hit) → **backend** (if `use_backend_motd` and ping succeeds) → **motd** (custom).

See [Servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html#virtual-host) for server configuration details and [Settings](https://beyenilmez.github.io/autostartstop/configuration/settings.html#motd_cache_interval) for MOTD cache interval configuration.

## Example

```
rules:
  respond_ping:
    triggers:
      - ping:
          hold_response: true  # Hold the ping response
    conditions:
      mode: all
      checks:
        - server_status:
            server: survival
            status: offline  # Only respond if server is offline
    action:
      - respond_ping:
          ping: ${ping}  # Ping event
          use_cached_motd: true  # Use cached MOTD
          protocol_version: -1  # Force version name display as text
          version_name: "<blue>◉ Sleeping"  # Version name
```

This rule will respond to ping requests with a cached MOTD and custom version name when the server is offline.

# if Action

Executes actions conditionally based on condition checks. Supports `if`, `else_if`, and `else` branches.

## Configuration example

```
action:
  - if:
      mode: all  # Condition evaluation mode (default: all)
      checks:  # Condition checks
        - string_equals:
            value: ${_trigger_type}
            equals: manual
      then:  # Actions if conditions are true
        - log:
            message: "Manual trigger executed"
      else_if:  # Additional condition branches (can have multiple)
        - mode: all
          checks:
            - string_equals:
                value: ${_trigger_type}
                equals: cron
          then:
            - log:
                message: "Cron trigger executed"
        - mode: all
          checks:
            - string_equals:
                value: ${_trigger_type}
                equals: connection
          then:
            - log:
                message: "Connection trigger executed"
        - mode: all
          checks:
            - string_equals:
                value: ${_trigger_type}
                equals: ping
          then:
            - log:
                message: "Ping trigger executed"
      else:  # Actions if no conditions match
        - log:
            message: "Other trigger type executed"
```

## Configuration fields

| Field     | Default | Description                                                             |
| --------- | ------- | ----------------------------------------------------------------------- |
| `mode`    | `all`   | Condition evaluation mode: `all` (AND) or `any` (OR)                    |
| `checks`  | -       | List of condition checks                                                |
| `then`    | -       | Actions to execute if conditions are true                               |
| `else_if` | -       | List of additional condition branches with `mode`, `checks`, and `then` |
| `else`    | -       | Actions to execute if no conditions match                               |

Condition checks

The `checks` and `mode` fields work exactly the same as in [rule conditions](https://beyenilmez.github.io/autostartstop/conditions/index.html). You can use any available condition type (e.g., `server_status`, `player_count`, `string_equals`, `number_compare`) and the same evaluation modes (`all` or `any`).

# while Action

Executes actions repeatedly while conditions are met. Supports timeout and configurable update interval.

## Configuration

```
action:
  - while:
      mode: all  # Condition evaluation mode (default: all)
      checks:    # Condition checks
        - server_status:
            server: survival
            status: offline
      do:  # Actions to execute in loop
        - log:
            message: "Waiting for server to start..."
      timeout: 60s         # Maximum time to loop
      update_interval: 1s  # Time between iterations (default: 1s)
```

## Configuration fields

| Field             | Default | Description                                          |
| ----------------- | ------- | ---------------------------------------------------- |
| `mode`            | `all`   | Condition evaluation mode: `all` (AND) or `any` (OR) |
| `checks`          | -       | List of condition checks                             |
| `do`              | -       | Actions to execute in each loop iteration (optional) |
| `timeout`         | -       | Maximum time to loop (e.g., `60s`, `5m`)             |
| `update_interval` | `1s`    | Minimum time between loop iterations                 |

Condition checks

The `checks` and `mode` fields work exactly the same as in [rule conditions](https://beyenilmez.github.io/autostartstop/conditions/index.html). You can use any available condition type (e.g., `server_status`, `player_count`, `string_equals`, `number_compare`) and the same evaluation modes (`all` or `any`).

## Example

```
rules:
  auto_start_on_connection:
    triggers:
      - connection:
          server_list:
            mode: whitelist
            servers:
              - survival  # Only trigger for connections to survival server
    action:
      - start:
          server: ${connection.server.name}  # Start the server that player is trying to connect to
      - while:  # Wait for server to start
        timeout: 2m  # Maximum wait time
        update_interval: 2s  # Check every 2 seconds
        checks:
          - server_status:
              server: ${connection.server.name}
              status: offline
      - allow_connection:  # Allow the connection after server is ready
```

This rule will automatically start the server when a player tries to connect to it, wait for it to start, and then allow the connection.

# sleep Action

Waits for a specified duration before continuing to the next action.

## Configuration

```
action:
  - sleep:
      duration: 30s  # Duration (e.g., "30s", "1m", "2h")
```

## Configuration fields

| Field      | Default | Description                                                          |
| ---------- | ------- | -------------------------------------------------------------------- |
| `duration` | -       | The duration to wait. Supports formats like `30s`, `1m`, `2h`, `10t` |

Duration format

The `duration` field supports multiple formats:

- **Ticks**: `10t`, `20t` (1 tick = 50ms, 20 ticks per second)
- **Milliseconds**: `500ms`, `1000ms`
- **Seconds**: `1s`, `3s`, `5.5s`
- **Minutes**: `1m`, `2m`
- **Hours**: `1h`, `2h`

## Example

```
rules:
  sleep:
    triggers:
      - manual:
          id: 'wait'  # Trigger with: /autostartstop trigger wait
    action:
      - log:
          message: "Waiting 30 seconds..."  # Log before waiting
      - sleep:
          duration: 30s  # Wait for 30 seconds
      - log:
          message: "Wait complete!"  # Log after waiting
```

This rule will wait for 30 seconds between two log messages.

# log Action

Logs a message to the console at a specified log level.

## Configuration

```
action:
  - log:
      message: "Server started successfully"  # Message to log
      level: INFO                             # Log level (default: INFO)
```

## Configuration fields

| Field     | Default | Description                                                            |
| --------- | ------- | ---------------------------------------------------------------------- |
| `message` | -       | The message to log                                                     |
| `level`   | `INFO`  | The log level. Valid values: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` |

## Example

```
rules:
  log:
    triggers:
      - manual:
          id: 'log'  # Trigger with: /autostartstop trigger log <message>
    action:
      - log:
          message: ${manual.args.0}  # Message from command argument
          level: INFO  # Log level
```

This rule will log the specified message to the console at INFO level.

# exec Action

Executes a shell command with optional working directory, timeout, and environment variables.

## Configuration

```
action:
  - exec:
      command: './backup.sh'             # Command to execute
      working_directory: '/opt/scripts'  # Working directory
      timeout: 5m                        # Command timeout
      environment:                       # Environment variables
        BACKUP_DIR: '/backups'
        SERVER_NAME: survival
```

## Configuration fields

| Field               | Default | Description                                                     |
| ------------------- | ------- | --------------------------------------------------------------- |
| `command`           | -       | The shell command to execute                                    |
| `working_directory` | -       | The working directory for the command                           |
| `timeout`           | -       | Maximum time to wait for command completion (e.g., `5m`, `30s`) |
| `environment`       | -       | Environment variables as key-value pairs                        |

## Example

```
rules:
  exec:
    triggers:
      - manual:
          id: 'backup'  # Trigger with: /autostartstop trigger backup
    action:
      - exec:
          command: './backup.sh'  # Backup script
          working_directory: '/opt/minecraft/scripts'  # Script directory
          timeout: 10m  # Maximum execution time
          environment:
            SERVER_NAME: survival  # Environment variable
            BACKUP_DIR: '/backups/survival'  # Backup directory
```

This rule will execute a backup script with the specified environment variables.
# Templates

# Templates

Templates are pre-built rule configurations that simplify common automation scenarios. Instead of manually defining triggers, conditions, and actions, templates provide ready-to-use solutions for frequently needed patterns.

## Available templates

- **[start_on_proxy_start](https://beyenilmez.github.io/autostartstop/rule-templates/start-on-proxy-start.html)**: Starts servers when the proxy starts
- **[stop_on_proxy_shutdown](https://beyenilmez.github.io/autostartstop/rule-templates/stop-on-proxy-shutdown.html)**: Stops servers when the proxy shuts down
- **[start_on_connection](https://beyenilmez.github.io/autostartstop/rule-templates/start-on-connection.html)**: Starts a server when a player attempts to connect to it
- **[stop_on_empty](https://beyenilmez.github.io/autostartstop/rule-templates/stop-on-empty.html)**: Automatically stops servers after they've been empty for a specified duration
- **[respond_ping](https://beyenilmez.github.io/autostartstop/rule-templates/respond-ping.html)**: Customizes ping/MOTD responses based on server status

## Using templates

Templates are used in rules by specifying the `template` field instead of `triggers`, `conditions`, and `action`:

```
rules:
  <rule_name>:
    enabled: true              # Enable/disable rule (default: true)
    template: <template_name>  # Template type
    # ... template-specific configuration
```

Each template has its own configuration options. See the individual template documentation pages for details.

## Template vs. manual rules

Templates are convenient shortcuts for common patterns, but you can always achieve the same functionality using manual triggers, conditions, and actions. Templates internally use the same triggers and actions that are available for manual configuration.

# start_on_proxy_start Template

Automatically starts specified servers when the proxy starts. This is useful for keeping essential servers (like lobbies) always running.

## Configuration

```
rules:
  start_on_boot:
    template: start_on_proxy_start  # Template type
    servers: ['lobby', 'limbo']     # List of server names to start
```

## Configuration fields

| Field     | Default | Description                                          |
| --------- | ------- | ---------------------------------------------------- |
| `servers` | -       | List of server names to start when the proxy starts. |

## How it works

The `start_on_proxy_start` template:

1. Uses the [`proxy_start`](https://beyenilmez.github.io/autostartstop/triggers/proxy-start.html) trigger internally
1. Uses the [`start`](https://beyenilmez.github.io/autostartstop/actions/server-management/start.html) action to start servers

Servers are started in the order they are listed in the configuration.

# stop_on_proxy_shutdown Template

Automatically stops specified servers when the proxy shuts down. This ensures servers are properly stopped before the proxy closes.

## Configuration

```
rules:
  stop_on_shutdown:
    template: stop_on_proxy_shutdown  # Template type
    servers: ['survival', 'lobby']    # List of server names to stop
```

## Configuration fields

| Field     | Default | Description                                             |
| --------- | ------- | ------------------------------------------------------- |
| `servers` | -       | List of server names to stop when the proxy shuts down. |

## How it works

The `stop_on_proxy_shutdown` template:

1. Uses the [`proxy_shutdown`](https://beyenilmez.github.io/autostartstop/triggers/proxy-shutdown.html) trigger internally
1. Uses the [`stop`](https://beyenilmez.github.io/autostartstop/actions/server-management/stop.html) action to stop servers

Shutdown timeout

The proxy will wait for servers to stop, but only up to the configured [`shutdown_timeout`](https://beyenilmez.github.io/autostartstop/configuration/settings.html#shutdown_timeout). Make sure your servers can stop within this time, or increase the timeout in your configuration.

# start_on_connection Template

Automatically starts a server when a player attempts to connect to it. Supports multiple connection handling modes for different user experiences.

## Configuration

```
rules:
  auto_start:
    template: start_on_connection      # Template type
    servers: ['survival', 'creative']  # List of server names to monitor
    players: ['alice', 'bob']          # Optional: Filter by player names
    mode: waiting_server  # Connection handling mode: none, disconnect, hold, waiting_server
    # ... mode-specific configuration
```

## Configuration fields

| Field                | Default                                                                                                                              | Description                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `servers`            | -                                                                                                                                    | List of server names to monitor. At least one server must be specified.                                     |
| `players`            | -                                                                                                                                    | Optional list of player names to filter. If specified, only these players will trigger the template.        |
| `mode`               | `none`                                                                                                                               | Connection handling mode. See [Connection modes](#connection-modes) for details.                            |
| `disconnect_message` | `"<gold>${connection.server.name}</gold> is currently <gray>${${connection.server.name}.state}</gray>. Try again in a few seconds."` | Message to show when disconnecting player (for `disconnect` mode). Supports variables.                      |
| `waiting_server`     | -                                                                                                                                    | Configuration for `waiting_server` mode. See [Waiting server configuration](#waiting-server-configuration). |

## Connection modes

### `none`

Just starts the server without interfering with the connection. The player's connection attempt will fail if the server is offline, but the server will start in the background.

```
rules:
  start_background:
    template: start_on_connection
    servers: ['survival']
    mode: none
```

### `disconnect`

Denies the connection, starts the server, and disconnects the player with a message.

```
rules:
  start_and_disconnect:
    template: start_on_connection
    servers: ['survival']
    mode: disconnect
    disconnect_message: "<gold>${connection.server.name}</gold> is starting. Try again in a few seconds."
```

### `hold`

Denies the connection, starts the server, waits for it to come online, then allows the connection.

Hold mode timeout

Hold mode has a 30-second timeout. Only use this mode for servers that start quickly (under 30 seconds). For slower servers, use `waiting_server` mode instead.

```
rules:
  start_and_wait:
    template: start_on_connection
    servers: ['survival']
    mode: hold
```

### `waiting_server`

The most sophisticated mode. Denies the connection, sends the player to a waiting server (like a limbo), starts the target server, shows progress UI (title, bossbar, action bar), then connects the player when ready.

```
rules:
  start_with_waiting:
    template: start_on_connection
    servers: ['survival']
    mode: waiting_server
    waiting_server:
      server: limbo
      start_waiting_server_on_connection: true
      connect_error_message: '<red>Could not connect to ${connect_server}: ${connect_error_reason}</red>'
      message:
        enabled: false
        message: "<gold>${connection.server.name}</gold> <gray>is starting. You will be connected shortly.</gray>"
      progress_bar:
        enabled: true
        message: "${${connection.server.name}.startup_progress_percentage}%"
        progress: "${${connection.server.name}.startup_progress}"
        color: WHITE
        overlay: PROGRESS
      title:
        enabled: true
        title: "Please Wait..."
        subtitle: "<gold>${connection.server.name}</gold> <gray>is ${${connection.server.name}.state}. You will be connected shortly.</gray>"
        fade_in: 1s
        stay: 1h
        fade_out: 1s
      action_bar:
        enabled: false
        message: "Server is ${${connection.server.name}.state}"
```

## Waiting server configuration

When using `waiting_server` mode, you can configure the waiting experience:

| Field                                | Default                                                                        | Description                                                                                                                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server`                             | -                                                                              | Name of the waiting server, typically a `limbo` server                                                                                                                                    |
| `start_waiting_server_on_connection` | `true`                                                                         | If `true`, automatically starts the waiting server on connection if it's offline, works like hold mode                                                                                    |
| `connect_error_message`              | `"<red>Could not connect to ${connect_server}: ${connect_error_reason}</red>"` | MiniMessage sent to the player when connecting to the waiting server or target server fails. Supports variables: `connect_server` (server name), `connect_error_reason` (failure reason). |
| `message`                            | -                                                                              | Message configuration (see [below](#message-configuration))                                                                                                                               |
| `progress_bar`                       | -                                                                              | Bossbar/progress bar configuration (see [below](#progress-bar-configuration))                                                                                                             |
| `title`                              | -                                                                              | Title configuration (see [below](#title-configuration))                                                                                                                                   |
| `action_bar`                         | -                                                                              | Action bar configuration (see [below](#action-bar-configuration))                                                                                                                         |

### Message configuration

| Field     | Default                                                                                             | Description                                                            |
| --------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `enabled` | `false`                                                                                             | Enable/disable the message                                             |
| `message` | `"<gold>${connection.server.name}</gold> <gray>is starting. You will be connected shortly.</gray>"` | Message to send when player enters waiting server. Supports variables. |

### Progress bar configuration

| Field      | Default             | Description                                                                        |
| ---------- | ------------------- | ---------------------------------------------------------------------------------- |
| `enabled`  | `true`              | Enable/disable the progress bar                                                    |
| `message`  | Progress percentage | Bossbar message. Supports variables.                                               |
| `progress` | Startup progress    | Progress value (0.0-1.0). Supports variables.                                      |
| `color`    | `WHITE`             | Bossbar color: `PINK`, `BLUE`, `RED`, `GREEN`, `YELLOW`, `PURPLE`, `WHITE`         |
| `overlay`  | `PROGRESS`          | Bossbar overlay: `PROGRESS`, `NOTCHED_6`, `NOTCHED_10`, `NOTCHED_12`, `NOTCHED_20` |

### Title configuration

| Field      | Default                                                                                                                       | Description                        |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `enabled`  | `true`                                                                                                                        | Enable/disable the title           |
| `title`    | `"Please Wait..."`                                                                                                            | Title text. Supports variables.    |
| `subtitle` | `"<gold>${connection.server.name}</gold> <gray>is ${${connection.server.name}.state}. You will be connected shortly.</gray>"` | Subtitle text. Supports variables. |
| `fade_in`  | `1s`                                                                                                                          | Fade-in duration                   |
| `stay`     | `1h`                                                                                                                          | How long the title stays visible   |
| `fade_out` | `1s`                                                                                                                          | Fade-out duration                  |

### Action bar configuration

| Field     | Default                                          | Description                             |
| --------- | ------------------------------------------------ | --------------------------------------- |
| `enabled` | `false`                                          | Enable/disable the action bar           |
| `message` | `"Server is ${${connection.server.name}.state}"` | Action bar message. Supports variables. |

## How it works

The `start_on_connection` template internally uses the following components:

- **[connection](https://beyenilmez.github.io/autostartstop/triggers/connection.html) trigger**: Detects when a player attempts to connect to a server.
- **[start](https://beyenilmez.github.io/autostartstop/actions/server-management/start.html) action**: Starts the target server when a connection attempt is detected. The action automatically tracks server startup progress, making startup variables available for use in UI elements.
- **Connection handling actions** (depending on mode):
- **[allow_connection](https://beyenilmez.github.io/autostartstop/actions/player-management/allow-connection.html)**: Used in `hold` and `waiting_server` modes to allow the connection after the server is ready
- **[connect](https://beyenilmez.github.io/autostartstop/actions/player-management/connect.html)**: Used in `waiting_server` mode to connect the player to the target server
- **Player communication actions** (for `waiting_server` mode):
- **[send_message](https://beyenilmez.github.io/autostartstop/actions/player-communication/send-message.html)**: Sends initial message when player enters waiting server
- **[send_title](https://beyenilmez.github.io/autostartstop/actions/player-communication/send-title.html)**: Shows title with server status updates
- **[show_bossbar](https://beyenilmez.github.io/autostartstop/actions/player-communication/show-bossbar.html)**: Displays progress bar showing startup progress
- **[send_action_bar](https://beyenilmez.github.io/autostartstop/actions/player-communication/send-action-bar.html)**: Shows action bar with server status

The template monitors the server startup process and automatically updates UI elements (in `waiting_server` mode) with real-time progress information.

## Available variables

This template provides access to variables from the [connection trigger](https://beyenilmez.github.io/autostartstop/triggers/connection.html#context-variables), which includes player and server information from the connection event. Additionally, you can use [global server variables](https://beyenilmez.github.io/autostartstop/variables.html#global-server-variables) to access server state and startup progress information.

For example:

- `connection.server.name` - The name of the server the player is trying to connect to
- `connection.player.name` - The name of the player attempting to connect
- `${connection.server.name}.state` - Current state of the target server (e.g., `starting`, `online`, `offline`)
- `${connection.server.name}.startup_progress` - Startup progress (0.0-1.0) for progress bars
- `${connection.server.name}.startup_progress_percentage` - Startup progress (0-100) for display

See the [connection trigger documentation](https://beyenilmez.github.io/autostartstop/triggers/connection.html#context-variables) for all available context variables and the [Variables](https://beyenilmez.github.io/autostartstop/variables.html#global-server-variables) page for global server variables.

# stop_on_empty Template

Automatically stops servers after they've been empty (no players) for a specified duration.

## Configuration

```
rules:
  auto_stop_empty:
    template: stop_on_empty  # Template type
    empty_time: 15m  # Duration server must be empty before stopping (default: 15m)
    servers: ['survival', 'creative']   # List of server names to monitor
```

## Configuration fields

| Field        | Default | Description                                                                                                |
| ------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| `empty_time` | `15m`   | Duration the server must be empty before stopping. Supports duration formats like `15m`, `1h`, `30s`, etc. |
| `servers`    | -       | List of server names to monitor. At least one server must be specified.                                    |

## How it works

The `stop_on_empty` template:

1. Uses the [`empty_server`](https://beyenilmez.github.io/autostartstop/triggers/empty-server.html) trigger internally to detect empty servers
1. Uses the [`stop`](https://beyenilmez.github.io/autostartstop/actions/server-management/stop.html) action to stop servers

Check [`empty_server`](https://beyenilmez.github.io/autostartstop/triggers/empty-server.html) trigger for more information.

# respond_ping Template

Customizes ping/MOTD responses based on server status. This allows you to show different information when a server is online vs. offline, such as showing a "sleeping" status for offline servers.

## Configuration

```
rules:
  custom_ping:
    template: respond_ping
    virtual_hosts:  # List of virtual hosts to handle
      - play.example.com
      - mc.example.com
    servers:        # List of server names (maps to virtual_hosts from config)
      - survival
      - creative
    offline:        # Configuration for when server is offline
      use_cached_motd: true
      use_backend_motd: false
      motd: ""
      version_name: "<blue>◉ Sleeping"
      protocol_version: -1
      icon: "/path/to/offline-icon.png"
    online:         # Configuration for when server is online
      use_cached_motd: false
      use_backend_motd: false
      motd: ""
      version_name: ""
      protocol_version: -1
      icon: "/path/to/online-icon.png"
```

## Configuration fields

| Field           | Default | Description                                                                                                                                                                                                                                                                                                   |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `virtual_hosts` | -       | List of virtual hosts to handle. At least one of `virtual_hosts` or `servers` must be specified.                                                                                                                                                                                                              |
| `servers`       | -       | List of server names to handle. Maps server names to their `virtual_host` values from the `servers:` configuration. Check [servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html#virtual-host) for more information. At least one of `virtual_hosts` or `servers` must be specified. |
| `offline`       | -       | Configuration for when the server is offline. At least one of `offline` or `online` must be specified.                                                                                                                                                                                                        |
| `online`        | -       | Configuration for when the server is online. At least one of `offline` or `online` must be specified.                                                                                                                                                                                                         |

### Offline/Online configuration

Both `offline` and `online` sections support the same fields:

| Field              | Default | Description                                                                                                                                |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `use_cached_motd`  | false   | If `true`, uses the cached MOTD from when the server was last online. If `false` or not specified, uses the `motd` field.                  |
| `use_backend_motd` | false   | If `true`, uses the live backend server MOTD.                                                                                              |
| `motd`             | -       | Custom MOTD text (MiniMessage format). Used when cached and backend MOTD are not used. Supports variables.                                 |
| `version_name`     | -       | Custom version name text (MiniMessage format). Use with `protocol_version: -1` to show custom text instead of version. Supports variables. |
| `protocol_version` | -       | Protocol version number. Use `-1` to show `version_name` as text instead of a version number.                                              |
| `icon`             | -       | Server icon. Can be a file path or base64-encoded png image string. Must be 64x64 pixels.                                                  |

At least one config required

You must specify at least one of `offline` or `online`. If you only specify one, the template will only modify respond to pings when the server is in that state.

Note

Any field can be omitted, and the template will not modify the existing ping response for that field.

## How it works

The `respond_ping` template:

1. Uses the [`ping`](https://beyenilmez.github.io/autostartstop/triggers/ping.html) trigger internally with `hold_response: true`
1. Finds the server associated with the virtual host
1. Checks if the server is online or offline
1. Selects the appropriate configuration based on server status
1. Uses the [`respond_ping`](https://beyenilmez.github.io/autostartstop/actions/ping-management/respond-ping.html) action to send the custom response

The template matches virtual hosts by comparing them (case-insensitive) with the `virtual_host` configured in each server's configuration. Check [servers](https://beyenilmez.github.io/autostartstop/configuration/servers.html#virtual-host) for more information.

## Examples

### Show "sleeping" status for offline servers

```
rules:
  sleeping_server:
    template: respond_ping
    servers: ['survival']
    offline:
      use_cached_motd: true
      version_name: "<blue>◉ Sleeping"
      protocol_version: -1
      icon: icons/sleeping-icon.png
```

When the server is offline, it will show "◉ Sleeping" as the version name and use the cached MOTD. When online, it uses the default server response.

### Custom MOTD for both states

```
rules:
  custom_motd:
    template: respond_ping
    virtual_hosts: ['survival.example.com']
    offline:
      motd: "<red>Server is offline</red>\n<gray>Check back later!</gray>"
      version_name: "<red>Offline</red>"
      protocol_version: -1
    online:
      motd: "<green>Welcome to Survival!</green>\n<yellow>Join now!</yellow>"
      version_name: "<green>Online</green>"
      protocol_version: -1
```

### Different icons for online/offline

```
rules:
  custom_icons:
    template: respond_ping
    virtual_hosts: ['play.example.com']
    offline:
      icon: "/icons/offline.png"
    online:
      icon: "/icons/online.png"
```

### Online-only configuration

```
rules:
  online_only:
    template: respond_ping
    virtual_hosts: ['play.example.com']
    online:
      motd: "<green>Welcome!</green>"
      version_name: "<green>Online</green>"
      protocol_version: -1
```

This will only customize the ping response when the server is online. When offline, the ping will proceed normally (no custom response).
# Examples

# Examples

This section contains real-world configuration examples that demonstrate how to use AutoStartStop in various scenarios.

## Available Examples

- **[Auto Start/Stop with Custom Ping Response](https://beyenilmez.github.io/autostartstop/examples/auto-start-stop-with-custom-ping-response.html)**: Demonstrates automatic server starting, stopping, and custom ping/MOTD responses based on server status.
- **[Scheduled Restart](https://beyenilmez.github.io/autostartstop/examples/scheduled-restart-with-proxy-start.html)**: Demonstrates automatic server starting on proxy startup and scheduled restarts using cron expressions.
- **[Hourly Random Reward](https://beyenilmez.github.io/autostartstop/examples/hourly-random-reward.html)**: Demonstrates scheduled command execution to reward random players with items using cron triggers.

# Auto Start/Stop with Custom Ping Response

This example demonstrates AutoStartStop's core automation features: automatic server starting, stopping, and custom ping/MOTD responses. The configuration shows how to automatically start servers when players connect, stop them when empty, and customize server list responses based on server status.

## Configuration

```
defaults:
  server:
    control_api:
      type: 'amp'
      ads_url: 'http://localhost:8080/'
      username: 'instance_management_bot'
      password: '123456789+Abc'
    startup_timer:
      auto_calculate_expected_startup_time: true

servers:
  smp:
    virtual_host: smp.example.com
    control_api:
      instance_id: 'f790deae-3fde-4049-8085-c51b19522526'
  limbo:
    control_api:
      instance_id: '8172f21e-5a16-473f-a3f1-12731a6b358a'

rules:
  start_on_proxy_start:
    template: 'start_on_proxy_start'
    servers: [limbo]

  stop_on_proxy_shutdown:
    template: 'stop_on_proxy_shutdown'
    servers: [limbo, smp]

  start_on_connection:
    template: 'start_on_connection'
    servers: [smp]
    mode: waiting_server
    waiting_server:
      server: limbo
      start_waiting_server_on_connection: true

  stop_on_empty:
    template: 'stop_on_empty'
    empty_time: 15m
    servers: [smp]

  respond_ping_smp:
    template: 'respond_ping'
    servers: [smp]
    offline:
      use_cached_motd: true
      version_name: '<blue>◉ Sleeping'
      protocol_version: -1
      icon: icons/smp-sleeping.png
    online:
      icon: icons/smp-icon.png
```

## Server Icons

The following icons are placed in the `icons` directory:

- **`icons/smp-sleeping.png`**

  ______________________________________________________________________

  SMP server icon when offline

- **`icons/smp-icon.png`**

  ______________________________________________________________________

  SMP server icon when online

Icon Requirements

Server icons must be 64x64 pixel PNG images. You can place them in any directory accessible to the plugin.

## What This Configuration Does

This configuration demonstrates AutoStartStop's key automation features:

1. **Auto-start on connection**: Servers start automatically when players try to connect
1. **Auto-stop when empty**: Servers stop automatically after being idle
1. **Graceful shutdown**: All servers stop cleanly when the proxy shuts down
1. **Custom ping responses**: Server list shows different information based on server status

## Demo

Here's a demonstration of the configuration in action:

# Scheduled Restart

This example demonstrates how to configure AutoStartStop to automatically start servers when the proxy starts, stop them gracefully when the proxy shuts down, and perform scheduled restarts using cron expressions. This is useful for maintaining server health, ensuring clean shutdowns, and keeping servers available when the proxy comes online.

## Configuration

```
defaults:
  server:
    control_api:
      type: 'amp'
      ads_url: 'http://localhost:8080/'
      username: 'instance_management_bot'
      password: '123456789+Abc'

servers:
  survival:
    control_api:
      instance_id: 'd8014792-89c8-4392-86f5-4023c3108f2c'
  creative:
    control_api:
      instance_id: 'f648dfa1-e9c7-4291-80a5-7bc9da28c171'

rules:
  start_on_proxy_start:
    template: 'start_on_proxy_start'
    servers: [survival, creative]

  stop_on_proxy_shutdown:
    template: 'stop_on_proxy_shutdown'
    servers: [survival, creative]

  daily_restart:
    triggers:
      - cron:
          format: 'UNIX'  # Available formats: UNIX, QUARTZ, CRON4J, SPRING, SPRING53
          expression: '0 3 * * *'  # Every day at 3 AM
          time_zone: 'UTC+00:00'
    action:
      - send_message:
          servers: [survival, creative]
          message: "<yellow>Server will restart in 1 minute.</yellow>"
      - sleep:
          duration: 1m
      - restart:
          server: survival
          wait_for_completion: false # Run asynchronously
      - restart:
          server: creative
      - log:
          message: "Daily restart completed at ${cron.actual_time}"
```

Cron Expressions

Cron expressions allow you to schedule tasks at specific times. The format used in this example is UNIX cron format:

- `0 3 * * *` means "at 3:00 AM every day"
- `0 4 * * 0` means "at 4:00 AM every Sunday"

You can use [crontab.guru](https://crontab.guru) to help create and understand UNIX cron expressions. The plugin supports multiple cron formats (UNIX, QUARTZ, CRON4J, SPRING, SPRING53) and time zones.

## What This Configuration Does

This configuration demonstrates scheduled server management:

1. **Auto-start on proxy start**: Both servers start automatically when the proxy starts, ensuring they're ready for players immediately
1. **Auto-stop on proxy shutdown**: All servers stop cleanly when the proxy shuts down
1. **Daily restart**: The servers restart every day at 3 AM UTC

# Hourly Random Reward

This example demonstrates how to use AutoStartStop to automatically send commands to servers on a schedule. In this case, a random player receives a diamond every hour, creating an engaging reward system for your players.

## Configuration

```
servers:
  survival:
    control_api:
      type: 'amp'
      ads_url: 'http://localhost:8080/'
      username: 'instance_management_bot'
      password: '123456789+Abc'
      instance_id: 'd8014792-89c8-4392-86f5-4023c3108f2c'

rules:
  hourly_diamond_reward:
    triggers:
      - cron:
          format: 'UNIX'  # Available formats: UNIX, QUARTZ, CRON4J, SPRING, SPRING53
          expression: '0 * * * *'  # Every hour at minute 0
          time_zone: 'UTC+00:00'
    action:
      - send_command:
          server: survival
          command: "give @r diamond 1"
```

Cron Expressions

The cron expression `0 * * * *` means "at minute 0 of every hour" (i.e., every hour on the hour). You can adjust this to run at different intervals:

- `0 * * * *` - Every hour at minute 0
- `*/30 * * * *` - Every 30 minutes
- `0 */2 * * *` - Every 2 hours at minute 0
- `0 12,18 * * *` - At 12:00 PM and 6:00 PM daily

You can use [crontab.guru](https://crontab.guru) to help create and understand UNIX cron expressions. The plugin supports multiple cron formats (UNIX, QUARTZ, CRON4J, SPRING, SPRING53) and time zones.

## What This Configuration Does

Every hour, a random player on the survival server receives a diamond

## Variation: Multiple Rewards

```
hourly_rewards:
  triggers:
    - cron:
        expression: '0 * * * *'
  action:
    - send_command:
        server: survival
        command: "give @r diamond 1" # Give 1 diamond to a random player
    - send_command:
        server: survival
        command: "give @a[limit=2,sort=random] emerald 2" # Give 2 emeralds to 2 random players
    - send_command:
        server: survival
        command: "give @a[limit=4,sort=random] gold_ingot 5" # Give 5 gold ingots to 4 random players
```
# Guides

# Guides

Step-by-step guides to help you set up and configure AutoStartStop.

## Available guides

- **[AMP Control API User Setup](https://beyenilmez.github.io/autostartstop/guides/amp-user-setup.html)**: Learn how to create and configure a dedicated user for the AMP control API integration

# AMP Control API User Setup

This guide walks you through creating a dedicated user account in AMP for use with AutoStartStop's control API integration.

## Why create a dedicated user?

Creating a dedicated user for the plugin is recommended for several reasons:

- **Security and permission management**: This allows you to grant only the necessary permissions without exposing your main admin account
- **Session management**: Using your own user account can cause issues with features like "Remember Me" and sticky sessions, which may interfere with the plugin's authentication

## Step 1: Create a new user

1. Navigate to your **base ADS instance configuration**
1. Go to **User Management**
1. Click **Create User**
1. Enter a username (e.g., `instance_management_bot`)
1. Set a secure password and save it in a safe location
1. Keep the following options disabled:
   - **Password Expires**
   - **Require Password Change**

## Step 2: Configure permissions

You can either grant all permissions or configure specific permissions. For better security, we recommend using the minimum required permissions.

### Required permissions

The user needs permissions to manage the instances you want to control:

1. **All Instances** → **Local Instances** → **[Your ADS Instance]** → **Manage**

   - The "Local Instances" section name may vary depending on your setup
   - Typically, your ADS instance name is something like `ADS01`

1. **All Instances** → **Local Instances** → **[Target Instance]** → **Start, Stop, and Manage permissions**

   - Replace `[Target Instance]` with the specific instance you want AutoStartStop to manage

### Setting permissions

You can configure permissions in two ways:

- **Edit User Permissions**: Click on the user and select "Edit User Permissions"
- **Use a Role**: Create or assign a role with the required permissions

## Step 3: Configure AutoStartStop

Once you have created the user and configured permissions, add the credentials to your AutoStartStop configuration:

```
defaults:
  server:
    control_api:
      type: 'amp'
      ads_url: 'http://localhost:8080/'
      username: 'instance_management_bot'  # The username you created
      password: 'your_password'            # The password you set
```

After completing this setup, your AutoStartStop plugin will be able to control your AMP instances using the dedicated user account.

For more details about these configuration options, see the [AMP Control API documentation](https://beyenilmez.github.io/autostartstop/control-api/amp.html).
# Credits

# Credits

## License

This project is licensed under the **GNU General Public License v3.0 (GPL-3.0)**. For the full license text, please visit [GNU GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.html).

## Third-Party Libraries

AutoStartStop uses the following open-source libraries and frameworks:

| Library                                                                       | Version  | Description                            | License    |
| ----------------------------------------------------------------------------- | -------- | -------------------------------------- | ---------- |
| [Velocity API](https://github.com/PaperMC/Velocity)                           | 3.4.0    | Velocity proxy framework API           | GPL-3.0    |
| [BoostedYAML](https://github.com/dejvokep/boosted-yaml)                       | 1.3.7    | Configuration management library       | Apache-2.0 |
| [AMP API](https://github.com/p0t4t0sandwich/ampapi/blob/main/readmes/Java.md) | 2620.4.0 | AMP API library                        | MIT        |
| [Result4j](https://github.com/sviperll/result4j)                              | 1.2.0    | Result type implementation for Java    | Apache-2.0 |
| [Cron Utils](https://github.com/jmrozanec/cron-utils)                         | 9.2.1    | Cron expression parsing and scheduling | Apache-2.0 |
| [Gson](https://github.com/google/gson)                                        | 2.13.2   | JSON parsing library                   | Apache-2.0 |
| [GitHub API](https://github.com/hub4j/github-api)                             | 1.330    | GitHub API client for update checker   | MIT        |
| [bStats](https://github.com/Bastian/bStats)                                   | 3.2.1    | Metrics library                        | MIT        |

## Testing Libraries

The following libraries are used for testing:

| Library                                               | Version | Description                      | License |
| ----------------------------------------------------- | ------- | -------------------------------- | ------- |
| [JUnit Jupiter](https://github.com/junit-team/junit5) | 6.0.3   | Unit testing framework for Java  | EPL-2.0 |
| [Mockito](https://github.com/mockito/mockito)         | 5.21.0  | Mocking framework for unit tests | MIT     |

## Documentation Tools

The documentation for AutoStartStop is built using the following tools and frameworks:

| Tool                                                                                        | Version | Description                                     | License      |
| ------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------- | ------------ |
| [MkDocs](https://www.mkdocs.org/)                                                           | 1.6.1   | Static site generator for project documentation | BSD-2-Clause |
| [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)                         | 9.7.1   | Material Design theme for MkDocs                | MIT          |
| [MkDocs Minify Plugin](https://github.com/byrnereese/mkdocs-minify-plugin)                  | 0.8.0   | Plugin for minifying HTML output                | MIT          |
| [MkDocs Include Markdown Plugin](https://github.com/mondeja/mkdocs-include-markdown-plugin) | 7.2.1   | Plugin for including markdown files in MkDocs   | Apache-2.0   |
| [MkDocs LLMsTxt Plugin](https://github.com/pawamoy/mkdocs-llmstxt)                          | 0.5.0   | Plugin for generating AI-friendly documentation | ISC          |

## Additional Resources

The following additional resources are used in the AutoStartStop project:

| Resource                                               | Description                   | License                                                                         |
| ------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- |
| [Beaver Punch](https://fontesk.com/beaver-punch-font/) | Display font used in the logo | [Free for commercial use](https://fontesk.com/license/free-for-commercial-use/) |