Friend

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

Permission	Default	Description
friends.use	true	Basic friend commands
friends.mail	true	Mail system access
friends.party	true	Party system access
friends.party.effects	true	Party effects access
friends.chat	true	Friend chat channel access
friends.teleport	true	Teleport to friends
friends.jump	true	Jump to a friend's server
friends.network	true	Cross-server features
friends.reload	op	Reload command
friends.admin	op	All admin commands

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

• [x] Friends.jar on every backend server
• [x] MySQL database shared across all servers
• [x] Unique server-name on each server
• [x] network.enabled: true on each server
• [x] 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