Friends

Friends is a social plugin that lets players add friends, send messages, mail, gifts, and create parties on your server. Works across BungeeCord and Velocity networks, with full Folia support.

Features

• Friend System – Add friends, best friends, favorites, groups, notes, and nicknames.
• Friend Chat – /fc channel to broadcast to all online friends at once.
• Gift System – Send items to friends with anti-abuse protection (cooldowns, daily limits, blacklist).
• Private Messaging – Direct messages with reply functionality and sound notifications.
• Mail System – Send offline messages to players who aren't online. Can be disabled server-wide.
• Party System – Create parties, invite friends, and manage groups.
• Party Effects – Party members get potion effects with proximity-based activation.
• Party Waypoints – Action-bar arrow pointing at the nearest member or a specific locked target.
• Last-Seen Lookup – /friend seen <player> checks when any player was last online.
• Leaderboards – Rankings for most friends, gifts sent, and messages.
• Statistics – Track your social stats and see your rankings.
• GUIs – Clean inventory menus with custom model data support for resource packs.
• Cross-Server – Full BungeeCord and Velocity support in a single jar.
• Folia Support – Works on Folia's region-threaded scheduler out of the box.
• PlaceholderAPI – 25+ placeholders for scoreboards and more.
• WorldGuard – Friend groups can auto-share your WG region access.
• GriefPrevention – Party members auto-trusted in leader's claims.
• Database – MySQL and SQLite with auto-migration.
• Developer API – Full API for integration.

Commands

Friend

• /friend add <player> – Send a friend request.
• /friend remove <player> – Remove a friend.
• /friend accept <player> – Accept a request.
• /friend deny <player> – Deny a request.
• /friend list – View your friends.
• /friend requests – View pending requests.
• /friend best <player> – Toggle best friend status.
• /friend fav <player> – Toggle favorite status.
• /friend nick <player> <nickname> – Set a nickname for a friend.
• /friend note <player> <note> – Add a note about a friend.
• /friend group create/delete/set/list – Manage friend groups.
• /friend tp <player> – Teleport to a friend.
• /friend jump <player> – Jump to a friend's server.
• /friend info <player> – View friend details.
• /friend seen <player> – Last-seen lookup for any player.
• /friend block/unblock <player> – Block or unblock a player.
• /friend chat [message] – Toggle friend chat mode or send a one-shot message.
• /friend compass – Toggle the party compass.
• /friend waypoint <player|clear> – Lock the compass on a specific member.
• /friend emote <player> <type> – Send a particle emote.
• /friend status <message> – Set your status message.
• /friend menu – Open the friends menu.

Messaging & Mail

• /msg <player> <message> – Send a private message.
• /reply <message> – Reply to the last message.
• /mail read [page] – Read your mail.
• /mail send <player> <message> – Send mail.
• /mail delete <id/all> – Delete mail.
• /fc [message] – Friend chat channel.

Party

• /party create – Create a party.
• /party invite <player> – Invite a player.
• /party accept/deny <player> – Handle invitations.
• /party leave – Leave your party.
• /party kick <player> – Kick a player.
• /party info – View party info.
• /party disband – Disband your party.
• /party transfer <player> – Transfer leadership.
• /party effects – View active effects.
• /party shop – Purchase party effect upgrades (requires Vault).
• /party chat [message] – Toggle party chat mode or send a one-shot message.
• /pc [message] – Party chat shortcut.

Gifts

• /gift <player> – Send the held item to a friend.
• /gift pending – View pending gifts.
• /gift accept <id> – Accept a gift.
• /gift deny <id> – Deny a gift.

Menus & Admin

• /settings – Open notification settings menu.
• /stats – View your social statistics.
• /leaderboard – View friend leaderboards.
• /freload – Reload the plugin configuration.
• /fupdate – Check for plugin updates.

All primary commands also accept f-prefixed aliases (/fmsg, /freply, /fmail, /fparty, /fgift, /fstats, /fsettings, /fleaderboard) for servers with naming conflicts. On startup, the plugin warns if another plugin owns any primary name.

Permissions

PlaceholderAPI

• %friends_count% – Total friends
• %friends_online% – Online friends
• %friends_offline% – Offline friends
• %friends_best_friends% – Best friends count
• %friends_favorites% – Favorite friends count
• %friends_max% – Max friends limit
• %friends_requests% – Pending friend requests
• %friends_gifts_pending% – Pending gifts
• %friends_gifts_sent% – Total gifts sent
• %friends_gifts_received% – Total gifts received
• %friends_gifts_daily_remaining% – Gifts you can still send today
• %friends_gifts_cooldown% – Gift cooldown remaining (seconds)
• %friends_messages_sent% – Messages sent
• %friends_mail_total% – Total mail
• %friends_mail_unread% – Unread mail
• %friends_messaging_enabled% – Private messages toggle
• %friends_status% – Your status message
• %friends_in_party% – In party (true/false)
• %friends_party_size% – Party size
• %friends_party_name% – Party name
• %friends_party_leader% – Party leader name
• %friends_is_party_leader% – Are you party leader (true/false)
• %friends_rank_friends% – Leaderboard rank (friends)
• %friends_rank_gifts% – Leaderboard rank (gifts)
• %friends_rank_messages% – Leaderboard rank (messages)

