Battlepass Definition

Register a battle pass definition

清单由 BattlePass 提供

Manifest entry used by TypeWriter to register a [BattlePassDefinition]. The definition itself is fully described in the configuration file. When this entry is compiled into the runtime registry by the extension lifecycle.

字段

字段	类型	默认值	描述
icon	String	minecraft:book	—
description	List<String>	empty	—占位符多行
data	Ref<BattlePassDataArtifactEntry>	—	—
tiers	List<TierConfig>	empty	— TierConfig（5） 字段 类型 默认值 描述 level Int 0 Display order of the tier (starting at 1) permission String — Permission required to access the tier priority Int 0 Priority controls which tier overrides another rewards List<RewardConfig> empty — RewardConfig（4） 字段 类型 默认值 描述 levelRequired Int 0 — triggers List<Ref<TriggerableEntry>> empty — displayName String — —占位符颜色 lore List<String> empty —占位符颜色多行 slots List<String> empty Slots used to display this tier's rewards inside the menu. Supports ranges such as '10-16'.
weeks	List<BattlePassWeekConfig>	empty	— BattlePassWeekConfig（7） 字段 类型 默认值 描述 number Int 0 Week number (used for ordering) title String — —占位符颜色 available Boolean true — description List<String> empty —占位符颜色多行 quests List<BattlePassQuestConfig> empty Quests unlocked during this week BattlePassQuestConfig（2） 字段 类型 默认值 描述 xpReward Long 0 — description List<String> empty —占位符颜色多行 unlockAt String — Explicit unlock date (ISO-8601). Overrides offset settings unlockOffsetDays Long? — Unlock offset in days from the battle pass start date
layout	MenuLayoutConfig	—	— MenuLayoutConfig（29） 字段 类型 默认值 描述 size Int 54 — weekSlots List<String> empty — tierButtonSlot Int? — — tierButtonEnabled Boolean true — questSlots List<String> empty — questPreviousSlot Int? — — questPreviousEnabled Boolean true — questNextSlot Int? — — questNextEnabled Boolean true — questSortSlot Int? — — questSortEnabled Boolean true — questBackSlot Int? — — questBackEnabled Boolean true — tierMenuSize Int 54 — tierMenuPreviousSlot Int? — — tierMenuPreviousEnabled Boolean true — tierMenuNextSlot Int? — — tierMenuNextEnabled Boolean true — tierMenuBackSlot Int? — — tierMenuBackEnabled Boolean true — previousWeekSlot Int? — — previousWeekEnabled Boolean true — nextWeekSlot Int? — — nextWeekEnabled Boolean true — closeSlot Int? — — closeEnabled Boolean true — backCommand String — Command executed when using the back button. Run as the player. Supports placeholders. infoSlot Int? — — infoEnabled Boolean true —
schedule	BattlePassScheduleConfig	—	— BattlePassScheduleConfig（4） 字段 类型 默认值 描述 start String — Battle pass start date (ISO-8601). Leave empty for immediate start end String — Battle pass end date (ISO-8601). Leave empty for no end weekDurationDays Long 7 Duration of a week in days timezone String UTC IANA timezone used to parse local schedule dates, for example Europe/Paris
buttons	BattlePassMenuButtonsConfig	—	— BattlePassMenuButtonsConfig（27） 字段 类型 默认值 描述 fill MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 levelLocked MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 levelUnlocked MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 levelCurrent MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 tierLocked MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 tierUnlocked MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 tierCurrent MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 weekLocked MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 weekAvailable MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 weekActive MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 weekCompleted MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 questLocked MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 questAvailable MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 questActive MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 questCompleted MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 questPrevious MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 questNext MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 questSort MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 previousWeek MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 nextWeek MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 questBack MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 close MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 tierMenuOpen MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 tierMenuPrevious MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 tierMenuNext MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 tierMenuBack MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行 info MenuButtonConfig — — MenuButtonConfig（2） 字段 类型 默认值 描述 item Item — — lore List<String> empty —占位符颜色多行
xp	BattlePassXpConfig	—	— BattlePassXpConfig（2） 字段 类型 默认值 描述 max Long 0 — levels List<Long> empty —
baseMenuId	String	—	Optional open_gui chassis to inherit. Empty keeps the standalone Battle Pass inventory.
menuLayoutPool	List<LayoutData>	empty	Additional GUI layouts merged over the inherited chassis.
menuViews	List<MenuViewData>	empty	Additional views merged over the inherited chassis. Slots tagged view:<id> are wired automatically.
menuMainLayoutId	String?	—	Main layout id for a definition-owned chassis. Empty = inherited main layout.
menuDefaultViewId	String?	—	Initial view id. Empty = inherited default view.
menuHomeViewId	String	battlepass_home	Home view id used by the Battle Pass navigation.
menuLevelsViewId	String	battlepass_levels	Levels/rewards view id used by the Battle Pass navigation.
menuQuestsViewId	String	battlepass_quests	Quests view id used by the Battle Pass navigation.
menuBreadcrumbSeparator	String	—	MiniMessage separator used in the inherited menu breadcrumb.颜色
menuPushHistoryOnViewSwitch	Boolean	false	Whether switching between Battle Pass views pushes a history entry.

How to use it

One definition is one battle pass. The fields work together like this:

• xp — levels is a list of cumulative XP thresholds in increasing order. A player is level 2 once their XP reaches the second threshold. max caps the XP (0 means no cap).
• weeks — each week has a number (unique, above zero), the quests it contains with their xpReward, and an optional unlock date. A week unlocks at unlockAt if set, otherwise at the pass start plus unlockOffsetDays, otherwise at the start plus weekDurationDays for every previous week. Without a schedule.start, weeks without a date are unlocked from the beginning.
• schedule — start and end accept 2026-11-01T00:00:00 (read in timezone) or a full UTC date such as 2026-11-01T00:00:00Z. XP is earned only between them; rewards can still be claimed after the end.
• tiers — each tier level must be unique. A tier with a permission only lets players holding it claim its rewards. Each reward needs a unique id (leave it empty to get tier-<level>-reward-<n>), a levelRequired and the triggers that deliver it.
• layout and buttons — slots and button items of the default menus. Sizes must be multiples of 9 up to 54.
• baseMenuId, menuLayoutPool, menuViews, menuMainLayoutId, menuDefaultViewId — fill any of them to open the pass inside a GUI chassis built with the GUI extension. Leave them all empty to use the standalone menus.

A definition that fails validation is skipped at startup and the reason is written to the server log.