Capabilities

Key Features

A complete toolkit to run a multi-server Minecraft network without the overhead of a proxy layer.

Reference

Commands

Every subcommand below also works directly under /auricnetwork (e.g. /auricnetwork server survival, /auricnetwork party invite Steve). The standalone commands like /server, /spawn, /lobby and /party keep working exactly the same.

Access control

Permissions

Every command node lives under auricnetwork.command.*. Parent nodes grant every subcommand beneath them, but each subcommand also has its own individual node, so you can remove access to a single feature without touching the rest.

General

Server Transfers

Spawns

Party

Admin Tools

Welcome System

Queue Priority

Setup

Configuration Guide

The config.yml file controls every aspect of AuricNetwork. Below is a detailed explanation of each section.

One key sits outside all of the sections below: check-updates (true by default), near the top of the file. It controls whether the plugin checks Modrinth for a newer version on startup and lets admins know in-game — set it to false to turn that off entirely.

servers:
  lobby: "127.0.0.1:25565"
  survival: "127.0.0.1:25566"

maintenance:
  enabled: false
  servers:
    - "survival"

transfer_immersion:
  delay: 3.0
  sound:
    enabled: true
    sound_id: "block.amethyst_block.hit"
    fade_out: true

language: "en"

join_spawn:
  enabled: false
  world: "world"
  x: 0.5
  y: 64.0
  z: 0.5
  yaw: 0.0
  pitch: 0.0

respawn_spawn:
  enabled: false
  world: "world"
  x: 0.5
  y: 64.0
  z: 0.5
  yaw: 0.0
  pitch: 0.0

lobby:
  enabled: false
  balancing_mode: "RANDOM"
  servers:
    - "lobby1"
    - "lobby2"

server_status_api:
  enabled: false
  update_interval_seconds: 60

loot_transfer:
  enabled: false
  include_enderchest: true
  sync_experience: false
  sync_health_hunger: false
  sync_potion_effects: false
  sync_gamemode: false
  sync_economy: false
  recovery_history_size: 3
  max_payload_age_seconds: 300
  network_secret: ""

stat_sync:
  enabled: false
  statistics:
    play_one_minute: false
    jump: false
    deaths: false
    mob_kills: false

webhooks:
  enabled: false
  batch_interval_seconds: 30
  urls:
    general: ""
    admin: ""
  events:
    join: false
    server_down: false
    loot_signature_mismatch: true
  channels:
    join: general
    server_down: general
    loot_signature_mismatch: admin
  messages:
    join: "**%player%** joined **%server%**."

First impressions

Welcome System

Greet players differently depending on their rank — title, subtitle, chat lines, action bar, sound, a firework, and an optional lightning strike. Everything is configured directly under welcome in config.yml.

How rank priority works

Each entry under welcome.ranks is keyed by a number, and that number is the permission. An entry keyed "10" requires auricnetwork.welcome.10 — there's no separate permission field to fill in. The entry keyed "0" is the default, used when a player doesn't have any other welcome permission. When a player matches more than one rank, the highest number wins.

What each rank can configure

Title timing

The title text doesn't just appear and disappear instantly — it fades in, stays on screen, then fades out. Each phase is measured in ticks, Minecraft's basic unit of time: there are 20 ticks in one second, so 40 means 2 seconds.

Firework and lightning

welcome:
  enabled: true
  ranks:
    "0":
      title:
        enabled: true
        text: "<gold>Welcome</gold>"
        subtitle: "<gray>%player_name%</gray>"
        fade_in_ticks: 10
        stay_ticks: 70
        fade_out_ticks: 20
      chat:
        enabled: true
        lines:
          - "<gray>Welcome to the network, %player_name%!</gray>"
      actionbar:
        enabled: false
        text: "<gray>Welcome!</gray>"
      sound:
        enabled: true
        sound_id: "entity.player.levelup"
        volume: 1.0
        pitch: 1.0
      effects:
        firework_enabled: false
        firework_count: 1
        firework_type: "BALL"
        firework_colors:
          - "YELLOW"
        lightning_enabled: false
    "10":
      title:
        enabled: true
        text: "<gradient:#ff6700:#fdc300>VIP</gradient>"
        subtitle: "<gray>Welcome back, %player_name%!</gray>"
        fade_in_ticks: 10
        stay_ticks: 70
        fade_out_ticks: 20
      chat:
        enabled: true
        lines:
          - "<gold>A VIP player has joined: %player_name%</gold>"
      actionbar:
        enabled: true
        text: "<gold>Enjoy your VIP perks, %player_name%!</gold>"
      sound:
        enabled: true
        sound_id: "entity.player.levelup"
        volume: 1.0
        pitch: 1.2
      effects:
        firework_enabled: true
        firework_count: 1
        firework_type: "STAR"
        firework_colors:
          - "#ff6700"
          - "#fdc300"
        lightning_enabled: false