Multi-Server Setup (BungeeCord / Velocity)

Only one jar is shipped: Friends.jar. It goes on every backend Spigot/Paper/Folia server. Nothing on the proxy.

1. Install the plugin

Drop Friends.jar into /plugins/ on every backend server in your network.

2. Set up MySQL

All servers share the same database. Open database.yml on each server and set:

database:
  type: mysql
  host: your-database-ip
  port: 3306
  name: friends
  username: your-user
  password: your-password
  pool:
    max-connections: 10
    timeout: 30000
    keep-alive: true

Make sure the friends database exists. Tables are created on first boot.

3. Configure each server

In config.yml set a unique name and enable networking:

server-name: "lobby"

network:
  enabled: true
  channel: "friends:network"

Use a unique server-name per backend (e.g. survival, skyblock, lobby).

4. Enable proxy mode on each backend

BungeeCord (spigot.yml):

settings:
  bungeecord: true

Velocity (paper-global.yml):

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "your-velocity-secret"

5. Restart every backend. Friend requests, messages, mail, and party invites sync across the network.

Quick Checklist

• Friends.jar on every backend server
• MySQL database shared across all servers
• Unique server-name on each server
• network.enabled: true on each server
• BungeeCord mode or Velocity forwarding enabled

Troubleshooting

• Friends not syncing? Check every server points to the same MySQL database.
• Cross-server messages not working? bungeecord: true (BungeeCord) or Velocity forwarding must be enabled.
• Players show wrong server? Each server needs a unique server-name in config.yml.
• Another plugin owns /msg, /party etc.? Use the f-prefixed aliases (/fmsg, /fparty) or /friends:<cmd>.

Config

server-name: "lobby"

settings:
  max-friends: 0
  best-friends:
    max-limit: 5
    enabled: true
  friend-groups:
    enabled: true
    max-groups: 10
  friend-teleport:
    enabled: true
    cooldown: 30
  friend-jump:
    enabled: true
    cooldown: 10
  private-messages:
    friends-only: false
    log-to-console: false
    sounds: true
    cross-server: true
    allow-toggle: true

party:
  max-size: 8
  allow-public-parties: true
  effects:
    enabled: true
    proximity-required: true
    proximity-range: 50
    scaling-strength: true
    scale-percentage: 10
    update-interval: 100
    compass:
      enabled: true
      update-interval: 20
    shop:
      enabled: true
      leader-only: true
      reset-on-disband: true

integrations:
  grief-prevention:
    enabled: true
    shared-building: true
    shared-containers: true
    shared-interactions: true
    shared-entities: true
  luck-perms:
    enabled: true
  worldguard:
    enabled: false
    shared-groups:
      - trusted
      - build

network:
  enabled: true
  channel: "friends:network"

mail:
  enabled: true
  auto-cleanup:
    enabled: true
    days-old: 30

gifts:
  enabled: true
  cooldown: 60
  max-daily: 10
  max-stack-size: 64
  expiry-days: 7
  blacklist:
    - BEDROCK
    - BARRIER
    - COMMAND_BLOCK

emotes:
  enabled: true
  cooldown: 5
  range: 10

debug: false

API Usage

Friend Management

FriendsAPI.getFriends(playerUUID);                 // Get a player's friends list
FriendsAPI.getOnlineFriends(playerUUID);           // Get only online friends
FriendsAPI.areFriends(playerUUID, otherUUID);      // Check friendship status
FriendsAPI.addFriend(playerUUID, friendUUID);      // Add a friend directly
FriendsAPI.removeFriend(playerUUID, friendUUID);   // Remove a friend

Friend Requests

FriendsAPI.sendFriendRequest(senderUUID, receiverUUID);
FriendsAPI.getPendingRequests(playerUUID);
FriendsAPI.acceptFriendRequest(receiverUUID, senderUUID);
FriendsAPI.denyFriendRequest(receiverUUID, senderUUID);

Messaging & Mail

FriendsAPI.sendMessage(senderUUID, receiverUUID, message);
FriendsAPI.getPlayerMail(playerUUID);
FriendsAPI.sendMail(senderUUID, receiverUUID, content);

Party System

FriendsAPI.createParty(leaderUUID);
FriendsAPI.disbandParty(partyId);
FriendsAPI.invitePlayerToParty(partyId, playerId);
FriendsAPI.getPlayerParty(playerId);
FriendsAPI.getPartyEffects(partyId);
FriendsAPI.sendPartyMessage(player, message);
FriendsAPI.isPartyChatEnabled(playerUUID);

Settings & Stats

FriendsAPI.getPlayerSettings(playerUUID);
FriendsAPI.getPlayerStats(playerUUID);
FriendsAPI.getLeaderboard(type, limit);

Optional Dependencies

• PlaceholderAPI – For placeholders
• LuckPerms – For permission integration
• GriefPrevention – For claim trust integration
• WorldGuard – For region sharing by friend group
• Vault – For the party effects shop
• ProtocolLib – For enhanced features