7. Velocity Module Reference

velocity/ produces AppelTools-Velocity.jar, a @Plugin(id="appeltoolsvelocity", ...) Velocity 4.2 plugin. It hosts cross-server moderation, friend system, party system, private messaging, chat filter, staff chat, reports, maintenance mode, server restart scheduler, server registration, and Discord logging.

7.1 Bootstrap and Lifecycle

velocity-plugin.json (@Plugin)

{
  "id": "appeltoolsvelocity",
  "name": "AppelTools",
  "version": "${version}",
  "description": "${description}",
  "author": "${author}",
  "dependencies": [
    { "id": "luckperms" }
  ]
}

AppelToolsVelocityBootstrap

• @Plugin(id="appeltoolsvelocity", ...) Velocity plugin class.
• @Inject constructor receives Logger, ProxyServer, PluginManager, @DataDirectory Path data.

AppelToolsVelocity

Lifecycle (see §3.7):

1. Inject Logger, ProxyServer, PluginManager, @DataDirectory Path data.
2. Construct managers/services.
3. Register Velocity event listeners (forwarded by bootstrap).
4. Connect to MySQL via Database.
5. Build LiteCommands via CommandRegistrar.
6. Load modules via ModuleManager.
7. Optionally start DiscordBot, PunishmentManager auto-save, AnnouncementManager.

onProxyShutdown() reverses: stops schedulers, unregisters commands, disconnects DB, unloads Discord.

7.2 Types/ package

ATVPlayer extends ATUserAdapter

A per-player wrapper around com.velocitypowered.api.proxy.Player:

Field	Type	Source
player	Player	constructor
name	String	player.getUsername()
uuid	UUID	player.getUniqueId()
data	ATPlayerData	cache
serverName	String	player.getCurrentServer().get().getServerInfo().getName()
currentChannel	ChatChannel	GLOBAL/PARTY/MESSAGE/STAFF

Implements:

• boolean hasPermission(String node) — player.hasPermission(node).
• void sendMessage(Component message) — player.sendMessage(msg).
• boolean isOnline() — player.isActive().
• Optional<Server> getCurrentServer() — player.getCurrentServer().
• String getCurrentServerName() — current server name (or null).
• void disconnect(Component reason) — player.disconnect(reason).

ATVConsole

Wraps Velocity's Logger to satisfy ATUserAdapter. Has no chat-channel concept.

7.3 Config/ package

Config.java

Static config keys for Velocity:

Group	Example keys
ServerInfo	NAME, LOCALE
Database	same as Paper
Modules	DISCORD.*, MAINTENANCE.*, ANNOUNCEMENT.*
Discord	TOKEN, STAFF_CHANNEL_ID, WATCHLIST_CHANNEL_ID, PING_ROLE_IDS, REPORT_CHANNEL_ID
ChatFilter	ENABLED, IP_REGEX, URL_REGEX, CURSE_WORDS[]
Punishment	MAX_TEMP_BAN, MAX_TEMP_MUTE, BROADCAST_KICK, BROADCAST_MUTE, BROADCAST_BAN
Friends	MAX_FRIENDS, REQUEST_TIMEOUT_MS, COOLDOWN_MS
Parties	MAX_MEMBERS, MAX_PARTIES, INVITE_TIMEOUT_MS
Maintenance	KICK_MESSAGE, MOTD, ENABLE_ON_START
Restart	WARNING_INTERVALS[], BROADCASTS[]
Servers	MAX_SERVERS
Other	REQUIRED_PLUGINS, WHITELIST, DEBUG, ANNOUNCEMENT_INTERVAL

Messages.java

All MessageKey<String> with MiniMessage defaults. Categories: GENERAL, PUNISHMENT, MAINTENANCE, FRIENDS, PARTY, MESSAGE, REPORT, STAFF, ADMIN, CHAT, RESTART.

Module.java

Per-module ConfigKey<Boolean> ENABLED.

Modules.java

Lombok @Data with Modules inner classes (Modules.Discord, Modules.Maintenance, Modules.Announcement).

7.4 Commands/ package

All commands use LiteCommands annotations. Registered by CommandRegistrar.

7.4.1 Commands/Punishment/

