> 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/getting-started/main-configuration.md).

# Main Configuration

Everything lives in a single `config.yml`. Colors support standard `&` codes plus hex (`&#RRGGBB`). Durations accept `10m`, `90s`, `1h30m` or plain seconds.

The `bossbar`, `visuals` and `levels` sections have their own pages: [Boss Bar](/p/codexmomentum/momentum/bossbar.md), [Visual Effects](/p/codexmomentum/momentum/visuals.md), [Levels](/p/codexmomentum/momentum/levels.md).

***

### Platforms

**`platforms`**

* **Default:** all `true`
* **Description:** which installed host plugins feed momentum. Every supported plugin found at startup is hooked automatically; set one to `false` to ignore its events.

```yaml
platforms:
  pinnaprison: true   # blocks mined in private mines (manual + bulk sources)
  edprison: true      # blocks broken (delivered in batches)
  edtools: true       # gen blocks broken (block-weights apply)
  eddungeons: true    # sword hits on dungeon mobs
```

***

### Grace period & decay

**`grace-period`**

* **Default:** `10s`
* **Description:** how long a player may stop mining/hitting before momentum starts draining. On EdPrison, keep this above the host's `pickaxe.update-time-seconds` (see [EdPrison](/p/codexmomentum/platforms/edprison.md)).

**`decay.interval-ticks`**

* **Default:** `10`
* **Description:** how often (in ticks) the async decay ticker runs. Smaller = smoother drain.

**`decay.blocks-per-second`**

* **Default:** `4.0`
* **Description:** blocks of progress lost per second while draining. When the current level's progress is empty the player drops a level and keeps draining. Can be overridden per level with `decay-blocks-per-second`.

***

### Gain

**`gain.sources`**

* **Default:** `[MANUAL]`
* **Description:** PinnaPrison only — which mining sources count towards momentum. `MANUAL` is raw blocks mined by hand (the intended metric).
* **Options:** `MANUAL`, `ENCHANT`, `BOMB`, `DRILL`, `AUTOMINER`, `OTHER` (bulk sources use the `default` block weight).

**`gain.block-weights`**

* **Default:** `default: 1.0`
* **Description:** progress granted per block, per material. Applies to PinnaPrison manual mining and EdTools gen breaks; anything not listed uses `default`; EdPrison batches always use `default`. Example: `DIAMOND_ORE: 2.0` makes rare ores push momentum harder.

**`gain.swing-weight`**

* **Default:** `1.0`
* **Description:** EdDungeons only — progress granted per landed sword hit. Hits land far slower than mined blocks, so raise this to keep level requirements reachable.

***

### Persistence

**`save-momentum`**

* **Default:** `false`
* **Description:** by default live momentum lives only in RAM — logging out, rejoining or a restart resets it to zero, and only lifetime records plus the `/momentum toggle` preference hit the disk. Set to `true` to also keep live momentum (level, progress, streak) across logouts and restarts; it is restored on join with a fresh grace period, so nobody comes back already draining.

**`autosave`**

* **Default:** `5m`
* **Description:** duration between automatic async saves of records. `0` disables autosave.

***

### Loss triggers

**`loss.death.mode`** / **`loss.teleport.mode`**

* **Default:** `RESET` (death), `DECAY` (teleport)
* **Options:**
  * `DECAY` — progressive loss; draining still only begins once the player has stopped mining for the full grace period (the trigger just tags the reason shown in the boss bar).
  * `RESET` — momentum zeroes out instantly.
  * `NONE` — trigger ignored.

**`loss.teleport.only-outside-mine`**

* **Default:** `true`
* **Description:** only trigger when the teleport lands **outside** every mine — teleports inside/into mines (including visits) keep the streak alive. (PinnaPrison mine detection.)

{% hint style="info" %}
Logout is not configurable here: quitting saves or resets momentum depending on `save-momentum`. Going idle always uses progressive decay.
{% endhint %}

***

### Boosters

**`boosters.stack-levels`**

* **Default:** `false`
* **Description:** `false` — only the current level's boosters apply (each level should list its full loadout). `true` — levels inherit and **add up** all previous levels' boosters. See [Boosters](/p/codexmomentum/momentum/boosters.md).

***

### Formatting

**`time-format`**

* **Default:** `with-hours: '{h}h {m}m {s}s'`, `with-minutes: '{m}m {s}s'`, `seconds-only: '{s}s'`
* **Description:** how streak durations are rendered in the boss bar, stats and placeholders.

**`number-format.grouping`**

* **Default:** `true`
* **Description:** fallback number rendering (thousands grouping) used when PinnaPrison's format API isn't available.

**`placeholders.no-multiplier`**

* **Default:** `'&8—'`
* **Description:** what `{multiplier}` / `%codexmomentum_multiplier%` shows when the level has no `multiplier-display` set.

**`placeholders.decaying-true`** / **`placeholders.decaying-false`**

* **Default:** `'&#FF6B6Btrue'` / `'&#71E893false'`
* **Description:** styled values for `%codexmomentum_decaying%`.