> 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/gameplay/eggs.md).

# Eggs (pet boxes)

Pet boxes and eggs: prices, loot pools, zone locks, hatch animation and placing eggs in the world.

File: `plugins/ClickEmCore/modules/eggs.yml`. Module id: `eggs`. Commands: `/egg`, `/eggs`.

{% hint style="success" %}
**Quick start**

* Change an egg's price: `currency-cost` in `eggs.yml`.
* Change what is inside: `loot.pool`.
* Place an egg in the world: look at a block, `/ceadmin egg set-block <egg>`.
* Reload: `/clickem module reload eggs`.
  {% endhint %}

Eggs, also called **pet boxes**, are how players get [pets](/lethium-docs/gameplay/pets.md). A player pays Coins to hatch an egg and receives one random pet from its loot pool. The odds inside a pool come from each pet's rarity `egg-weight` in `pets.yml`.

The shipped setup has **40 eggs**: `zone_box_1`, `zone_box_4`, `zone_box_7` and so on, one for every third zone. A higher egg mixes in pets from earlier zones.

### Egg entry

```yaml
eggs:
  zone_box_4:
    rarity: COMMON
    required-zone: w1_zona4
    display-name: "clickem.eggs.zone_box_4.name"
    currency-cost: 89
    hatch-delay-seconds: 2
    multi-hatch: [1, 10, 100]
    loot:
      pool: [Z4_1, Z4_2, Z4_3, Z4_4, Z4_5, Z4_6, Z1_1, Z1_2]
```

| Key                             | Meaning                                                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `rarity`                        | Tooltip frame only. Cheap eggs Common, priciest Ancient.                                                        |
| `required-zone`                 | The zone that must be unlocked to buy or open the egg. **Applies to every Coin path.**                          |
| `display-name`                  | Language key.                                                                                                   |
| `currency-cost`                 | Coins per hatch. Priced at about 3% of the next zone's unlock price.                                            |
| `hatch-delay-seconds`           | Wait before the result when `quick-open: false`.                                                                |
| `multi-hatch`                   | Quantities offered in the quantity menu, for example `[1, 10, 100]`. A very expensive egg can offer only `[1]`. |
| `loot.pool`                     | Pet ids that can drop.                                                                                          |
| `material`, `custom-model-data` | Menu icon. Missing means a vanilla egg.                                                                         |
| `presentation`                  | Replaces the global presentation for this egg. See below.                                                       |

VIP ranks take `egg-hatch-discount-percent` (up to 8%) off the price.

### Global settings

| Key                                                  | Default  | Meaning                                                                                                                                                                                      |
| ---------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max-hatch-at-once`                                  | 250      | Safety cap for "hatch max".                                                                                                                                                                  |
| `block-hitbox.width`, `height`                       | 3.0, 3.0 | Invisible click area over a placed egg. Re-run `egg set-block` to apply a new size to existing eggs.                                                                                         |
| `block-hologram.*`                                   | on       | Floating text over each placed egg. `height`, `scale`, `lines` (MiniMessage or lang keys, `<egg>` and `<cost>` placeholders). Edits reach existing eggs within about 10 seconds of a reload. |
| `hatch-spin.*`                                       |          | The animation for a **single** hatch: `reel-length`, `deceleration-exponent`, delays, sounds, top-tier flourish. Bulk hatches skip it.                                                       |
| `presentation.message`                               | true     | The private chat line.                                                                                                                                                                       |
| `presentation.hologram`, `hologram-duration-seconds` | true, 3  | A floating name above the player.                                                                                                                                                            |
| `presentation.broadcast`                             | false    | Announce the hatch to the whole server.                                                                                                                                                      |
| `presentation.quick-open`                            | true     | `false` makes `hatch-delay-seconds` a real wait for suspense.                                                                                                                                |
| `presentation.per-player`                            | true     | `false` shows the hologram to everyone nearby.                                                                                                                                               |

A per-egg `presentation:` block replaces **all** the global fields at once, not just the ones it sets. Use it to make the rarest egg a public spectacle.

### Placing an egg in the world

Eggs are opened by **clicking a bound block** or from the menu. The block is usually dressed with an egg model from the resource pack, and ClickEm adds the floating text and the click area around it.

1. Look at the block.
2. Run `/ceadmin egg set-block <egg id>`.
3. Right-click the block: choose how many to open. Left-click: preview the loot pool.
4. `/ceadmin egg unset-block` removes it. `/ceadmin egg hitbox` shows the click area.

Bound blocks are saved in `plugins/ClickEmCore/data/egg-blocks.yml` as `World;x;y;z: egg id`. Back this file up with the world, and copy it when you move or clone a world.

### Where eggs come from

* Bought with Coins at an egg block or from `/egg`.
* Level-up reward: a random `zone_box_<n>` for the player's current zone (see [Profile Level](/lethium-docs/gameplay/profile-level.md)).
* Boss loot, daily rewards, quests, the Season Pass and crates.
* `/ceadmin egg give-item <player> <egg> [amount]`.

### Staff commands

| Command                                                   | Use                     |
| --------------------------------------------------------- | ----------------------- |
| `/ceadmin egg hatch <player> <egg> [count]`               | Open eggs for a player. |
| `/ceadmin egg force <player> <species>`                   | Force the next hatch.   |
| `/ceadmin egg give-item <player> <egg> [amount]`          | Give egg items.         |
| `/ceadmin egg set-block <egg>` / `unset-block` / `hitbox` | Bind, unbind and debug. |

### How to

* **Change an egg price:** edit `currency-cost`, reload with `/clickem module reload eggs`.
* **Change what an egg contains:** edit `loot.pool`.
* **Make an egg rarer to get:** raise `required-zone` or `currency-cost`.
* **Add an egg:** copy an entry, give it a new id, add `clickem.eggs.<id>.name` to `lang/en_us.yml` and its model to your resource pack if it has one.


---

# 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/gameplay/eggs.md?ask=<question>&goal=<user_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.