Velocity Friends

This is a friends system for Velocity proxy servers that allows players to manage friendships, send messages, and interact across multiple servers.

What's New in Version 1.4.1:

• Personal server switch notification toggle - Players can now enable/disable server switch notifications individually
• Server alias system - Replace technical server names with custom display names in the config
• Admin message spy feature - Monitor private messages with permission-protected /friend watch <player> command
• Enhanced MySQL support - Full support for special characters in database passwords (" \ # ; : / ? & | $)
• Hex color support in all messages - Use <#RRGGBB> (MiniMessage style) or &#RRGGBB (BungeeCord style) anywhere in config.yml
• MySQL auto-reconnect - Plugin automatically reconnects to the database if it goes offline and comes back (30-second cooldown between attempts, no data loss)
• Fixed stale MySQL connections - Added HikariCP keepalive, max lifetime, and connection validation to prevent silent failures after the database is idle
• Fixed activity status (Active/AFK/DND) not being saved to MySQL - Was previously only stored in memory and reset on every restart
• Server join action configurable: direct connection or custom command
• Fixed config migration for new settings in server_aliases from existing configs

Commands:

• /friend add <player> - Send a friend request
• /friend accept <player> - Accept a friend request (works with offline players)
• /friend deny <player> - Deny a friend request
• /friend remove <player> - Remove a friend
• /friend list - View all friends with online status and server location (click to join!)
• /friend requests - Show pending friend requests
• /friend msg <player> <message> - Send a private message
• /friend reply <message> - Reply to the last message
• /friend broadcast <message> - Message all online friends
• /friend status [active|afk|dnd] - Set your activity status
• /friend settings - Open the interactive settings menu
• /friend version - Check plugin version and updates
• /friend reload - Reload configuration (admin only)

Permissions:

• friends.use - Basic permission to use the friends system
• friends.reload - Permission to reload the plugin configuration

Settings Menu: Players can customize their experience with toggleable options:

• Friend Requests - Enable/disable receiving friend requests
• Notifications - Toggle friend online/offline notifications
• Messages - Enable/disable friend messages
• Status Message - Set a custom status visible to friends

Plugin Messaging API: The plugin provides a complete API for Spigot/Paper servers to interact with the friends system:

Available Requests:

• GET_FRIENDS - Retrieve all friends with names and online status
• GET_ONLINE_FRIENDS - Get only online friends
• GET_SETTINGS - Fetch a player's settings and status message
• UPDATE_SETTING - Change player settings from backend servers
• GET_PENDING_REQUESTS - List all pending friend requests
• ARE_FRIENDS - Check if two players are friends

Automatic Events:

• FRIEND_ONLINE - Triggered when a friend comes online
• FRIEND_OFFLINE - Triggered when a friend goes offline
• FRIEND_SERVER_SWITCH - Notified when a friend switches servers (NEW in 1.2.0)
• FRIEND_REQUEST - Sent when receiving a new friend request
• SETTING_CHANGED - Notified when settings are updated

Storage Options: Choose between JSON files or MySQL database:

JSON Mode (Default):

• Simple file-based storage
• No external dependencies
• Perfect for smaller networks

MySQL Mode:

• Scalable database storage
• HikariCP connection pooling
• Ideal for larger networks
• Tables: friendships, pending_requests, player_settings, player_names

Features:

• Cross-server friend system for Velocity networks
• Live version checker - Stay updated with automatic version notifications
• Activity status system - Active, AFK, and DND modes with visual indicators
• Server display - See which server each friend is on
• Click-to-join - Instantly join your friends by clicking their server
• Offline support - Accept friend requests from offline players
• Server switch tracking with clickable notifications
• Private messaging between friends
• Broadcast messages to all online friends
• Customizable settings per player
• Offline player name display
• Console logging for moderation
• MySQL support with connection pooling
• JSON fallback for simplicity
• Plugin Messaging API for custom integrations
• Automatic username caching
• Interactive settings menu
• Configurable notifications (join/leave/server switch)
• Flexible message customization with auto-disable for empty entries

PlaceholderAPI Support (New!):

Use the included companion plugin to display friend data in scoreboards, holograms, chat, and more:

Available Placeholders:

• %friends_online% # Number of online friends
• %friends_total% # Total number of friends
• %friends_offline% # Number of offline friends
• %friends_online_list% # Comma-separated online friends
• %friends_online_servers% # Unique servers count

To find the companion plugin for Spigot/Paper servers, simply click on a version of the plugin (click on ‘Version’ and then, for example, ‘1.4.1-SNAPSHOT-3’), and under ‘Files’ you’ll find both the plugin and the companion plugin available for download.

Supported Velocity Version: Velocity 3.3.0 and higher (Java 17+)

Important when setting up:

1. Choose your storage type in config.yml (json or mysql)
2. If using MySQL, configure database credentials
3. Restart the proxy server
4. Optionally integrate with Spigot/Paper plugins using the Plugin Messaging API

Just send me a message on Discord if you have any questions, suggestions, or requests for new plugins.