BattlePass
The Battle Pass Extension allows you to create seasonal progression systems. Players earn XP, level up, unlock tiers, and claim rewards through a fully configurable GUI.
Features
- Seasons — Scheduled battle passes with start/end dates and timezone support.
- Tiers — Multiple progression tiers with permissions, priorities, and rewards.
- Weekly Quests — Time-gated quests that unlock week by week.
- XP System — Configurable XP per quest, per level thresholds, and max XP.
- Custom UI — Every button template is configurable: fill, tiers, weeks, quests, navigation.
- Messages — All chat messages customizable with placeholders.
Performance & Cross-Server
Player progress reads go through an in-memory artifact cache, so menus, placeholders and quest checks never block on storage in the hot path — writes update the cache and persist in the background.
On networks, the cache is kept coherent with cross-server invalidation over Redis: when a player's progress changes on one backend (XP gain, reward claim), other servers holding a cached copy drop it and reload on next access. Redis rides the MySQL extension's shared RedisService; on a single server the cache simply works without Redis.
Architecture
Entry Library
Configuration
- Messages — Customize all chat messages with placeholders.
Definitions
- Battle Pass Definition — Define the full battle pass: tiers, weeks, layout, buttons, and schedule.
Actions
- Open Battle Pass — Action that opens the battle pass menu for a player.
Artifacts
- Battle Pass Data — Persistent storage for player progress (XP, level, rewards).
Facts
- Quest Active Fact — Returns 1 when a configured battle pass week is active for the player.
Quick Start
-
1. Create the Data Artifact — Start by adding a Battle Pass Data artifact entry. This stores all player progress (XP, level, claimed rewards) persistently. - The artifact acts as the database for one battle pass - Link it in the definition in the next step → Battle Pass Data
-
2. Customize Messages (Optional) — Add a BattlePass Messages entry to customize all chat messages. Configure notifications for XP gained, rewards claimed, level ups, and command feedback. - Messages support
%player%,%pass%,%amount%,%level%,%reward%,%tier%placeholders - Leave empty to use built-in defaults → Messages -
3. Define the Battle Pass — Add a Battle Pass Definition entry. This is the core configuration: -
data→ Link to the artifact from step 1 -icon→ Item shown in menus (e.g.minecraft:book) -tiers→ Progression levels with permissions, priorities, and rewards -weeks→ Weekly quest sets with unlock dates and XP rewards -layout→ Menu size, slot assignments, navigation buttons -schedule→ Start/end dates and week duration -xp→ Level thresholds and max XP -buttons→ Customize every button: tiers (locked/unlocked/current), weeks (locked/available/active/completed), quests (locked/available/active/completed), navigation, sort, info → Battle Pass Definition -
4. Open the Menu — Add an Open Battle Pass action entry to let players access the menu. Trigger it from: - A command or NPC interaction - Another menu button - A quest event or cinematic → Open Battle Pass
Commands
| Command | Permission | Description |
|---|---|---|
/battlepass pass <id> xp add <amount> [player] | typewriter.battlepass | Add XP to a player's battle pass. |
/battlepass pass <id> xp remove <amount> [player] | typewriter.battlepass | Remove XP from a player's battle pass. |
/battlepass pass <id> xp set <amount> [player] | typewriter.battlepass | Set a player's battle pass XP. |
/battlepass pass <id> level add <amount> [player] | typewriter.battlepass | Add levels to a player's battle pass. |
/battlepass pass <id> level remove <amount> [player] | typewriter.battlepass | Remove levels from a player's battle pass. |
/battlepass pass <id> level set <amount> [player] | typewriter.battlepass | Set a player's battle pass level. |
/battlepass pass <id> info [player] | typewriter.battlepass | View battle pass progress info. |
Placeholders
Prefix: %battlepass:<pass_id>:<key>% or %typewriter_<pass_id>:<key>%
Global Placeholders
| Placeholder | Returns | Example |
|---|---|---|
%battlepass:<id>:name% | Battle pass name | Season 1 |
%battlepass:<id>:active% | 1 if active, 0 otherwise | 1 |
%battlepass:<id>:level% | Player's current level | 5 |
%battlepass:<id>:xp% | Player's current XP | 1250 |
%battlepass:<id>:xp:max% | Max XP (total or current level) | 5000 |
%battlepass:<id>:xp:next% | XP required for next level | 2000 |
%battlepass:<id>:xp:remaining% | XP remaining until next level | 750 |
Reward Placeholders
| Placeholder | Returns |
|---|---|
%battlepass:<id>:rewards:total% | Total number of rewards |
%battlepass:<id>:rewards:claimed% | Number of claimed rewards |
%battlepass:<id>:rewards:available% | Number of available rewards |
%battlepass:<id>:rewards:unclaimed% | Available minus claimed |
Week Placeholders
| Placeholder | Returns |
|---|---|
%battlepass:<id>:week:<n>:state% | Week state: LOCKED, AVAILABLE, COMPLETED |
%battlepass:<id>:week:<n>:active% | 1 if active, 0 otherwise |
%battlepass:<id>:week:<n>:title% | Week title |
%battlepass:<id>:week:<n>:description% | Week description |
%battlepass:<id>:week:<n>:release% | Release date (formatted) |
%battlepass:<id>:week:<n>:release_in% | Time until release (e.g., 2d 5h) |
Template Variables (in Button @Placeholder fields)
These {variable} placeholders are replaced inside menu button templates.
Tier Buttons: {tier_level}, {tier_priority}, {tier_permission}, {tier_status}, {tier_status_color}, {tier_rewards}, {tier_index}, {tier_page_index}, {tier_total}, {tier_page}, {tier_max_page}, {reward_level_required}, {reward_state}, {reward_state_color}, {reward_name}, {reward_description}, {reward_index}, {reward_page_index}, {reward_total}, {reward_page}, {reward_max_page}
Week Buttons: {week_number}, {week_title}, {week_status}, {week_state_color}, {week_selected}, {week_index}, {week_available}, {week_description}, {quests_total}, {quests_completed}, {quests_active}, {quest_list}, {week_release}, {week_release_in}
Quest Buttons: {quest_id}, {quest_name}, {quest_status}, {quest_state}, {quest_state_color}, {quest_index}, {quest_page_index}, {quest_total}, {quest_filtered}, {quest_page}, {quest_max_page}, {quest_sort}, {quest_sort_key}, {quest_unlocked}, {quest_description}, {quest_progress}, {quest_objectives}
Navigation: {quest_page}, {quest_max_page}, {quest_total}, {quest_filtered}, {quest_sort}, {quest_sort_key}, {page}, {max_page}, {direction}
Back/Close: {battle_pass_id}, {battle_pass_name}, {player_name}
Tier Menu Open: {tier_total}, {tier_unlocked}, {tier_current_level}, {tier_current_priority}, {tier_current_permission}, {tier_current_status}, {tier_current_rewards}, {tier_next_level}, {tier_next_priority}, {tier_next_permission}, {tier_next_rewards}
Info Button: {week_number}, {week_title}, {week_description}, {week_available}, {week_release}, {week_release_in}, {pass_start}, {pass_end}, {pass_active}, {pass_remaining}, {page}, {max_page}, {total_weeks}, {selected_week_number}, {selected_week_title}, {selected_week_available}, {selected_week_description}
Message Placeholders
Used in BattlePassMessages entry fields:
| Placeholder | Context |
|---|---|
%player% | Player name |
%pass% | Battle pass name |
%amount% / %total% / %value% | XP amounts |
%level% | Player level |
%xp% | Player XP |
%reward% | Reward name |
%tier% | Tier level |
Permissions
| Permission | Default | Description |
|---|---|---|
typewriter.battlepass | OP | Access to all /battlepass admin commands. |
typewriter.battlepass.open | (none) | Open the battle pass menu (default: everyone). |
Dependencies
| Extension | Required | Usage |
|---|---|---|
| GUI Extension | Required | Menu rendering and layout system. |
| PlaceholderAPI | Optional | For @Placeholder fields. |