Installation

AppelTools comes in two halves. You install both.

Half	Jar	What it does
The proxy	AppelTools-Velocity.jar	Everything that crosses servers: the punishments, the friends, the parties, the private messages, the reports, the Discord bot, the maintenance mode, the restarts and the two-factor.
The backend	AppelTools-Paper.jar	Everything that lives inside one game server: the teleport, the homes, the economy, the gamemodes, the speed and the staff tools.

The two halves talk to each other over the same MySQL database. That shared database is why a ban on one server counts on the next one, and why a balance is the same on every server of the network.

What you need

	Requirement
Java	Java 25 or newer, on the proxy and on every backend.
Proxy	Velocity 4.2.0 or newer.
Backend	Paper 26.3 or newer (the plugin asks for api-version 1.21).
Database	MySQL or MariaDB.
Permissions	LuckPerms, on the proxy and on every backend.

On the backend you also need:

Plugin	Why
Vault	The economy is exposed to other plugins through Vault.
PremiumVanish	The vanish tool of the staff mode runs its /vanish command.

On the proxy, vpacketevents is used as well.

TIP

The backend downloads the MySQL driver, the connection pool and the logger itself the first time it starts, so you do not have to install them.

The database

Create the database yourself; the plugin creates the tables inside it.

CREATE DATABASE appeltools CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Give the user of the plugin the rights it needs. The plugin creates the tables, adds columns, adds indexes and renames tables when it migrates the schema:

CREATE USER 'appeltools'@'localhost' IDENTIFIED BY 'a-strong-password';
GRANT ALL PRIVILEGES ON appeltools.* TO 'appeltools'@'localhost';
FLUSH PRIVILEGES;

The schema is migrated by the plugin itself, on every start. The version that is applied is kept in the table schema_version. When a migration cannot be applied, it stays pending and every migration after it waits — so a failing migration stops the plugin, instead of leaving you with half a schema.

The order of the installation

1. Set up the database.
2. Install LuckPerms on the proxy and on every backend.
3. Install the proxy jar in plugins/ of the proxy.
4. Install the backend jar in plugins/ of every game server.
5. Start the proxy. It writes plugins/appeltoolsvelocity/config.yml.
6. Start a backend. It writes plugins/AppelToolsPaper/config.yml.
7. Fill in the database section of both files with the same database.
8. Fill in the server section of both files: the name, the address and the locale.
9. Give the staff their permissions. See the permissions.
10. Start the proxy and the backends again and check the log for errors.

TIP

Install the proxy first. The proxy is what knows which backends exist and how to reach them; a backend that starts before the proxy does not find its way home.

The configuration files

After the first start you have:

plugins/
├── appeltoolsvelocity/       the proxy
│   ├── config.yml
│   ├── messages.yml
│   └── data.yml
└── AppelToolsPaper/          the backend
    ├── config.yml
    ├── messages.yml
    └── data.yml

messages.yml is written on the first start with every message of the plugin and its default text. Change the text, not the key: a key that the plugin does not know is ignored.

data.yml belongs to the plugin. It holds the identity of the server — the UUID that the backend uses to tell one server from another. Do not edit it by hand.

Every key of config.yml is listed in the configuration page.

Required plugins

Both halves have a required-plugins key in config.yml. It is a list of plugin names; when one of them is missing, the plugin switches the server to whitelist mode — everybody without appeltools.command.staff is kicked and cannot join. It is empty by default.

required-plugins:
  - LuckPerms

The check runs when the server starts and again on every /atp reload. On the proxy it also sends a message to the Discord log channel.

WARNING

The comment in the shipped config.yml says that the server fails to start when a required plugin is missing. It does not — it switches the whitelist on. The LuckPerms, Vault and PremiumVanish plugins that the backend really needs are enforced by the plugin descriptor instead: the backend does not load without them.

Checking that it works

• /atv help and /atp help list the commands that are available to you.
• /atp health shows the state of the plugin on the backend: the database, the tasks and the players.
• /versionlist shows the plugins of the server with their versions.
• The log of both halves should have no errors after the start.

If something does not work, the FAQ lists the problems that come up most.