Quick access

Hotbar Items

Give players configurable items in their hotbar the moment they join — a compass to open the server selector, a nether star to return to the lobby, or anything else you can imagine. Configured under hotbar in config.yml.

Item options

Available actions

Use any of these as a line under actions. You can combine several in the same list — for example, play a sound and then transfer the player.

Protection options

All four default to true, so a hotbar item is fully protected unless you explicitly turn an option off.

hotbar:
  enabled: true
  items:
    selector:
      slot: 4
      material: "COMPASS"
      name: "<gold>Server Selector</gold>"
      lore:
        - "<gray>Right click to open the menu</gray>"
      glow: false
      prevent_drop: true
      prevent_move: true
      prevent_pickup: true
      prevent_swap: true
      actions:
        - "open:selector"
    lobby_item:
      slot: 8
      material: "NETHER_STAR"
      name: "<yellow>Lobby</yellow>"
      lore:
        - "<gray>Right click to return to the lobby</gray>"
      glow: true
      prevent_drop: true
      prevent_move: true
      prevent_pickup: true
      prevent_swap: true
      actions:
        - "transfer:lobby"

Broadcasting

Named Announcements

Instead of a rotating list of messages, every announcement has its own id, its own lines, and is sent on demand with a command. Configured under announcements.list in config.yml.

How announcement permissions work

There's no permission field to fill in for each announcement. Instead, every id automatically requires its own node: auricnetwork.command.announce.<id>. A player with the parent auricnetwork.command.announce can run any announcement; a player with only auricnetwork.command.announce.discord can only run that one.

announcements:
  list:
    welcome_network:
      lines:
        - "<yellow>Welcome to our network!</yellow>"
    discord:
      lines:
        - "<aqua>Join our Discord: discord.gg/example</aqua>"
    vote:
      lines:
        - "<green>Vote for us daily to get rewards!</green>"
    staff_only:
      lines:
        - "<red>This is a staff-only announcement example.</red>"

Run it with /auricnetwork announce <id> — for example, /auricnetwork announce discord broadcasts the discord entry above to every online player. The command tab-completes with whichever ids you have permission to run.

Zero-database transfers

Full Loot Transfer

A player's complete inventory — storage, armor, off-hand, whatever's held on the cursor, and optionally the ender chest — travels with them across a transfer, riding inside the same connection the player already uses. No database, no proxy, no extra infrastructure of any kind.

How it actually works

Minecraft's own protocol has a small feature built specifically for this: cookies. Right before a transfer, the server hands the client a signed, compressed blob of data; the client carries it along and hands it back to whichever server it lands on next. AuricNetwork serializes the player's inventory, compresses it, signs it with HMAC-SHA256, and — if it's too big for a single cookie — splits it across up to 20 of them (roughly 96 KB of budget in total). If it still doesn't fit, nothing is touched: the transfer happens normally and the player simply keeps their current inventory, with a warning logged to console.

Setting it up: network_secret

Enable loot_transfer.enabled in config.yml and start the server once — a random network_secret is generated automatically and written back into that same file. Copy that exact value into loot_transfer.network_secret on every other server in your network. This is what lets a destination server verify that a payload genuinely came from another server in your network and reject anything else outright — including a modified client trying to hand back forged or replayed data.

loot_transfer:
  enabled: true
  include_enderchest: true
  recovery_history_size: 3
  max_payload_age_seconds: 300
  network_secret: "(auto-generated on first start)"

Every payload is also tied to the exact player it was created for. Even a correctly signed, not-yet-expired payload is rejected outright if it doesn't match the identity of the player currently connecting — so a payload can never be applied to the wrong person, whatever the reason it ended up in the wrong hands.

