> For the complete documentation index, see [llms.txt](https://lethium.gitbook.io/lethium-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lethium.gitbook.io/lethium-docs/server-setup/excellentcrates-rewards.md). # ExcellentCrates: rewards and editing How crate rewards are built, the odds rule, zone-locked bands, and how to edit crate files safely. Details for [ExcellentCrates](/lethium-docs/server-setup/excellentcrates.md). ### How rewards are built Rewards run **console commands into ClickEm**. They do not depend on ExcellentCrates knowing about ClickEm. Typical reward commands: | Reward | Command | | --------------------------- | ---------------------------------------------------------------------------------- | | Coins equal to N mob kills | `admin givekills %player_name% 45 coins` | | Gems, Essence | `admin give %player_name% gems` (or `artifact_essence`) | | A pet box | `egg admin give-item %player_name% ` | | A boost | `boosts admin grant %player_name% ` | | Profile XP | `profilelevel admin addxp %player_name% ` | | Pet candy | `pet candy give %player_name% ` | | Pet tickets | `pet tickets give %player_name% ` | | Season Pass XP | `seasonpass admin addxp %player_name% ` | | Cosmetic voucher | `voucher admin cosmetic %player_name% 1` | | Temporary rank | `lp user %player_name% permission settemp clickem.vip. true d accumulate` | | A small permanent stat gift | `admin stat give %player_name% ` | **Coin rewards are worded "Coins (N mob kills)"**: the amount is what N kills in the player's furthest zone would pay, including their stats (see [Reward scaling](/lethium-docs/configuration/reward-scaling.md)). This keeps every crate useful from day one to World 5. ### Zone-locked rewards Pet boxes, Echoes and instant pets come in **bands by zone**. A band is live only while the player owns that tier's zone and **not** the next one. This uses the permission `clickem.zone.` that ClickEm gives automatically for each zone a player owns (see [Zones](/lethium-docs/gameplay/zones.md)). So one band is live per player at a time. ### Odds {% hint style="danger" %} **The rarity weights are a rule, not a suggestion.** The global rarity weights are **common 55, rare 27, epic 12, legendary 5, mythic 1 (= 100)**. In every crate each rarity's reward weights **sum to that rarity's weight**, so a reward's `Weight` **is its percent chance**. If you change one reward's weight, change another in the same rarity by the opposite amount, or the odds shown to players will be wrong. {% endhint %} The cosmetic crates put everything in one bucket whose weights sum to 100. The description shown in each reward includes `Chance: %`. Keep it in sync with `Weight`. ### Changing things {% tabs %} {% tab title="Move or add a crate in the world" %} Get the **Link Tool** (a blaze rod named "Link Tool", `Crate.LinkTool` in `config.yml`). ExcellentCrates' own crate editor or command gives it to you, see `/crates help`. Hold it and click the block. `Block.Positions` in the crate file stores it as `x,y,z,world`. The seven crates are already linked in World 1 only. Link them again in other worlds if you want crates there. {% endtab %} {% tab title="Change a hologram" %} Holograms use **templates** in `config.yml` under `Crate.Holograms.TemplateList` (one per crate). A crate picks one with `Hologram.Template`. Edit the text there. {% endtab %} {% tab title="Change reward amounts" %} Edit the `Commands:` of a reward in its crate file. Keep the `Weight` totals per rarity unchanged. {% endtab %} {% tab title="Change the opening animation" %} A crate's `Animation.Id` picks one from `openings/`. The shipped crates use `simple_roll`. `Preview.Id` picks the preview menu from `previews/` (`ladder`, `cosmetic`, `default`). {% endtab %} {% tab title="Milestones" %} `milestones.yml` and the crate's `Milestones` section give extra rewards for opening a crate a number of times. The menu text is in `milestones.yml`. {% endtab %} {% endtabs %} {% hint style="danger" %} **The crate files are huge** (up to 600 KB) because every reward carries a fully styled item. Edit them with a proper editor (VS Code), never a plain notepad, and always keep a copy before editing. The rarity frame glyphs are baked into each reward's name and description when the crates are generated. If you ever change `rarity-tooltips` in ClickEm's `config.yml`, the crates must be regenerated to match. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://lethium.gitbook.io/lethium-docs/server-setup/excellentcrates-rewards.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.