# Powerups

URL: https://greenarrowlol.github.io/TNTGamesCore/docs/features/powerups/
Section: features
Description: Floating pickups that spawn at random during TNT Run and TNT Tag.

---

> For a complete page index, fetch https://greenarrowlol.github.io/TNTGamesCore/llms.txt.

Floating pickups that appear around the arena while a game runs. A player grabs one by walking into it.

## How it works

1. You save **spots** in an arena with one command. A spot is just a position, not a powerup type.
2. While a game runs, every spot rolls on its own timer.
3. When a roll succeeds, a random powerup appears there. Which one is decided by the **chance** values in `powerups.yml`.
4. A player walks into it, gets the effect, and the spot starts rolling again.

Powerups float in place with their name above them. Untouched ones vanish after a while so the arena does not fill up.

## Saving spots

Stand where a powerup should appear and run:

```
/tt addpowerup <arena>
```

Repeat for as many spots as you like. To manage them:

```
/tt powerups <arena>      List the spots
/tt delpowerup <arena>    Remove the spot closest to you (within 10 blocks)
```

`/tt setupstatus <arena>` also shows how many spots an arena has. Spots are optional, an arena with none simply has no powerups.

:::{tip}
In TNT Run, place spots a little above the floor along the paths players run. The floor breaks under them but the powerup keeps floating.
:::

## Spawn timing

The `settings` block at the top of `powerups.yml` controls when powerups appear.

| Setting | What it controls | Default |
| --- | --- | --- |
| `enabled` | Turn powerups on or off everywhere. | `true` |
| `first-spawn-delay` | Seconds after the game starts before the first roll. | `5` |
| `spawn-interval` | Seconds between rolls at an empty spot. | `15` |
| `spawn-chance` | Percent chance (0 to 100) that a roll spawns something. | `60` |
| `lifetime` | Seconds an untouched powerup stays. `0` keeps it forever. | `20` |

## Powerup chances

Each powerup has a `chance`. It is a relative weight: a powerup with `chance: 30` shows up three times as often as one with `chance: 10`. If all enabled chances in a game add up to 100, you can read them as percentages. Set `chance: 0` or `enabled: false` to remove one.

Only powerups whose `games` list includes the current game can roll there.

## Built-in powerups

| Powerup | Games | Effect | Chance |
| --- | --- | --- | --- |
| `speed` | TNT Run, TNT Tag | Speed II for 6 seconds. | 35 |
| `leap` | TNT Run, TNT Tag | Jump Boost III for 6 seconds. | 25 |
| `feather` | TNT Run | 2 extra double jumps for the rest of the game. | 15 |
| `slow-fall` | TNT Run | Slow Falling for 5 seconds. | 10 |
| `blind-others` | TNT Run, TNT Tag | Blinds every other player for 3 seconds. | 8 |
| `slow-others` | TNT Run, TNT Tag | Slowness II on every other player for 3 seconds. | 7 |
| `invisibility` | TNT Tag | Invisible for 6 seconds. | 10 |

## Making your own

Add a new key under `powerups`:

```yaml
powerups:
  rocket:
    enabled: true
    chance: 5
    games: [TNT_RUN]
    material: FIREWORK_ROCKET
    name: '&c&lRocket'
    sound: ENTITY_FIREWORK_ROCKET_LAUNCH
    self:
      - 'LEVITATION:3:1'
    double-jumps: 1
    commands:
      - 'say {player} took off!'
```

| Field | Meaning |
| --- | --- |
| `chance` | Relative weight, see above. |
| `games` | `TNT_RUN`, `TNT_TAG`, `BOW_SPLEEF`. |
| `material` | The floating item. |
| `name` | Name tag above it. Color codes and `&#RRGGBB` work. |
| `sound` | Sound played on pickup. Optional. |
| `self` | Effects on the picker, as `TYPE:LEVEL:SECONDS`. Level 1 is the base effect. |
| `others` | Effects on every other alive player in the game, same format. |
| `double-jumps` | Extra double jumps for the rest of that game. |
| `commands` | Console commands run on pickup. `{player}` is the picker. |

Run `/tt reload` after editing.

## Related

- [Shop and cosmetics](/docs/features/shop/): bought double jumps and trails.
- [Commands](/docs/reference/commands/)