Crate

Loot crates with weighted rewards, virtual keys, milestones and a card-picking opening mini-game.

Privatev0.0.2Economy & crafting

RequiresTypeWriter0.9BasicGUI

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview

Crate adds loot crates to your server. A crate has a list of rewards, each with a rarity, and players open it by spending a virtual key. The winning reward is drawn on the server before any animation starts, so nothing a player does during the opening can change the result. Opening a crate counts towards milestones, which can trigger extra rewards after a number of openings.

Rewards are TypeWriter triggers, so a reward can give an item, run a command, grant a cosmetic or start a sequence. The opening is shown in the world in front of the player: a preview of the rewards on floating item displays, or a card-picking mini-game. Menus let players browse the crates and the rewards each one can give.

The extension runs on the BTC build of TypeWriter (BTC Core, Paper/Folia) and is documented here for reference.

Features

• Weighted rewards — rarities carry a weight, and the chance of each reward is shown in the menus.
• Virtual keys — keys are counted per player in the crate's data artifact, and one is spent at each opening.
• Safe openings — a key is reserved first and only spent when the reward is revealed; a disconnect, a timeout or a restart refunds it.
• Milestones — trigger extra rewards after a number of openings.
• Card mini-game — the player flips one of a grid of face-down cards, while the reward is already decided.
• World previews — rewards float around the player in PAGINATED, FLEX or SIMPLE layouts, with an optional NPC and hologram.
• Menus — a global crate menu and a reward menu per crate, with frames, pagination and custom buttons.
• Statistics — openings, keys, keys used, last opening and milestone, available as placeholders.

Installation

1. Install the TypeWriter Basic extension and the GUI extension (GuiAndDialogs in the BTC build). Crate will not load without them.
2. Put the Crate JAR in plugins/Typewriter/extensions/ and restart the server.
3. Grant the permissions in the Permissions section to your staff.

Getting started

Create a crate with three rewards and give yourself a key:

1. In the TypeWriter web panel, open a manifest page and add a Crate Data artifact. Keep the generated artifactId, and use one artifact per crate.
2. Add a Crate entry. Set dataArtifact to the artifact and write the noKeyMessage.
3. In rarities, add Common with weight 70 and Rare with weight 30.
4. In rewards, add three rewards: for each one set a rarity, an item shown in the preview, a name, and in action a trigger that gives the reward. Keep grantItem on to give the item automatically, or turn it off if the action gives the item itself.
5. In rewardSlots, list the inventory slots of the reward menu (counted from 0), for example 10-12. A crate with no reward slot refuses to open.
6. In icon, set the x and y of the crate in the global menu, an item and a name.
7. Add an Open Crate action pointing to the crate, and trigger it from an NPC, a block or an item.
8. Publish, then run /tw crate give <crate entry id> 5 and open the crate. Use /tw crate menu to browse the crates.

Reward clicks in the reward menu

In a crate's reward menu, clicking a reward triggers that reward's action directly, with no key spent and no statistics. Do not give players access to the reward menu if a reward's action gives something valuable, or keep the menu for staff.

Giving keys

Keys are added with /tw crate give <crate> <amount> [targets]. There is no dedicated action for keys, but a command action can run that command, for example from a quest reward or a shop.

How it works

The chance of a reward is the weight of its rarity divided by the total weight of all rewards. A reward whose rarity is not listed in rarities has a weight of 1. When the reward is revealed, the key is spent, the openings and keys-used counters go up, any milestone crossed fires, then the item is given (if grantItem is on) and the reward action runs. A player can only have one opening at a time.

Menus

• Global menu — opened with /tw crate menu. It shows one icon per crate, placed at the icon's x (0 to 8) and y (0 to 5), and clicking an icon opens that crate's reward menu. An optional Crate Main Menu entry sets the size, title, frame, buttons, items per page and the column reserved for the pagination arrows.
• Reward menu — opened by clicking an icon, or with the Open Crate Menu action. It shows the rewards in rewardSlots, with their name, lore, and optional chance and rarity lines (chanceLore and rarityLore, using {chance} and {rarity}). guiLayout is PAGINATED, FLEX (centred, four columns) or SIMPLE. frameItem, itemsPerPage and paginationColumn adjust the frame and pagination, and buttons add custom buttons with an action.

