Victus Social Documentation

Start here

v0.1.0-SNAPSHOTProduction-oriented MVPBuilt for Velocity networks

One shared social experience across every server.

Victus Social is a Minecraft social plugin for Paper or Purpur networks with Velocity. Players get profiles, friends, private messages, online status and notifications that work network-wide. Friends and messages follow them from server to server.

Java 21Required runtime

1.21.8Paper / Purpur

3.4.0Velocity

2 JARsBackend + proxy

Before going live: this release is a production-oriented MVP. Test it on a staging copy of your network with your hosted database and Redis before opening it to players.

Features

♟

Player profiles

UUID-based profiles with display names and profile text. Profile viewing respects privacy.

❤

Friends everywhere

Add, accept, decline and remove friends from any server. If two players request each other at the same time, one friendship is created automatically.

✉

Cross-server DMs

Use /msg and /reply on any server. Messages to offline players are stored and delivered when they return.

●

Live presence

See online, away, do-not-disturb and invisible status, plus which server a friend is playing on.

🔔

Notifications

Friend requests and social updates appear in a durable in-game notification center.

✦

Ready-made menus

Polished social, profile, friends and notification inventories, no extra GUI plugin needed.

🛡

Blocks and privacy

Blocking removes the friendship, cancels pending requests and stops private messages between both players.

⚡

Network synchronization

Redis carries live events between servers; the database keeps everything durable.

PlaceholderAPI support

Friend counts, online friends, pending requests, unread notifications, status and current server.

Quick setup

Java 21Paper / Purpur 1.21.8Velocity 3.4.0Hosted MariaDB / MySQLHosted Redis 6.2+

Download both plugin files

Your release package contains one backend JAR and one Velocity proxy JAR. You need both for a network.

Install the backend JAR

Put VictusSocial-Backend-0.1.0-SNAPSHOT.jar in the plugins folder of every Paper or Purpur server.

Install the proxy JAR

Put VictusSocial-Proxy-0.1.0-SNAPSHOT.jar in your Velocity proxy's plugins folder.

Generate the config files

Start, then stop, the proxy and backend servers once. Victus Social creates its plugin folders and default configs automatically.

Enter your service details

Copy the MariaDB/MySQL and Redis credentials from your host into every Victus Social config. Use the same services everywhere.

Start one server, then the rest

Start one process and check its console for a successful connection. Then start the remaining backends and the proxy.

✓

No manual SQL setup

Victus Social creates and migrates its own tables automatically. Your database user only needs permission to create and update tables in the database supplied by your host.

Database & Redis

▰

MariaDB or MySQL

Stores profiles, friends, messages and notifications

✓MariaDB 10.6+ or MySQL 8.0+
✓Use the host, port, database, username and password from your provider
✓Same database on the proxy and every backend

⚡

Redis

Moves live social events between servers

✓Redis 6.2+ standalone service
✓Use the connection URI supplied by your provider
✓Use rediss:// when your provider requires TLS

plugins/VictusSocial/config.yml — important connection fields

server-id: lobby-1
instance-id: backend-lobby-1
proxy-managed-presence: true

database:
  type: MARIADB
  host: your-database-host
  port: 3306
  name: your-database-name
  username: your-username
  password: your-password

redis:
  enabled: true
  uri: rediss://username:password@your-redis-host:6380/0

Backend config: plugins/VictusSocial/config.yml · Velocity config: plugins/victussocial/config.yml

Identity rules: every process needs a unique, stable instance-id. Every backend needs a unique server-id and every proxy a unique proxy-id. All processes must share the same database, table prefix, Redis URI and stream key.

Commands

Players can use the menus for everyday actions or run commands directly. Each command lists its permission below.

Menus & profiles

/social

victussocial.use

Open the main social hub.

/friends

victussocial.friends.use

Open the paginated friends menu.

/notifications [markall]

victussocial.notifications.use

Open the notification center. Add markall to mark everything read.

/profile [player]

victussocial.profile.view

Open your profile, or another player's if it is visible to you.

Friends

/friend add <player>

victussocial.friends.use

Send a request. Accepts automatically if they already requested you.

/friend accept <player>

victussocial.friends.use

Accept a pending request.

/friend decline <player>

victussocial.friends.use

Decline a pending request.

/friend remove <player>

victussocial.friends.use

Remove an existing friendship.

/friend block <player>

victussocial.friends.use

Block a player: removes the friendship and cancels pending requests.

/friend unblock <player>

victussocial.friends.use

Remove a block.

/block <player>

victussocial.friends.use

Block a player.

/block remove <player>

victussocial.friends.use

Unblock a player.

Messaging

/msg <player> <message>

victussocial.messaging.use

Send a network-wide DM. Aliases: /tell, /w.

/reply <message>

victussocial.messaging.use

Reply to your most recent conversation. Alias: /r.

Presence

