Crate

The Crate Extension provides virtual loot crates for the official Typewriter runtime: weighted rewards, virtual keys, milestones, OmniGUI menus and visual opening sequences. Physical world-crates and physical key adapters are reserved for the custom BTC profile and are not part of this public artifact.

Compatibility profiles

The public extension targets the official Typewriter runtime on Paper/ASPaper 1.21.x and emits JVM 21 bytecode so it remains usable on official 1.21 servers. It uses the official OmniGUI dependency (renaud:GuiAndDialogs) for menus.

The custom BTC profile is a separate adapter layer. It may target BTC Core, BTC Velocity, Folia and Java 25, but those dependencies and scheduler assumptions must not be introduced into this public artifact.

Opening mini-games

Crates can open through a world-space mini-game instead of a plain animation. The reward is drawn server-side before the mini-game starts; the game is pure presentation and grants the already-decided reward exactly once.

• Cards — A grid of face-down cards; the selected card reveals the reward and the rest reveal decoys.

Architecture

Entry library

Definitions

• Crate Definition — Main definition of a loot box.
• Global Menu — Browse all available crates.
• Cards Mini-Game — Optional world-space reveal.

Actions

• Open Crate — Trigger an opening sequence.
• Open Menu — Open a crate reward menu.

Artifacts

• Crate Artifact — Persistent keys and history.

Quick start

1. Define a crate and, if needed, a crate_main_menu entry.
2. Create a crate_artifact and reference it from the crate.
3. Configure rewards, rarity weights, reward slots and optional milestones.
4. Trigger open_crate or open_crate_menu from Typewriter.

Commands

All commands are under /crate:

Command	Description	Permission
/crate menu	Open the global crate menu	typewriter.crate.menu
/crate give <crate_id> [amount]	Grant virtual keys	typewriter.crate.give
/crate remove <crate_id> [amount]	Revoke virtual keys	typewriter.crate.remove

Placeholders

Both %crate_<crate_id>_<field>% and %typewriter_crate_<crate_id>_<field>% are accepted.

Field	Description
openings	Total openings by the player
keys	Virtual keys held
keys_used	Keys consumed
last_open	Last opening timestamp
milestone	Highest reached milestone

Unknown crates and fields return null, allowing Typewriter's placeholder fallback to apply.

Permissions

Permission	Description
typewriter.crate	Base access to crate commands
typewriter.crate.menu	Open the crate menu
typewriter.crate.give	Give virtual keys
typewriter.crate.remove	Remove virtual keys

Dependencies

Extension	Required	Usage
Typewriter Basic	Required	Typewriter runtime and entries
OmniGUI / GuiAndDialogs	Required	Menu rendering and layout system
PlaceholderAPI	Optional	Placeholder parsing where installed