Buttons have a type (INFORMATION, NEXT, PREVIOUS, FILL) and a position. A FILL button is copied to every empty slot. The crate_button: markers (CRATE_OPEN, CRATE_PREVIEW, CRATE_GLOBAL_BROWSE, CRATE_REWARD_SLOT, NAV_BACK, NAV_CLOSE) are offered in the GUI editor, but they only show a placeholder item in this version.

Configuration

Crate has no configuration file. Everything is configured in entries. The player data lives in the Crate Data artifact: keys, openings, keys used, last opening time, milestone and pending openings. It is written asynchronously, and pending openings left by a crash are recovered at startup (the key is refunded).

Commands

All commands are subcommands of the TypeWriter command, so they start with /typewriter or /tw. <crate> is the entry of a crate and is auto-completed.

Command	Description	Permission
/tw crate menu	Opens the global crate menu.	typewriter.crate.menu
/tw crate open <crate>	Opens the crate, using one key.	typewriter.crate.open
/tw crate give <crate> [targets]	Gives one key to yourself or the selected players.	typewriter.crate.give
/tw crate give <crate> <amount> [targets]	Gives several keys.	typewriter.crate.give
/tw crate remove <crate> [targets]	Removes one key, only if the player has one.	typewriter.crate.remove
/tw crate remove <crate> <amount> [targets]	Removes several keys, only if the player has enough.	typewriter.crate.remove

The base permission typewriter.crate guards the whole command. The extension registers an internal /cratemenu command used by menu clicks; it is not meant to be typed.

Permissions

Permission	Grants
typewriter.crate	Access to the /tw crate command.
typewriter.crate.menu	/tw crate menu.
typewriter.crate.open	/tw crate open.
typewriter.crate.give	/tw crate give.
typewriter.crate.remove	/tw crate remove.

Placeholders

These are MiniPlaceholders tags of the crate expansion. Replace id with the entry ID of the crate. An unknown crate returns an empty value.

Placeholder	Returns
<crate_openings:id>	Number of openings of this crate by the player.
<crate_keys:id>	Keys the player holds.
<crate_keys_used:id>	Keys the player has spent.
<crate_last_open:id>	Time of the last opening, in milliseconds since 1 January 1970.
<crate_milestone:id>	The highest milestone reached.

In hologramLines, use the tokens {openings}, {keys}, {last_open} and {milestone} instead.

Entries

6 entries, generated from the extension source.

Actions2

• Open CrateOuvre une caisse
• Open Crate MenuOuvre le menu d'une caisse

Artifacts1

• Crate ArtifactDonnées de caisse

Manifests3

• CrateDéfinition d’une caisse
• Crate Main MenuApparence du menu principal
• Crate Minigame CardsMini-jeu Caisse : Cartes

Troubleshooting

"This crate is not configured correctly". The crate failed validation, and the server log lists the reasons: no rewards, an invalid rarity weight (it must be above zero), no rewardSlots or slots outside 0 to 53 or duplicated, a button or icon outside the 9 by 6 grid, or milestones at zero openings or duplicated. The same checks run at startup and write a warning.

The player gets the noKeyMessage. The player has no key for that crate, or the crate has no dataArtifact. Give keys with /tw crate give and check the artifact link.

"You are already opening a crate". An opening is in progress for that player. It ends when the reward is revealed or the player disconnects.

The statistics and keys do not change after an opening. They only change when the reward is revealed. If the player left or the server stopped before that, the key is refunded and the counters stay the same.

The preview shows nothing or the wrong rewards. The preview uses each reward's item. Rewards with an empty item are skipped, and preview.maxVisibleRewards limits how many show at once. preview.distance and the *Location offsets move the display.

The card mini-game does not start. Link a Crate Minigame: Cards entry in the crate's minigame field. Its columns go up to 10 and rows up to 10, and cardCount is capped at 100.

A reward is given twice. Keep grantItem on only when the action does not also give the item.

Related extensions

• GUI — menu engine used for the crate menus.