6. Paper Module Reference

paper/ produces AppelTools-Paper.jar, a standard paper-plugin.yml plugin for Paper 26.3. It contains gameplay commands, the per-server economy, staff tools (vanish, invsee, freeze, notes GUI), staff mode, and the Velocity plugin-message listener.

6.1 Bootstrap and Lifecycle

paper-plugin.yml

• name: AppelTools
• main: me.Maussee.AppelTools.paper.AppelToolsPaperLoader
• version: ${version} (substituted from build.gradle)
• description: ${description}
• author: ${author}
• api-version: '1.21'
• dependencies: — declares LuckPerms, Vault, PremiumVanish.
• The descriptor has no libraries: section: MySQL, HikariCP, ConfigLib, LiteCommands and the rest are shaded into the jar and moved under their own namespace.
• folia-supported: false

AppelToolsPaperLoader

Standard PluginLoader. Constructor builds the AppelToolsPaperBootstrap and passes itself as JavaPlugin.

AppelToolsPaperBootstrap extends JavaPlugin

• onEnable() — calls new AppelToolsPaper(this).enable().
• onDisable() — calls AppelToolsPaper.get().shutdown().

AppelToolsPaper lifecycle

See §3.7. The bootstrap performs:

1. Set paths/data dir; throw StartupException on failure.
2. Load config.yml, messages.yml, data.yml via YamlStore.
3. Set Locale from Config.ServerInfo.LOCALE; set serverName from Config.ServerInfo.NAME.
4. Generate/persist serverUuid (random) if unset.
5. Resolve LuckPerms provider; throw if missing.
6. Register VaultEconomyProvider and resolve it back.
7. Create player manager, console, baltop calculator.
8. Create all DAOs.
9. Setup Database (Hikari pool) and async-load ServerData for the server's port.
10. Create CommandRegistrar and ModuleManager; load modules and register commands.
11. Create StaffInventoryManager.
12. If Modules.Discord.ROOT.isEnabled() and token non-empty, load DiscordBot with commands (filtering Bukkit listeners out).
13. Run PluginChecker.checkPlugins().
14. Create PluginUpdaterManager.
15. playerManager.startAutoSaveTask() (5-minute interval).

onShutdown() stops auto-save, awaits saves, unregisters commands, unloads Discord, disconnects DB.

6.2 Types/ package

ATPPlayer extends ATUserAdapter

A per-player wrapper around org.bukkit.entity.Player:

Field	Type	Source
player	Player	constructor
name	String	player.getName()
uuid	UUID	player.getUniqueId()
data	ATPlayerData	cache
serverData	ATPlayerServerData	cache
currentChannel	ChatChannel	GLOBAL/PARTY/MESSAGE/STAFF

Implements:

• boolean hasPermission(String node) — player.hasPermission(node).
• void sendMessage(Component message) — player.sendMessage(msg).
• boolean isOnline() — player.isOnline().
• Optional<Server> getCurrentServer() — Paper does not have proxy-style server objects; returns Optional.empty() for cross-platform compatibility.
• String getCurrentServerName() — Config.ServerInfo.NAME.
• void disconnect(Component reason) — player.kick(reason).
• ATPlayerData getData() — loads on first call.
• void saveData() — flushes to DB.

ATPConsole

Wraps Bukkit.getConsoleSender() to satisfy ATUserAdapter for paper. Identical surface; no chat-channel concept.

Debug/

• DebugStaffModeItem enum — the staff tool kit items.

6.3 Commands/ package

All commands extend a common pattern using LiteCommands annotations. Each command class is a @Command(name=..., aliases={...}) with @Permission(...) on the class or method. They are registered through ModuleManager.

6.3.1 Commands/Economy/

BalanceCommand

• /balance (bal, money)
• Permission: Permissions.Command.Economy.BALANCE
• Shows the player's per-server balance.
• Args: (@Context ATPPlayer self) then overload @Arg ATPPlayer target.

PayCommand

• /pay <target> <amount>
• Permission: Permissions.Command.Economy.PAY
• Validates: amount > 0, target has PaymentsToggled=true, sufficient funds.
• Rounding: 2 decimals via BigDecimal.setScale(2, RoundingMode.HALF_UP).
• On success: decrements self, increments target, persists both server-data rows, sends confirmation messages.

TogglePayCommand

• /togglepay
• Permission: Permissions.Command.Economy.TOGGLEPAY
• Flips PaymentsToggled in playerServerData.

EconomyCommand (eco)

• /economy add|remove|set|reset <target> [amount]
• Permission: Permissions.Command.Economy.ADMIN
• For subcommand dispatch, the class is split with @Execute per method.