/status <online|away|dnd|invisible> [message]

victussocial.profile.edit

Set your presence and an optional profile status message.

Admin

/socialadmin status

victussocial.admin

Show backend, transport and instance health. No credentials or player data.

/socialreload

victussocial.admin.reload

Reload local messages and menu layouts only.

/socialproxy status

victussocial.proxy.admin

Check Victus Social from the Velocity proxy. Configure this permission in your Velocity permission provider.

Permissions

Grant these nodes through your permissions plugin. Normal player features are granted to everyone by default; admin, invisible and cooldown bypass default to operators.

victussocial.useEveryone

Open the main social menu.

victussocial.friends.useEveryone

Friend and block commands, and the friends menu.

victussocial.messaging.useEveryone

Send and reply to private messages.

victussocial.messaging.offlineEveryone

Required to message players who are offline.

victussocial.notifications.useEveryone

Open the notification center and mark all read.

victussocial.profile.viewEveryone

Open profiles.

victussocial.profile.editEveryone

Change presence and profile status.

victussocial.profile.invisibleOperators

Use the invisible presence mode.

victussocial.bypass.cooldownOperators

Bypass message and friend command cooldowns.

victussocial.adminOperators

Run /socialadmin status.

victussocial.admin.reloadOperators

Run /socialreload.

victussocial.proxy.adminOperators

Run /socialproxy status on Velocity.

Placeholders

Optional integration

PlaceholderAPI

Install PlaceholderAPI on your backend servers and Victus Social registers cached values automatically. Safe to use in scoreboards, tab lists and holograms. Values refresh every 10 seconds by default.

%victussocial_friend_count%Total friends%victussocial_online_friend_count%Friends who are online and visible%victussocial_pending_friend_requests%Unexpired incoming requests%victussocial_unread_notifications%Unread notifications%victussocial_status%Current social status%victussocial_server%Current server name

Placeholders can lag by up to the refresh interval (10 seconds). Group, party, achievement and level placeholders are not implemented yet.

Menus & messages

▦

Inventory menus

Change titles, sizes, icons, materials, slots and decorative items in menus.yml. Menu sizes must be 9 to 54 and divisible by nine.

Player messages

Edit the generated files inside messages/. The current release includes the en_US locale.

↻

Fast reloads

Run /socialreload after editing menus or messages. Database and Redis changes still need a restart.

Admin & troubleshooting

Plugin does not start

Check Java 21, then confirm the database host, port, name, username and password match your hosting panel. The database user must be allowed to create and update tables.

Friends or messages do not sync

Make sure Redis is enabled everywhere, the URI and stream key are identical on every process, and no two processes share an instance-id.

A menu will not load

Check material names, slot numbers and inventory size. Sizes must be between 9 and 54 and divisible by nine.

Presence looks out of date

Confirm the Velocity plugin is running and each proxy has a unique proxy-id. After a crash, stale presence expires after the configured timeout.

Launch checklist

✓Back up the database before plugin upgrades
✓Keep database and Redis behind your host's firewall
✓Test friend requests and DMs between two different servers
✓Check /socialadmin status and /socialproxy status report healthy

Privacy note

Private messages are stored as plaintext in the database. They are not end-to-end encrypted. Protect database credentials, restrict staff access and use TLS when your host provides it.

Developer API

Other plugins on the same server can access profiles, friends, messages, notifications and presence through the local Java API. This is an in-JVM API—there is no REST API or web dashboard.

Get the API

VictusSocialApi api = VictusSocialProvider.require();

api.profiles().findById(playerId).thenAccept(profile ->
    profile.ifPresent(value ->
        logger.info(value.displayName())
    )
);

Pre-1.0 API

Available services

ProfileService
FriendService
MessagingService
NotificationService
PresenceService
SocialEventBus

API calls return CompletionStage. Never block a Paper or Velocity event thread with .join(). The API is pre-1.0, so snapshot releases may introduce breaking changes.

What's included right now

Included in 0.1.0

✓Profiles and privacy-aware profile viewing
✓Online, away, DND and invisible presence
✓Friend requests, friendships and blocks
✓Durable cross-server DMs and offline delivery
✓Notifications and configurable inventory menus
✓Redis Streams synchronization and SQL migrations
✓Velocity presence authority and cached placeholders

Planned for later

–Groups, roles, parties and party finder
–General, custom, group or party chat
–Feeds, posts, reactions and discovery
–Reports, moderation and achievements
–Teleportation and Discord/web integrations
–BungeeCord, Waterfall, Redis Sentinel or Cluster
–Import/export and automated privacy workflows

A clear release boundary

This release focuses on the social basics and multi-server reliability. Future database tables do not mean planned systems are functional. SQLite is for single-process development only; managed MariaDB/MySQL and Redis are the recommended network setup. LuckPerms and Vault are soft dependencies only—dedicated integrations are not included yet.