AppelTools — Complete Reference Documentation

Comprehensive technical reference for the AppelTools Minecraft server plugin suite. Detailed enough to allow complete reconstruction from scratch. Every class, command, event, configuration, database table, permission node, and cross-server interaction is documented.

Table of Contents

1. Project Overview
2. Build System
3. Module Architecture
4. Database Schema (MySQL)
5. Common Module Reference
6. Paper Module Reference
7. Velocity Module Reference
8. Plugin Messaging Channels
9. Permissions Reference
10. Discord Integration
11. Plugin Updater
12. Chat Filter & Moderation
13. Cross-Server Synchronization
14. Configuration Files
15. Resource Files
16. Rebuilding From Scratch
17. File Index

---

Quick Reference

AppelTools is a coordinated Paper + Velocity plugin suite for the AppelCraft server network. Both share a single MySQL database and a common Java library (AppelTools-Common).

Modules

• common — shared library (AppelTools-Common.jar). Pure Java, no Bukkit/Velocity classes.
• paper — Paper 26.3 server plugin (AppelTools-Paper.jar). Gameplay commands, economy, staff tools.
• velocity — Velocity 4.2 proxy plugin (AppelTools-Velocity.jar). Cross-server moderation, friends, parties, reports.

Features

• Moderation: ban, tempban, IP ban, mute, IP mute, kick, with full history and undo.
• Economy: per-server balances, payment toggle, /baltop, Vault hook.
• Teleport: /tp, /tpa, /tpahere, /tphere, /tppos, /back, /tptoggle, /tpauto.
• Homes: per-server player homes (/home, /sethome, /delhome confirm flow, /renamehome).
• Speed & Flight: /speed, /walkspeed, /flyspeed, /fly.
• Gamemode: /gamemode, /gmc, /gms, /gma, /gmsp.
• Friends: cross-server friend list, requests, notifications, toggles.
• Parties: cross-server parties (invite, warp, promote/demote/transfer/mute/allinvite).
• Private Messaging: /msg, /reply, /ignore, /unignore, /messagetoggle, cross-server.
• Chat: per-player channels (global/party/message/staff), filter, anti-advertising, cross-server chat queue.
• Reports: /report, /reports list/remove, Discord notifications.
• Staff Tools: staff mode tool kit, freeze, notes GUI, invsee, vanish, broadcast, staff list/version list, staff chat, staff spy.
• Staff Notes: add/remove/list; Discord watchlist embed.
• Maintenance: proxy-wide maintenance, MOTD/version/icon override, kicks non-bypass players.
• Server Management: /servers register/unregister/list.
• Restart: scheduled proxy restart with countdown broadcasts.
• Plugin Updater: check/download/install updates from Jenkins, SpigotMC, Modrinth, Hangar, GitHub, Geyser.
• Discord Bot (JDA): full logging of reports, staff notes, freezes, missing plugins, punishments, joins/leaves, restarts, maintenance, log search.
• Plugin Checker: enforces required plugins; kicks non-staff if any are missing.
• Whitelist: per-Paper emergency whitelist flag.

Technology Stack

Component	Library / API
Build	Gradle 9+ with com.gradleup.shadow 9.3.2
Java	OpenJDK 25
Annotations	JetBrains annotations 26.0.2
Boilerplate	Lombok 1.18.40
JSON	Gson 2.15.0
Utilities	Guava 33.8.0-jre
Chat	Adventure API 4.26.1 (MiniMessage)
Config	ConfigLib 4.8.1 (YAML)
Permissions	LuckPerms API 5.5
Database	MySQL Connector/J 26.10.0, HikariCP 7.1.0
Logging	SLF4J 2.0.20, Logback 1.6.6 (paper)
Discord	JDA 6.7.0
Commands	LiteCommands 3.11.0 (Bukkit + Velocity + JDA flavors)
Server platform	Paper API 1.21.11-R0.1-SNAPSHOT
Proxy platform	Velocity API 4.2.0
Vault	VaultAPI 1.7
Vanish	PremiumVanishAPI 2.9.18-2
Plugin messaging (Velocity)	vPacketEvents 1.1.0
SSH deploy	sshj 0.40.0

Repository Layout

AppelTools/
├── build.gradle             # root: deploy tasks, version, repositories
├── settings.gradle          # includes common, paper, velocity
├── common/                  # shared library
├── paper/                   # Paper plugin
├── velocity/                # Velocity plugin
├── CLAUDE.md                # developer quick-start
└── docs/                    # this reference

Build Commands

./gradlew build                # build all modules
./gradlew build -x test        # skip tests
./gradlew test                 # run all tests
./gradlew deployDev            # clean, build, SFTP to dev servers
./gradlew deployProd           # clean, build, SFTP to dev + prod

Inter-Module Wiring

┌──────────────┐  plugin messages   ┌──────────────────────┐
│   Velocity   │ ─────────────────▶ │   Paper (each node)  │
│   Proxy      │ ◀───────────────── │                      │
└──────┬───────┘                    └──────────┬───────────┘
       │                                      │
       └─────────────► MySQL ◄────────────────┘

Paper and Velocity share the same MySQL database but do not share a JVM. They synchronize via Velocity plugin-message channels (see 08-messaging.md).

---

See the linked sections for full details.