Rewards

The Rewards Extension allows you to give rewards to players even when they are offline or have full inventories. Rewards are queued and can be claimed later.

Features

• Deferred Claiming — Store rewards safely.
  • Visual GUI — Menu for claiming pending items.
  • Scheduling — Cron support for daily rewards.
  • History — Track lifetime claimed rewards.

Architecture

Entries

• Definition — btc_reward_definition: reusable reward template.
• Config — btc_rewards_config: sounds, toasts, messages and lore layout.
• Actions — btc_give_reward: queue a reward. btc_open_rewards_menu: open the claim screen.
• Storage — btc_rewards_artifact: the queue itself and claim history.
• Event — btc_reward_claimed_event: fires on every claim.
• Fact — btc_has_pending_rewards: pending count, usable in criteria.

Quick Start

1. Create the storage — add one btc_rewards_artifact. A single artifact backs the whole queue.
2. Configure globals — add one btc_rewards_config for sounds, messages and the reward lore layout.
3. Define your rewards — one btc_reward_definition per reward type, each with its rewardId and source.
4. Queue them — trigger btc_give_reward from a command, an NPC, an event, or on a cron schedule.
5. Let players claim — trigger btc_open_rewards_menu, or place rewards_button: markers on an existing page.

Menus

Rewards can be shown two ways, both sharing the same claim logic and the same item rendering:

• Standalone screen — the btc_open_rewards_menu action builds its own inventory.
• As a tab of any page — place tagged items and the extension fills them in at render time. This is what lets the queue live inside the shared menu chassis instead of a separate screen.

Marker tag	Renders
rewards_button:REWARD_SLOT#<n>	The viewer's n-th pending reward. Past the last one the slot renders empty, so the grid is a display ceiling rather than a declared reward count.
rewards_button:BULK_CLAIM	Claims every reward the player has room for.

The configured item of a tagged slot is preserved for position and styling; only reward slots have their item replaced by the reward's own display item.

Placeholders

MiniPlaceholders expansion: rewards.

Placeholder	Description
<rewards_pending>	Total pending count
<rewards_pending:rewardId>	Count for one reward type
<rewards_source:source>	Count for one origin (event, vote, daily_login…), case-insensitive
<rewards_claimed_total>	Lifetime claimed

备注

The reward id is a tag argument, not a name suffix — <rewards_pending:daily>, not <rewards_pending_daily>. A pending reward whose definition no longer exists is skipped by <rewards_source:...> rather than counted as uncategorised.

Dependencies

Extension	Required	Usage
GUI Extension	Required	Menu rendering, layout system and click dispatch.
MySql Extension	Optional	Cross-server cache invalidation over Redis. Without it the queue still works, on a single server.