BaltopCommand

• /baltop [page]
• Permission: Permissions.Command.Economy.BALTOP
• Cache: 60-second TTL map of page -> rendered text.
• Underlying data: PlayerServerDataDB.getTopBalances(serverUuid, 1000), paginated 10 per page.

6.3.2 Commands/Gamemode/

• GamemodeCommand — /gamemode <mode> [target], supports gp for parsing target.
• CreativeCommand, SurvivalCommand, AdventureCommand, SpectatorCommand — direct shortcuts.

6.3.3 Commands/Home/

• HomeCommand — /home [name], /homes. Admin: /home <player>:<name>.
• SetHomeCommand — /sethome <name> [target].
• DelHomeCommand — /delhome <name> sends clickable /delhomeconfirm <name>.
• DelHomeConfirmCommand — actually deletes.
• RenameHomeCommand — /renamehome <oldName> <newName>.

6.3.4 Commands/Speed/

• SpeedCommand — sets walking or flying speed 1-10 depending on current flying state.
• WalkingSpeedCommand (walkspeed) — walking speed 1-10.
• FlyingSpeedCommand (flyspeed) — flying speed 1-10.
• FlyCommand (togglefly) — toggles allowFlight.

6.3.5 Commands/Teleport/

• TeleportCommand (tp) — /tp <target> or /tp <target> <dest>.
• TeleportHereCommand (tphere).
• TeleportPosCommand (tppos) — /tppos <x> <y> <z> [yaw] [pitch] [world]. ~ and 0 shortcuts via XCoordinateArgument, YCoordinateArgument, ZCoordinateArgument, YawArgument, PitchArgument.
• BackCommand (return) — return to last teleport-from location.
• TeleportToggleCommand (tptoggle) — toggles TeleportToggle.
• TeleportAutoCommand (tpauto) — toggles TeleportAutoAccept.
• TeleportAskCommand (tpask, tpa) — sends a TO teleport request.
• TeleportAHereCommand (tpahere) — sends a HERE teleport request.
• TeleportAcceptCommand (tpaccept) — accepts.
• TeleportDenyCommand (tpdeny) — denies.
• TeleportACancelCommand (tpacancel) — cancels all or a specific request.

TeleportCommand builds clickable /tpaccept <id> / /tpdeny <id> chat components.

6.3.6 Commands/NotesGuiCommand

• /notesgui <target>
• Permission: Permissions.Command.Staff.NOTES
• Opens a 54-slot chest GUI of the target's notes; requires staff mode.
• Each note entry has a delete button (red wool) and click-to-edit paper slot.

6.3.7 Commands/AppelToolsPaperCommand (atp)

• /atp root command.
• Subcommands: debug staffmode give <DebugStaffModeItem>, updater list/get/update, reload.

6.3.8 Commands/Helpers/Arguments/

Custom argument resolvers for LiteCommands:

• XCoordinateArgument implements Argument<Float, Location> — accepts ~, 0, or a numeric value.
• YCoordinateArgument, ZCoordinateArgument — analogous.
• YawArgument, PitchArgument — degrees.

6.3.9 Commands/Helpers/Contexts/

• ATPPlayerContextProvider — provides ATPPlayer from a sender (or errors with no-permission).
• ATPUserContextProvider — provides ATUserAdapter.

6.3.10 Commands/Helpers/Handler/

• NoPermissionHandler — handles missing permission errors.
• CooldownHandler — per-player cooldown enforcement.

6.4 Config/ package

Config.java

All config keys for Paper. Static fields grouped:

Group	Example keys
ServerInfo	NAME, LOCALE, UUID
Database	HOST, PORT, NAME, USER, PASSWORD, SSL, MAX_POOL_SIZE, MIN_IDLE
Modules	DISCORD.ROOT, DISCORD.TOKEN, DISCORD.LOG_CHANNEL etc.
Discord	STAFF_CHANNEL_ID, WATCHLIST_CHANNEL_ID, PING_ROLE_IDS
ChatFilter	ENABLED, IP_REGEX, URL_REGEX, CURSE_WORDS[]
Plugins	updater config block
Other	REQUIRED_PLUGINS, WHITELIST, DEBUG
Economy	STARTING_BALANCE, MAX_NAME_LENGTH
Teleport	COOLDOWN_SECONDS, REQUEST_TIMEOUT_SECONDS

Messages.java

All MessageKey<String> and MessageKey<List<String>> keys with MiniMessage defaults. Categories: GENERAL, TELEPORT, HOME, ECONOMY, SPEED, GAMEMODE, STAFF, ADMIN.

