> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/codexmomentum/momentum/how-momentum-works.md).

# How Momentum Works

Momentum is a **streak**: as long as a player keeps performing their platform's activity, progress climbs a ladder of levels; the moment they stop for too long, it drains back down.

## Gaining momentum

Every counted action adds weighted progress:

| Platform    | What counts                                    | Weight used                                                    |
| ----------- | ---------------------------------------------- | -------------------------------------------------------------- |
| PinnaPrison | Blocks mined in private mines (`gain.sources`) | `gain.block-weights` per material (bulk sources use `default`) |
| EdPrison    | Blocks broken (delivered in batches)           | Always `gain.block-weights.default`                            |
| EdTools     | Gen blocks broken                              | `gain.block-weights` per material                              |
| EdDungeons  | Landed sword hits on dungeon mobs              | `gain.swing-weight`                                            |

When accumulated progress reaches the current level's `blocks` requirement the player **levels up**: boosters activate (PinnaPrison), the level's title/sound/particles fire, its console `commands` run and the chat line is sent. At the maximum level, extra progress keeps the buffer topped up.

## Grace period

After a player's last counted action, nothing happens for `grace-period` (default `10s`). Any new action during — or after — the grace period keeps or revives the streak instantly.

## Progressive decay

Once the grace period expires, momentum starts **draining**: `decay.blocks-per-second` of progress is lost every second (overridable per level). When the current level's progress hits zero the player **drops a level** — its boosters are removed, the level-down sound plays — and draining continues, level by level, until momentum reaches zero. The boss bar switches to its `decaying` style and shows the reason and drain rate while this happens.

## Loss triggers

| Trigger      | Default mode | Configurable                                                                                         |
| ------------ | ------------ | ---------------------------------------------------------------------------------------------------- |
| **Idle**     | `DECAY`      | No — going idle always drains progressively.                                                         |
| **Death**    | `RESET`      | `loss.death.mode` — `DECAY`, `RESET` or `NONE`                                                       |
| **Teleport** | `DECAY`      | `loss.teleport.mode`, plus `only-outside-mine` so teleports inside/into mines keep the streak alive. |
| **Logout**   | reset        | Governed by `save-momentum` (below), not by `loss`.                                                  |

{% hint style="info" %}
With `DECAY` mode the trigger does not start draining early — draining still only begins once the full grace period has passed. The trigger just tags the reason shown in the boss bar and in `lost-chat`.
{% endhint %}

## Persistence & records

By default (`save-momentum: false`) live momentum lives **only in RAM** — logging out or restarting the server resets it to zero. Set `save-momentum: true` to keep live momentum (level, progress, streak) across logouts and restarts; players rejoin with a fresh grace period so nobody comes back already draining.

Regardless of that setting, three **lifetime records** are always persisted per player, in an embedded H2 database at `plugins/CodexMomentum/data/`:

* **Best level** ever reached
* **Longest streak** duration
* **Most blocks** in a single streak

Records are saved asynchronously every `autosave` (default `5m`) and on quit/shutdown. They are shown in `/momentum stats` and exposed as [placeholders](/p/codexmomentum/reference/placeholders.md).