max_payload_age_seconds (300 by default) controls how long a payload stays valid after being created. A transfer normally finishes in a few seconds, so this only needs enough slack to cover a slow reconnect — it's kept short on purpose, since a longer window only widens how long an old payload could still be reused for.

If something goes wrong, nothing is silently lost

Before a player's inventory is cleared for the trip, a local backup is written to disk on the origin server. If the transfer fails completely after every retry, that backup is restored automatically — the player never ends up empty-handed on a server they never actually left. If a payload is rejected on the other end (for example because network_secret doesn't match), the backup still exists locally; it just needs to be restored by hand if the player comes back.

Recovering a backup by hand

Every transfer keeps a short history per player — recovery_history_size in config.yml controls how many (3 by default) — and it survives a restart since it's just local files, not memory.

Optional: syncing real statistics too

Separately from the inventory itself, AuricNetwork can also sync a player's actual vanilla statistics — the same ones Minecraft already tracks locally, like PLAY_ONE_MINUTE, MOB_KILLS, or JUMP — using the exact same signed payload. This is off by default, and every statistic is individually toggleable under stat_sync.statistics in config.yml, so nothing changes unless a specific stat is explicitly turned on.

When a statistic is enabled, syncing only ever raises the value to the higher of the two servers — it never lowers one. A player who already has 40 hours played on one server won't see that drop just because another server in the network only has 10.

Optional: full player continuity

Beyond the inventory and statistics, five more things can travel in the same signed payload, each its own independent switch in loot_transfer, all off by default. Useful for networks where one physical server hosts a spin-off of another — a dungeon instance branching off the main survival world, for example — where a transfer should feel invisible rather than like arriving at a different game.

Statistics use "keep the higher value" because they're counters that should never go backwards. These five are different: they're a snapshot of exactly how the player was the moment they left, so they replace the destination's value outright, the same way the inventory does.

Network control

Maintenance Mode

Take a server out of rotation without shutting it down. Players already connected elsewhere simply can't transfer into it.

Add the server's name to maintenance.servers in config.yml and set maintenance.enabled to true. Any /server attempt targeting that server — by a player or sent by an admin — is rejected with a message, and the player stays exactly where they were.

Or skip editing the file entirely: /auricnetwork maintenance <server> on adds it to the list and enables the system in one step, and /auricnetwork maintenance <server> off removes it again.

maintenance:
  enabled: true
  servers:
    - "survival"

What happens with the queue

Maintenance is checked before the queue. A server under maintenance always rejects the transfer outright — it never places the player in a queue, even if the queue system is enabled.

A full server without maintenance

This is a separate case worth knowing about: if a server is simply full (not in maintenance) and the queue system is enabled, the player is placed in a queue automatically. If the queue is disabled, the player is rejected immediately with a "server is full" message instead of waiting indefinitely.

Checking maintenance status

Run /auricnetwork status to see every server in the network along with a maintenance tag next to any server currently listed in maintenance.servers.

Dynamic text

Placeholders

AuricNetwork resolves its own placeholders internally — they work in announcements, the welcome system, the hotbar, the menu, the bossbar and the actionbar, even without PlaceholderAPI installed. If PlaceholderAPI is installed, the same placeholders are also registered as a normal PlaceholderAPI expansion under two identifiers: %auricnetwork_*% and the shorter %an_*%.

Network-wide

Per-server

Replace <server> with any server name from your servers list.

Queue

Party

Fallback

Rescue Server

When a server shuts down gracefully (e.g., /stop or a restart), AuricNetwork automatically transfers all online players to a configured rescue server. This prevents disconnections and improves user experience.

The fallback logs a detailed message to the console:

To enable it, add the following to your config.yml:

rescue_server:
  enabled: true
  target: "lobby"

Fallback list

target is where everyone goes first. If you also want a backup plan, enable fallback_list_enabled and list extra servers under fallback_list — AuricNetwork will also send any player still online through each one of them, in order, right after the main target.

rescue_server:
  enabled: true
  target: "lobby"
  fallback_list_enabled: true
  fallback_list:
    - "lobby2"
    - "lobby3"