Class	Permission	Aliases	Notes
BanCommand	Permissions.Command.Punishment.BAN		Inserts PermPunishment; kick from all servers.
TempBanCommand	Permissions.Command.Punishment.TEMP_BAN		Duration parsing.
UnbanCommand	Permissions.Command.Punishment.UNBAN		Deactivates + inserts UndonePunishment.
IPBanCommand	Permissions.Command.Punishment.IP_BAN		IP-targeted; kicks all with that IP.
TempIPBanCommand	Permissions.Command.Punishment.TEMP_IP_BAN
IPUnbanCommand	Permissions.Command.Punishment.IP_UNBAN
KickCommand	Permissions.Command.Punishment.KICK		Inserts Punishment with Type=KICK.
IPKickCommand	Permissions.Command.Punishment.IP_KICK
MuteCommand	Permissions.Command.Punishment.MUTE		Inserts PermPunishment with Type=MUTE; broadcasts.
TempMuteCommand	Permissions.Command.Punishment.TEMP_MUTE
UnmuteCommand	Permissions.Command.Punishment.UNMUTE
IPMuteCommand	Permissions.Command.Punishment.IP_MUTE
TempIPMuteCommand	Permissions.Command.Punishment.TEMP_IP_MUTE
IPUnmuteCommand	Permissions.Command.Punishment.IP_UNMUTE
HistoryCommand	Permissions.Command.Punishment.HISTORY		Lists perm+temp+undone by UUID or name.

Each punishment command:

1. Resolves target to UUID via UUIDFetcher (cache-first).
2. Calls punishment.checkActive(...) to avoid stacking active punishments.
3. Inserts the punishment row.
4. Kicks/notifies target(s).
5. Posts Embeds.createPunishmentEmbed to Discord.

7.4.2 Commands/Friends/

FriendsCommand

Subcommands: add, accept, deny, remove, list, requests, pending, notifications, toggle.

• list paginates 10/page.
• All actions go through FriendRequestDB / PlayerDataDB for Friends field.

7.4.3 Commands/Party/

PartyCommand

Subcommands: invite, leave, list, promote, demote, transfer, remove (kick), warp, accept, disband, chat, mute, allinvite, plus admin variants (admin join, admin list, admin disband).

PartyChatCommand (pchat, pc)

Party chat broadcast.

The Party data class is in-memory only; coordination is via plugin messages when each party participates.

7.4.4 Commands/Message/

MessageCommand

Many aliases (msg, m, tell, whisper, w, pm, message, dm).

• Stores lastMessaged in target's playerData.
• Respects ignore list (IgnoredPlayers).
• Applies RegexFilter for curse words; if curse, notifies staff with notifyStaffNotif.
• Spy broadcasts to staff with StaffSpyToggled=true.

ReplyCommand

Replies to last messaged player or console.

IgnoreCommand / UnignoreCommand

Manage IgnoredPlayers list.

MessageToggleCommand

Toggles MessagesToggled.

7.4.5 Commands/Report/

ReportCommand

• /report <player> <reason>
• Rejects self-report; enforces cooldown.
• Appends to playerData.Reports.
• Broadcasts to staff with StaffToggled.
• Posts Embeds.createReportEmbed to Discord report channel.
• Calls StaffNotificationService.sendReport(report).

ReportsCommand

• list and remove <index>.

7.4.6 Commands/Staff/

StaffChatCommand (sc)

• @Join <message> joins and broadcasts to all staff with StaffChatToggled=true.

StaffChatToggleCommand (sctoggle)

• Toggles StaffChatToggled.

StaffModeToggleCommand (smtoggle, staffmode, sm, h)

• Toggles StaffModeToggled per-player and globally; broadcasts via plugin message.

StaffNotificationsToggleCommand (sntoggle, staffnotifications)

• Toggles StaffToggled.

StaffSpyToggleCommand (sstoggle, staffspy)

• Toggles StaffSpyToggled.

StaffListCommand (slist)

• Online staff grouped by server.

VersionListCommand (vlist)

• Online players grouped by Minecraft protocol version.

BroadcastCommand (a, alert, bc)

• Global alert.

StaffNotesCommand

• add|remove|list notes.
• Sends Embeds.createWatchlistNoteEmbed to watchlist channel.

7.4.7 Commands/Other/

MaintenanceCommand (mt)

• Toggles maintenance mode; broadcasts to all servers via plugin message.
• Posts Embeds.createMaintenanceEmbed.
• Kicks non-bypass players from each paper server.

