BattlePass
Official compatibility
| Element | Reference |
|---|---|
TypeWriter | Required. Use the official TypeWriter release supported by the extension release. |
| Related extensions | Install the related extensions listed on this page before using entries that depend on them. |
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.
User guide
-
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. |
Troubleshooting
The extension is not visible
Check that the installed release matches the supported TypeWriter release and that the related extensions listed in the compatibility section are present.
An entry is missing
In the Typewriter Web panel, use the Search bar or the + button to find or create the entry with its exact identifier. Entry IDs and field names are case-sensitive; do not translate them.
The entry saves but nothing happens
Check that the entry is connected to the trigger, command, objective, event, or menu interaction required by its type. Test with optional permissions and criteria removed, then add them back one at a time.
An integration does not work
Verify the dependency and version shown in the extension card, then check the server log for the first error. Do not replace a missing dependency with a similarly named plugin unless the extension source explicitly supports it.