Official Documentation

AuricPass

The Ultimate Battle Pass Experience for Minecraft servers.

Lightweight · Customizable · Independent

AuricPass is a lightweight, highly customizable, and independent Battle Pass plugin for your Minecraft server. Reward your players with an engaging progression system, featuring both Free and Premium tracks, custom GUI designs, and a unique Prestige system!

Download on Modrinth Discord Support YouTube Channel

At a glance

Everything you need to know

Whether you're setting up AuricPass for the first time or pushing it to its limits, this wiki covers every feature, command, permission, placeholder, and configuration option the plugin has to offer.

Free & Premium Tracks

Offer a standard reward line for everyone and an exclusive premium line to monetize your server.

Prestige System

The grind never stops. Players who reach max level enter an infinite loop, earning Extra Rewards for every specific amount of XP they gather.

Smart 6-Row GUI

Fully customizable menus with intelligent math-based pagination. Design your layout exactly how you want it.

Standalone XP Economy

AuricPass uses its own XP system via commands (/auricpass xp give). Integrate it with ANY other plugin (Quests, MythicMobs, Crates) just by running a console command.

Capabilities

Key Features

A complete toolkit designed to deliver a polished, rewarding Battle Pass experience for your community — without the bloat.

Free & Premium Tracks

Offer a standard reward line for everyone and an exclusive premium line to monetize your server.

Prestige System (Extra Rewards)

The grind never stops! Players who reach the max level enter an infinite loop, earning "Extra Rewards" for every specific amount of XP they gather.

Smart 6-Row GUI

Fully customizable menus with intelligent math-based pagination. Design your layout exactly how you want it.

Standalone XP Economy

AuricPass uses its own XP system via commands (/auricpass xp give). This means you can integrate it with ANY other plugin (Quests, MythicMobs, Crates) just by running a console command!

Advanced Command Execution

Rewards can trigger multiple actions. Use tags like [console], [player], [message], or [close] to execute exactly what you need.

Hex Colors & MiniMessage

Create stunning visuals with RGB gradients and modern formatting throughout the entire config.

Real PlaceholderAPI Integration

All %auricpass_*% placeholders work natively in any PAPI-compatible plugin. Supports per-player lookups like %auricpass_level_Steve%.

Multi-language

Comes with English (en.yml) and Spanish (es.yml) by default. Every player-facing message is fully configurable.

Reference

Commands

Below is the complete list of commands available in AuricPass. All commands are prefixed with /auricpass. Aliases: /battlepass, /bp, /pass.

/auricpass

Opens the Battle Pass GUI for yourself. Requires auricpass.use.

/auricpass open [player]

Opens the Battle Pass GUI. Optionally target another player to view their pass. Opening another player's pass requires auricpass.commands.open.

/auricpass xp give <player> <amount>

Gives a specified amount of XP to a player. Auto-levels up if enough XP is reached. Append nvl to give levels instead (e.g. 5nvl).

/auricpass xp remove <player> <amount>

Removes XP from a player. Append nvl to remove levels instead (e.g. 2nvl).

/auricpass xp reset <player>

Resets a player's XP and level to the starting state.

/auricpass premium give <player>

Grants the Premium Battle Pass to the specified player permanently.

/auricpass premium remove <player>

Removes the Premium Battle Pass from the specified player.

/auricpass xp check <player>

Displays a player's current level, XP and premium status directly in chat. Works from console too.

/auricpass season end [name]

Ends the current season, resets all player progress and saves a backup to the seasons/ folder with the given name (or season1.yml, season2.yml... if no name is provided). Controlled by seasons.store-history in config.

/auricpass season restore <name>

Restores a previously saved season backup, replacing the current database. Use this if you ended a season by mistake.

/auricpass season list

Lists all saved season backups available in the seasons/ folder.

/auricpass reload

Reloads the plugin's configuration, all language files and the player data from disk.

/auricpass help

