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.
• Friend Streaks – Daily streaks between friends. Both sides send daily to keep it going. Auto-warns before expiry, auto-resets when broken, caps at 1000 with configurable milestone rewards.
• Trust Levels – 6 tiers (Acquaintance → Bestie). Points earned from messages, gifts, and streaks. Configurable perks per tier.
• Gift Wishlists – Players publish a wishlist so friends know what to gift. Persisted per player.
• Rock Paper Scissors – Bet Vault money on RPS between friends. Configurable bet limits and optional house cut.
• Per-Rank Friend Limits – Different max-friends per LuckPerms group, including an unlimited tier.

Commands:

• /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.
• /friend streak <player> – Send a daily friend streak.
• /friend streak list – View all your active streaks.
• /friend trust <player> – View your trust tier with a friend.
• /friend trust tiers – List every tier and its perks.
• /friend wishlist – View your gift wishlist.
• /friend wishlist <player> – See a friend's wishlist before gifting.
• /friend wishlist add <material> [amount] [note] – Add an item.
• /friend wishlist addhand [amount] [note] – Add the item you're holding.
• /friend wishlist remove <material> – Remove an item.
• /friend wishlist clear – Clear your wishlist.
• /friend rps <player> <bet> – Challenge a friend to Rock Paper Scissors for Vault money.
• /friend rps accept | deny – Respond to a pending challenge.
• /friend rps rock | paper | scissors – Pick your move.

• /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 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.

• /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.

• /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:

• friends.use – Basic friend commands (default: true).
• friends.mail – Mail system access (default: true).
• friends.party – Party system access (default: true).
• friends.party.effects – Party effects access (default: true).
• friends.chat – Friend chat channel access (default: true).
• friends.teleport – Teleport to friends (default: true).
• friends.jump – Jump to a friend's server (default: true).
• friends.network – Cross-server features (default: true).
• friends.reload – Reload command (default: op).
• friends.admin – All admin commands (default: op).
• friends.limit.<number> – Sets the friend cap to any number. friends.limit.15, friends.limit.250, friends.limit.9999 all work. Highest granted match wins (default: false).
• friends.limit.unlimited – Removes the friend cap entirely. Overrides any number (default: false).

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)
• %friends_chat_enabled% - Friend chat receive toggle (true/false)
• %friends_in_friendchat% - Friend chat mode active (true/false)
• %friends_streak_count% - Number of active streaks
• %friends_longest_streak% - Your longest streak ever
• %friends_favorites% - Shows your favorite friends
• %friends_slots% - Displays how many slots remaining
• %friends_online_names% - Shows who's online by name
• %friends_top_level% - Top level
• %friends_level_with_<player>% - Shows top level with a friend
• %friends_current_streak% - Shows current streak
• %friends_party_online% - Shows your party online
• %friends_wishlist_count% - Shows how many items on wishlist
• %friends_gifts_total% - Shows total gifts

Proxy Setup (BungeeCord / Velocity)

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

server-name: "lobby"

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

settings:
  bungeecord: true

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

# Friends Plugin Configuration

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
    bonuses:
      regeneration: 0
      damage_resistance: 0
      speed: 0
      luck: 0
      haste: 0
    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) // Send a request

FriendsAPI.getPendingRequests(playerUUID) // Get pending requests

FriendsAPI.acceptFriendRequest(receiverUUID, senderUUID) // Accept a request

FriendsAPI.denyFriendRequest(receiverUUID, senderUUID) // Deny a request

Messaging & Mail:

FriendsAPI.sendMessage(senderUUID, receiverUUID, message) // Send a direct message

FriendsAPI.getPlayerMail(playerUUID) // Get player's mail

FriendsAPI.sendMail(senderUUID, receiverUUID, content) // Send mail

Party System:

FriendsAPI.createParty(leaderUUID) // Create a new party

FriendsAPI.disbandParty(partyId) // Disband an existing party

FriendsAPI.invitePlayerToParty(partyId, playerId) // Invite a player

FriendsAPI.getPlayerParty(playerId) // Get a player's current party

FriendsAPI.getPartyEffects(partyId) // Get active effects for a party

FriendsAPI.sendPartyMessage(player, message) // Send party chat message

FriendsAPI.isPartyChatEnabled(playerUUID) // Check party chat toggle

Settings & Stats: