RefineryFriends

RefineryFriends is a persistent, GUI-driven friends system for Paper servers. It uses RefineryCore for commands, messages, configuration, and database services.

Features

• Persistent friend relationships and pending requests
• GUI friend list with pagination, online sorting, and best-friend pins
• Accept, decline, remove, and inspect friend requests
• Per-player private friend nicknames
• Best-friend marking with configurable limits
• Join and leave notifications with per-player settings
• Configurable request cooldowns and request expiry
• Localized messages and player-selectable menu languages
• Optional network-wide presence for Velocity or BungeeCord networks
• Public asynchronous API and friend events for other plugins

Requirements

• Paper 1.21.11 or a compatible server implementation
• Java 21 or newer
• RefineryCore 0.1.3 or newer

RefineryCore must be installed in the server's plugins directory before RefineryFriends.

Installation

1. Download the refineryfriends plugin JAR.
2. Install the required RefineryCore version.
3. Place both JARs in the server's plugins directory.
4. Start the server once to generate the configuration files.
5. Review plugins/RefineryFriends/config.yml and gui.yml.

The plugin stores friend data and player preferences in its SQLite database, friends.db.

Commands

The main command is /friends; /friend is an alias.

Command	Description
/friends	Open the friends menu
/friends add <player>	Send a friend request
/friends accept <player>	Accept a friend request
/friends decline <player>	Decline a friend request
/friends remove <player>	Remove a friend
/friends requests	List incoming friend requests
/friends list	List friends and their current server
/friends settings	Open personal notification and display settings
/friends bestfriend <player>	Toggle a best-friend pin
/friends nickname <player> [nickname]	Set or clear a private nickname
/friends language <locale>	Choose the friends menu language

All commands are player-only. A blank nickname clears the existing nickname.

Permissions

Permission	Default	Description
refineryfriends.limit.bypass	Operator	Bypasses friend, pending-request, and best-friend limits
refineryfriends.limit.<n>	False	Raises an individual player's friend limit to n
refineryfriends.bestlimit.<n>	False	Raises an individual player's best-friend limit to n

Dynamic limit permissions support any positive integer. When several matching permissions are granted, the highest tier is used.

Configuration

General behavior is configured in config.yml, including:

• Default locale and whether players may override it
• Maximum friends and pending requests
• Request cooldown and automatic request expiry
• Join, leave, and incoming-request notifications
• Notification sound
• Best-friend limit and sorting behavior
• Nickname formatting and maximum nickname length
• Proxy-network presence and the local server name

The appearance of the friends menus is configured separately in gui.yml. It controls titles, row counts, online sorting, filler items, and best-friend slot highlighting. Both files are migrated automatically when their schema changes.

Locales

The bundled locale identifiers are:

en_us, ar_sa, es_es, fr_fr, de_de, pt_br, ru_ru, zh_cn, ja_jp, ko_kr, tr_tr, and it_it.

Locale files are located in plugins/RefineryFriends/lang/. Set DefaultLocale in config.yml, or allow players to use /friends language <locale>.

Network presence

Set NetworkEnabled: true when the server is part of a Velocity or BungeeCord network running RefineryFriends on multiple backend servers. Set a distinct ServerName for each backend and ensure the proxy supports the plugin messaging channel used for network presence.

API

Other plugins can obtain the registered service with RefineryFriendsAPI:

RefineryFriendsAPI api = RefineryFriendsAPI.get();
if (api != null) {
    api.areFriends(firstUuid, secondUuid).thenAccept(areFriends -> {
        // Handle the result asynchronously.
    });
}

API lookups return CompletableFuture values and complete off the main server thread. Switch back to the Bukkit main thread before accessing Bukkit APIs in a callback. Friend relationship changes also publish events through RefineryCore's event bus.