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

# Events

Server-wide timed bonus events: weekly schedule, random rotation, boss bar and manual start.

File: `plugins/ClickEmCore/modules/events.yml`. Module id: `events`. Commands: `/events`, `/event`.

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

* Stop an event: `/ceadmin events stop <event>`.
* Run one now: `/ceadmin events start <event> [minutes]`.
* Turn off surprise events: `rotation.enabled: false`.
* Change a day's bonus: its `bonus:` in `events.yml`.
  {% endhint %}

Events are **server-wide timed bonuses** applied equally to every player while active. Two kinds run on their own with no admin needed.

| Kind                 | How it starts                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| **Weekly scheduled** | `schedule-days` plus `start-hour` and `end-hour` (0 to 23, server time) start it automatically each week. |
| **Rotation pool**    | `schedule-days: []`. Picked at random by the `rotation:` section.                                         |

### The shipped events

| Event                                | When           | Bonus                               |
| ------------------------------------ | -------------- | ----------------------------------- |
| Weekend Boost                        | Sat and Sun    | +50% Coins                          |
| Movement Monday                      | Mon            | +25% movement speed                 |
| Toughness Tuesday                    | Tue            | +20% Defense, +20% Max HP           |
| Essence Wednesday                    | Wed            | +40% Essence                        |
| Thunder Thursday                     | Thu            | +20% Attack speed                   |
| Flash Event                          | rotation       | +25% Power, +10% Luck               |
| Crit Carnival                        | rotation       | +15% crit chance, +25% crit damage  |
| Essence Rush                         | rotation       | +75% Essence                        |
| Lucky Hour                           | rotation       | +30% Luck                           |
| Vitality Surge                       | rotation       | +30% HP regen, +15% Max HP          |
| Lifesteal Festival                   | rotation       | +8% Lifesteal                       |
| Boss Bounty                          | rotation       | +40% Boss Damage                    |
| Triple Threat                        | rotation       | +15% Coins, Power, Luck and Essence |
| Global Booster (`gems_global_boost`) | Gems Shop only | +20% Coins, +15% Power, +10% Luck   |

The Global Booster is **not in the rotation pool**. Only the [Gems Shop](/lethium-docs/gameplay/gems-shop.md) starts it, for the duration a buyer pays for.

### Rotation

```yaml
rotation:
  enabled: true
  interval-minutes: 45
  duration-minutes-min: 10
  duration-minutes-max: 20
  pool: [flash_event, crit_carnival, essence_rush, lucky_hour, vitality_surge,
         lifesteal_festival, boss_bounty, triple_threat]
```

Every `interval-minutes`, if no rotation event is active, one is picked at random and runs for a random time between the min and max, then stops. `enabled: false` means rotation events only run when started by hand.

### An event

```yaml
events:
  weekend_boost:
    rarity: MYTHICAL
    display-name: "clickem.events.weekend_boost.name"
    schedule-days: [SATURDAY, SUNDAY]
    start-hour: 0
    end-hour: 24
    bonus:
      currency-mult: 50.0
```

`bonus` uses the normal [stat keys](/lethium-docs/configuration/stats-and-limits.md). An event can also set `bossbar-color`.

### What players see (`announce:`)

| Section                                      | Keys                                                                                                                                                                                                                                                           |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                                      | `enabled`, `fade-in-ms`, `stay-ms`, `fade-out-ms`: an "Event started" title.                                                                                                                                                                                   |
| `bossbar`                                    | `enabled`, `color` (`BLUE`, `GREEN`, `PINK`, `PURPLE`, `RED`, `WHITE`, `YELLOW`), `overlay` (`PROGRESS`, `NOTCHED_6`, `NOTCHED_10`, `NOTCHED_12`, `NOTCHED_20`), `update-interval-ticks`. A bar drains as time runs out. Players joining mid-event get it too. |
| `bossbar.join-delay-ticks`, `reanchor-ticks` | For servers using BetterHud through a boss bar. The client stacks bars in the order received, so the event bar is delayed and re-sent so it always sits below the HUD's. `reanchor-ticks: 0` turns the re-send off.                                            |

Wording is in `lang/en_us.yml` under `clickem.events.title` and `clickem.events.bossbar`.

`schedule-check-interval-ticks` (1200) is how often schedule, rotation and expiry are checked.

### How to

* **Stop an event:** `/ceadmin events stop <event>`.
* **Run one now:** `/ceadmin events start <event> [minutes]`. A hand-started event is saved in the file under `state:` so it survives a restart. Do not edit `state:`.
* **Change a day's bonus:** edit its `bonus`.
* **Add a weekly event:** copy a block and set `schedule-days`.
* **Turn off surprise events:** `rotation.enabled: false`.

### Placeholders

There is no event placeholder. The boss bar is the on-screen signal. Active bonuses show up in `%clickem_stat_*%`.


---

# 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/events.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.