Skip to main content
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.

​
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

CommandPermissionDescription
/battlepass pass <id> xp add <amount> [player]typewriter.battlepassAdd XP to a player’s battle pass.
/battlepass pass <id> xp remove <amount> [player]typewriter.battlepassRemove XP from a player’s battle pass.
/battlepass pass <id> xp set <amount> [player]typewriter.battlepassSet a player’s battle pass XP.
/battlepass pass <id> level add <amount> [player]typewriter.battlepassAdd levels to a player’s battle pass.
/battlepass pass <id> level remove <amount> [player]typewriter.battlepassRemove levels from a player’s battle pass.
/battlepass pass <id> level set <amount> [player]typewriter.battlepassSet a player’s battle pass level.
/battlepass pass <id> info [player]typewriter.battlepassView battle pass progress info.

​
Placeholders

Prefix: %battlepass:<pass_id>:<key>% or %typewriter_<pass_id>:<key>%
PlaceholderReturnsExample
%battlepass:<id>:name%Battle pass nameSeason 1
%battlepass:<id>:active%1 if active, 0 otherwise1
%battlepass:<id>:level%Player’s current level5
%battlepass:<id>:xp%Player’s current XP1250
%battlepass:<id>:xp:max%Max XP (total or current level)5000
%battlepass:<id>:xp:next%XP required for next level2000
%battlepass:<id>:xp:remaining%XP remaining until next level750
PlaceholderReturns
%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
PlaceholderReturns
%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)
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}
Used in BattlePassMessages entry fields:
PlaceholderContext
%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

PermissionDefaultDescription
typewriter.battlepassOPAccess to all /battlepass admin commands.
typewriter.battlepass.open(none)Open the battle pass menu (default: everyone).

​
Dependencies

ExtensionRequiredUsage
GUI ExtensionRequiredMenu rendering and layout system.
PlaceholderAPIOptionalFor @Placeholder fields.