Displays the help menu with all available commands.

Access control

Permissions

Manage who has access to specific AuricPass features using the following permission nodes.

You can grant the premium pass either via the command /auricpass premium <player> or by assigning the permission auricpass.premium. The auricpass.admin node grants all sub-permissions at once.

auricpass.use

Allows a player to open their own Battle Pass GUI. Granted to all players by default.

auricpass.premium

Grants the player access to the Premium reward track automatically without a command.

auricpass.admin

Meta-permission that includes all auricpass.commands.* nodes including season. Granted to ops by default.

auricpass.commands.open

Access to the command that opens the selected player's Battle Pass inventory.

auricpass.commands.premium

Access to the command to activate premium mode on another player.

auricpass.commands.reload

Access to the command that reloads the plugin's settings, language files and player data from disk.

auricpass.commands.xp

Access to the XP command with all its variants (give / remove / reset / check).

auricpass.commands.season

Access to the season management commands (end / restore / list).

Integration

Placeholders

Use these placeholders in your scoreboards, chat formats, or any plugin that supports PlaceholderAPI. AuricPass also has an internal placeholder engine that works in lore and item names even without PAPI.

PlaceholderAPI required for use in external plugins (scoreboards, chat, etc). The internal engine handles %auricpass_*% placeholders inside the plugin's own lore and GUI text automatically, even without PAPI installed.

Self placeholders for the viewing player

%auricpass_level%

Displays the player's current level.

%auricpass_xp%

Shows the amount of XP the player has earned at their current level.

%auricpass_required%

Shows the total XP required to advance from the current level to the next.

%auricpass_xp_left%

Shows the XP still needed to reach the next level.

%auricpass_premium_status%

Displays the player's tier as a formatted string (e.g. Premium or Free). The text is configurable in the language files.

%auricpass_premium%

Returns true or false depending on whether the player has the premium pass. Useful for conditional formatting in plugins that support it.

Per-player lookup placeholders for any player by name

Append _<PlayerName> to any placeholder to look up data for a specific player regardless of who is viewing. Works with both online and offline players. Requires PlaceholderAPI.

%auricpass_level_<player>%

Returns the current level of the specified player. Example: %auricpass_level_Steve%

%auricpass_xp_<player>%

Returns the current XP of the specified player. Example: %auricpass_xp_Alex%

%auricpass_required_<player>%

Returns the XP required for the specified player's current level.

%auricpass_xp_left_<player>%

Returns the XP still needed to level up for the specified player.

%auricpass_premium_status_<player>%

Returns the premium status string for the specified player.

%auricpass_premium_<player>%

Returns true or false for the specified player's premium status.

Setup

Configuration Guide

The config.yml file in AuricPass is highly customizable. It supports MiniMessage for hex colors and gradients and allows you to structure the GUI and rewards exactly as you need.

Topics Action Tags Custom Items Sounds Rewards Player Heads XP & Levels Prestige Seasons

1 Action Tags (Commands)

When setting up rewards or interactive items in the GUI, you can trigger multiple actions using our advanced tag system. You can stack as many commands as you want.

[console] command — Executes the command via the console (Default).
[player] command — Forces the player to execute the command.
[message] <text> — Sends a direct chat message to the player. Supports MiniMessage formatting.
[close] — Automatically closes the inventory when clicked.

View Action Tags example

YAML

commands:
  - "[console] give %player% diamond 1"
  - "[message] <green>You claimed your daily diamond!</green>"
  - "[player] spawn"
  - "[close]"

2 Custom Items (Row 1)

The first row of the menu (slots 0 to 8) is completely empty by default. This is the row-1-custom section, where you can create custom items to display information, links to your store, or open other menus.

View Custom Item example

YAML