RestartServerCommand (rs)

• restartserver <duration|cancel>.
• Parses duration (1d, 2h, 30m, etc.).
• Broadcasts at 60/30/10/1 minutes and 5/4/3/2/1 seconds.
• Posts Embeds.createRestartEmbed.
• Calls proxy.shutdown() at expiry.

ServersCommand

• register <name> <ip> <port>, unregister <name>, list.
• All reads/writes go through ServerDataDB.

AppelToolsVelocityCommand (atv)

• updater list/get/update, reload.

7.4.8 Commands/Helpers/Arguments/

• ServerNameArgument — uses ProxyServer.getAllServers() to resolve.
• ServerIpArgument — parses dotted-quad.
• ServerPortArgument — parses int.

7.4.6 Commands/Helpers/Contexts/

• ATVPlayerContextProvider — provides ATVPlayer from a sender.

7.4.7 Commands/Helpers/Handler/

• NoPermissionHandler, CooldownHandler.

7.5 Events/ package

Class	Listens for	Effect
PlayerJoinListener	PlayerChooseInitialServerEvent then ServerPostConnectEvent	Loads peer DB; creates initial ATPlayerData; posts Discord join.
PlayerQuitListener	PlayerDisconnectEvent	savePlayer() + unloadPlayer(); posts Discord leave.
PlayerServerSwitchListener	ServerPostConnectEvent	Tracks server name; relays to followers via plugin message.
PluginMessageListener	PluginMessageEvent on "appeltools:*" channels	Central dispatcher for all incoming cross-server channels.
StaffChatListener	PlayerChatEvent	Routes StaffChatToggled messages; broadcasts to staff.
ChatListener	PlayerChatEvent	Routes through SignedQueue for moderation; applies RegexFilter.
ProxyPingListener	ProxyPingEvent	When maintenance is on, overrides MOTD, server-icon, version-name, player-list-hover.
PreLoginListener	PreLoginEvent	Refuses connection if maintenance and no bypass permission.
LoginListener	LoginEvent	When kicked for maintenance, posts embed and check timer.

Events/Modifiers/

Custom wrappers for cross-cutting concerns.

7.6 Discord/ package

DiscordBot extends BaseDiscordBot

• void start(String token, List<SlashCommandData> slashCommands) — JDABuilder + addEventListeners.
• Hosts the /search slash command.
• StaffNotificationService provides outbound embed helpers.

Discord/Commands/

• SearchCommand — /search <query> — searches recent log messages.

Discord/Commands/Helpers/Arguments/

• Argument resolvers for Discord slash-command options.

7.7 Punishments/ package (Velocity-side)

• PunishmentManager — applies/unapplies punishments; runs 5-minute checkAllTempPunishments.
• Each ban/kick/mute method kicks/notsies/etc.; sends Discord embed.

7.8 Utils/ package

Utils/Managers/

Class	Role
ATVPlayerManager extends PlayerManager<ATVPlayer>	Tracks online players on the proxy.
CommandRegistrar	LiteCommands registration; uses relocated dev.rollczi.litecommands.
ModuleManager	Loads modules.
PluginUpdaterManager	updater list/get/update.
FriendManager	Friend system state.
AnnouncementManager	Repeating broadcast of configured announcements.
RestartManager	Tracks scheduled restart state.

Utils/Scheduler/

• VelocitySchedulerAdapter implements SchedulerAdapter
• VelocityScheduledTaskAdapter implements ScheduledTaskAdapter

MessageFormatter

• static Component format(String miniMessage, Placeholder... placeholders) — MiniMessage resolution.

7.9 Summary of Velocity-only capabilities

• Cross-server moderation: ban, mute, kick (perm + temp + IP-targeted), undo.
• Cross-server chat: private messages, party chat, staff chat, friend status broadcasts.
• Friends: cross-server friend list, requests, toggles.
• Parties: cross-server parties with invite/promote/transfer/allinvite.
• Reports: with Discord embed and staff notification.
• Maintenance mode: proxy-wide + per-Paper fan-out.
• Restart scheduler: countdown broadcasts.
• Server registration: /servers register/unregister/list.
• Discord logging: reports, staff notes, freezes, missing plugins, punishments, joins/leaves, restarts, maintenance, log search.

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

7.10 Permissions

See 09-permissions.md.

7.11 Messages

See 14-configs.md.