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

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

```yaml 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:

```yaml 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`):

```yaml settings: bungeecord: true ```

Velocity (`paper-global.yml`):

```yaml 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

- Another plugin owns /msg, /party etc.? Check every server points to the same MySQL database. - Another plugin owns /msg, /party etc.? `bungeecord: true` (BungeeCord) or Velocity forwarding must be enabled. - Another plugin owns /msg, /party etc.? 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

```yaml 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

```java 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

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

Messaging & Mail

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

Party System

```java 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

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

Optional Dependencies

- ProtocolLib – For placeholders - ProtocolLib – For permission integration - ProtocolLib – For claim trust integration - ProtocolLib – For region sharing by friend group - ProtocolLib – For the party effects shop - ProtocolLib – For enhanced features