row-1-custom:
  info-item:
    enabled: true
    slot: 4
    material: "BOOK"
    name: "<yellow><bold>Information</bold></yellow>"
    lore:
      - "<gray>Welcome to the Battle Pass!</gray>"
      - "<gray>Complete missions to earn XP.</gray>"
    commands:
      - "[message] <green>Welcome to the Battle Pass!</green>"
    sound: "ENTITY_EXPERIENCE_ORB_PICKUP;1.0;1.0"

3 Adding Sounds

You can assign sounds to practically any item click or reward claim. The system uses the format SOUND_NAME;VOLUME;PITCH. If you do not want a sound, simply use "none".

Tip: Browse the official Minecraft Sound enum in the Bukkit/Paper API documentation for a complete list of available sound names.

View Sound example

YAML

# Example of a level up sound:
sound: "ENTITY_PLAYER_LEVELUP;1.0;1.0"

# Example with no sound:
sound: "none"

4 Adding Rewards (Free & Premium)

You can create as many levels as you want under the rewards: (Free) and premium-rewards: sections. Make sure the node name follows the format level-X. The number of reward levels should match your max-level setting.

View Reward example

YAML

rewards:
  level-10:
    material: "DIAMOND_SWORD"
    name: "<aqua><bold>Level 10</bold></aqua>"
    lore:
      - "<yellow>Reward:</yellow>"
      - "<white>- 1x Epic Sword</white>"
      - "<gray>Missing <aqua>%auricpass_xp_left% XP</aqua> for level up!</gray>"
    commands:
      - "[console] give %player% diamond_sword 1"
    sound: "ENTITY_PLAYER_LEVELUP;1.0;1.0"

5 Custom Player Heads (Base64)

If you want to display the viewer's own head in the GUI, set the material to PLAYER_HEAD @self. You can also use a custom Base64 texture string to load decorative heads (like a treasure chest or a star).

View Custom Head example

YAML

player-info:
  slot: 49
  material: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYmFkYzA0OGE3Y2U3OGY3ZGFkNzJhMDdkYTI3ZDg1YzA5MTY4ODFlNTUyMmVlZWQxZTNkYWYyMTdhMzhjMWEifX19"
  name: "<green><bold>Bonus Chest</bold></green>"
  lore:
    - "<gray>This item uses a Base64 texture!</gray>"
  commands: []
  sound: "none"

6 XP & Level Settings

Define the maximum number of reward levels your Battle Pass has and the XP required per level using ranges. This saves you from writing every single level manually. Levels beyond max-level are handled by the Prestige system. You can also configure the levelup-sound played when a player reaches a new level, and the level-up message in your language files.

View XP Settings example

YAML

settings:
  max-level: 54
  levelup-sound: "ENTITY_PLAYER_LEVELUP;1.0;1.0"
  xp-for-level:
    "1-10": 10
    "11-20": 15
    "21-30": 25
    "31-40": 40
    "41-54": 50

7 Prestige System (Extra Rewards)

Once a player reaches the maximum level, enable the extra-rewards system to give them a repeating prize for every X amount of XP they earn beyond the cap. Set limit: -1 to make it infinite. All command action tags ([console], [player], [message], [close]) are fully supported here too.

View Prestige example

YAML

extra-rewards:
  enabled: true
  slot: 53
  xp-required: 50
  limit: -1
  material: "NETHER_STAR"
  name: "<aqua><bold>Prestige Rewards</bold></aqua>"
  commands:
    - "[console] give %player% diamond 1"
    - "[message] <gold>Prestige reward claimed!</gold>"

8 Season System

Configure how AuricPass stores season history when you run /auricpass season end. You can store every season forever, set a cap on how many to keep, or disable storage entirely if you just want a wipe.

View Season Settings example

YAML

seasons:
  # Save a backup each time a season ends.
  store-history: true

  # Keep at most 3 backups. The oldest is deleted when exceeded.
  # Use -1 to keep all backups forever.
  max-history: 3

If you end a season by accident, use /auricpass season restore <name> to bring the data back instantly. Use /auricpass season list to see all available backups.