Rewards

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 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.

User guide

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.

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.