Crate

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

User guide

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

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.