Examples:

• Messages.Economy.BALANCE_SELF — default: "<green>Your balance: <gold>${balance}<gold>."
• Messages.Teleport.REQUEST_SENT — clickable accept/deny hover text.
• Messages.Home.DELHOME_CONFIRM — clickable confirm prefix.

Module.java

Per-module ConfigKey<Boolean> ENABLED etc. for each feature module.

6.5 Discord/ package

DiscordBot extends BaseDiscordBot

• void start(String token, List<SlashCommandData> slashCommands) — JDABuilder + addEventListeners.
• Hosts the /search slash command and all Bukkit listeners.
• Bukkit listeners are filtered out so only JDA listeners register.

Discord/Commands/

• SearchCommand — /search <query> — searches recent log messages and returns embed results.

6.6 Economy/ package

VaultEconomyProvider implements net.milkbowl.vault.economy.Economy

• String getName() → "AppelEconomy"
• Currency getCurrency() → $ with 2-decimal format #,###.00
• boolean hasBankSupport() → false
• double getBalance(OfflinePlayer) → ATPlayerServerData.balance
• EconomyResponse withdrawPlayer(...) → uses BigDecimal to avoid float drift.
• EconomyResponse depositPlayer(...) → similar.
• boolean createPlayerAccount(...) → no-op (rows auto-created on join).

6.7 Events/ package

Class	Listens for	Effect
PlayerJoinListener	PlayerJoinEvent	Loads ATPlayerData/ATPlayerServerData into playerManager; enforces setWhitelisted; broadcasts Discord join.
PlayerQuitListener	PlayerQuitEvent	savePlayer() + unloadPlayer(); broadcasts Discord leave.
StaffFreezeListener	PlayerMoveEvent, InventoryClickEvent, PlayerInteractEvent, BlockPlaceEvent, BlockBreakEvent, PlayerCommandPreprocessEvent	Cancels all actions for players with Frozen=true.
StaffModeListener	toggles	Toggles vanish via PremiumVanish, sets staff tool kit, saves inventory.
StaffToolListener	PlayerInteractEvent	Each tool kit slot triggers its action (FEATHER=vanish toggle, BLAZE_ROD=freeze toggle, CHEST=invsee, PAPER=notes, ENDER_EYE=cycle target).
PlayerChatListener	AsyncPlayerChatEvent	Routes through RegexFilter; posts result to Velocity plugin-message channel.

Events/Modifiers/

Custom event wrappers for cross-cutting concerns.

6.8 Utils/ package

Utils/Managers/

Class	Role
ATPPlayerManager extends PlayerManager<ATPPlayer>	Tracks online players; 5-minute auto-save.
CommandRegistrar	LiteCommands registration; uses relocated dev.rollczi.litecommands from shadowJar.
ModuleManager	Loads ModuleAdapters and calls onEnable / onDisable.
StaffInventoryManager	Saves/restores inventories when entering/exiting staff mode.
PluginUpdaterManager	updater list/get/update.
BaltopCache	60s cached baltop pages.

Utils/Scheduler/

• BukkitSchedulerAdapter implements SchedulerAdapter
• BukkitScheduledTaskAdapter implements ScheduledTaskAdapter

MessageFormatter

• static Component format(String miniMessage, Placeholder... placeholders) — resolves MiniMessage tags + placeholders.
• static Component format(MessageKey<String> key, Placeholder... placeholders).

PluginChecker

• void checkPlugins() — iterates Config.Other.REQUIRED_PLUGINS; if any missing, setWhitelisted(true) and posts Embeds.createMissingPluginsEmbed. Retries every 30 seconds until the Discord bot is connected.

6.9 Constants are managed by:

• Constants.java — auto-substituted (from common/.../Constants.java).
• The replaceTokens Gradle task.

6.10 Summary of Paper-only capabilities

• Gameplay: teleport, speed, fly, gamemode, homes.
• Economy: per-server balance, pay, baltop, Vault.
• Staff tools: staff mode, vanish (PremiumVanish), invsee, freeze, notes GUI.
• Plugin messaging listener: PluginMessageListener (in Events/) consumes appeltools:chat, appeltools:command, appeltools:staffmode, appeltools:staffchat, appeltools:maintenance, appeltools:freeze.
• Whitelist & plugin checker.

For Paper-only file index, see 17-file-index.md.

6.11 Permissions

See 09-permissions.md. All Paper permissions are declared in common/.../Types/Permissions.java.

6.12 Messages

See 14-configs.md for the full default YAML, and paper/.../Config/Messages.java for the source.