> For the complete documentation index, see [llms.txt](https://docs-nightbeam.gitbook.io/infinity-rifts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-nightbeam.gitbook.io/infinity-rifts/docs/gateway_configuration.md).

# Gateway configuration

Every `*.yml` directly inside `plugins/InfinityRifts/gateways/` is loaded independently through Configurate. The map key is the file's configured `id`, not its filename. Duplicate IDs overwrite earlier entries in unspecified file iteration order.

The packaged presets are [`fire_gate.yml`](https://github.com/MeherBenSalem/InfinityRifts/tree/main/src/main/resources/gateways/fire_gate.yml), [`ice_gate.yml`](https://github.com/MeherBenSalem/InfinityRifts/tree/main/src/main/resources/gateways/ice_gate.yml), and [`void_gate.yml`](https://github.com/MeherBenSalem/InfinityRifts/tree/main/src/main/resources/gateways/void_gate.yml). Those files are the complete, annotated examples shipped to servers; this page defines every model path and the behavior behind it.

## Complete schema and defaults

Paths containing `<wave>`, `<mob>`, `<reward>`, `<world>`, or `<slot>` are repeatable map/list entries.

| Path                                                      | Type · model default                  | Rules and behavior                                                                                                                                    |
| --------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                                      | string · `default_gateway`            | Unique lookup ID used by commands/PDC                                                                                                                 |
| `display-name`                                            | MiniMessage · `<gold>Default Gateway` | UI, messages, hologram text                                                                                                                           |
| `description`                                             | string · `A mysterious gateway...`    | Admin GUI lore                                                                                                                                        |
| `item.material`                                           | material · `NETHER_STAR`              | Invalid key material falls back to `NETHER_STAR`                                                                                                      |
| `item.name`                                               | MiniMessage · `<gold>Gateway Key`     | Key display name                                                                                                                                      |
| `item.lore`                                               | string list · `[]`                    | MiniMessage lines; command adds generated details                                                                                                     |
| `item.custom-model-data`                                  | integer · `0`                         | Applied when greater than zero                                                                                                                        |
| `item.glint`                                              | boolean · `true`                      | Adds hidden durability enchant                                                                                                                        |
| `settings.max-time-seconds`                               | integer · `300`                       | Validator warns below 30; gateway-wide deadline                                                                                                       |
| `settings.spawn-radius`                                   | integer · `8`                         | Validator warns below 1                                                                                                                               |
| `settings.allow-multiple-players`                         | boolean · `false`                     | Parsed but current party/session path does not consult it                                                                                             |
| `settings.max-players`                                    | integer · `4`                         | Enforced when parties join/start; validator warns below 1                                                                                             |
| `settings.cost`                                           | decimal · `0.0`                       | Parsed but unused; no economy withdrawal exists                                                                                                       |
| `bossbar.gateway.title`                                   | MiniMessage                           | Supports `<name>`, `<time>`                                                                                                                           |
| `bossbar.gateway.color`                                   | string · `WHITE` entry default        | Adventure color; invalid becomes white                                                                                                                |
| `bossbar.gateway.style`                                   | string · `SOLID` entry default        | Solid or segmented overlay; invalid becomes solid/progress                                                                                            |
| `bossbar.wave.title`                                      | MiniMessage                           | Supports `<wave>`, `<max>`, `<wave-time>`, `<mobs>`                                                                                                   |
| `bossbar.wave.color/style`                                | strings                               | Same rules                                                                                                                                            |
| `highlighting.enabled`                                    | boolean · `true`                      | Per-gateway highlighting gate                                                                                                                         |
| `highlighting.glow-color`                                 | ChatColor · `GOLD`                    | Invalid becomes white                                                                                                                                 |
| `highlighting.particles.enabled`                          | boolean · `true`                      | Per-gateway particle gate                                                                                                                             |
| `highlighting.particles.type`                             | Particle · `FLAME`                    | Runtime fallbacks exist for incompatible data particles                                                                                               |
| `highlighting.particles.count`                            | integer · `5`                         | No configured bound                                                                                                                                   |
| `waves.<wave>.time-limit`                                 | seconds · `60`                        | Must be >0 to avoid validator warning/failure behavior                                                                                                |
| `waves.<wave>.spawn-delay`                                | seconds · `0`                         | Multiplied by 20 ticks; must be nonnegative                                                                                                           |
| `waves.<wave>.rewards[]`                                  | object list · `[]`                    | Per-wave `type`, `amount`, `value`                                                                                                                    |
| `waves.<wave>.rewards[].type`                             | string · `XP`                         | Primary `GatewayInstance` processes only `XP`; the legacy `RiftInstance`/`RewardProcessor` also handles `ITEM` and `COMMAND`. Other types are ignored |
| `waves.<wave>.rewards[].amount`                           | integer · `50`                        | XP/item amount                                                                                                                                        |
| `waves.<wave>.rewards[].value`                            | string · empty                        | Material for ITEM; console command for COMMAND                                                                                                        |
| `waves.<wave>.mobs[]`                                     | object list                           | At least one valid mob is needed                                                                                                                      |
| `waves.<wave>.mobs[].type`                                | string · `ZOMBIE`                     | Bukkit entity, `minecraft:TYPE`, or `mythic:InternalName`                                                                                             |
| `waves.<wave>.mobs[].amount`                              | integer · `1`                         | Must be >0                                                                                                                                            |
| `waves.<wave>.mobs[].name`                                | MiniMessage · empty                   | Optional custom name                                                                                                                                  |
| `waves.<wave>.mobs[].health`                              | decimal · `20.0`                      | Must be >0; scaled by participants                                                                                                                    |
| `waves.<wave>.mobs[].damage`                              | decimal · `5.0`                       | Must be nonnegative; stored in PDC                                                                                                                    |
| `waves.<wave>.mobs[].boss`                                | boolean · `false`                     | Alive boss can prevent collapse when configured                                                                                                       |
| `waves.<wave>.mobs[].mythic-type`                         | string · empty                        | Legacy alternative MythicMobs selector                                                                                                                |
| `waves.<wave>.mobs[].mythic-level`                        | decimal · `1.0`                       | MythicMobs spawn level                                                                                                                                |
| `waves.<wave>.mobs[].equipment.<slot>`                    | material · empty                      | Slots: `hand`, `off-hand`, `helmet`, `chestplate`, `leggings`, `boots`                                                                                |
| `waves.<wave>.mobs[].equipment.<slot>-enchants.<enchant>` | integer map · `{}`                    | Bukkit enchant key/name to level; invalid entries log/skip                                                                                            |
| `waves.<wave>.mobs[].potion-effects[]`                    | objects · `[]`                        | `type`, `duration` ticks (default 9999), `amplifier` (default 0)                                                                                      |
| `waves.<wave>.mobs[].attributes.speed`                    | decimal · `-1`                        | Negative means unchanged                                                                                                                              |
| `...attributes.attack-speed`                              | decimal · `-1`                        | Negative means unchanged                                                                                                                              |
| `...attributes.knockback-resistance`                      | decimal · `-1`                        | Negative means unchanged                                                                                                                              |
| `...attributes.armor`                                     | decimal · `-1`                        | Negative means unchanged                                                                                                                              |
| `rewards.items[]`                                         | objects · `[]`                        | Final material items                                                                                                                                  |
| `rewards.items[].material`                                | material · `DIAMOND`                  | Invalid item logs and is skipped                                                                                                                      |
| `rewards.items[].amount`                                  | integer · `1`                         | Stack amount                                                                                                                                          |
| `rewards.items[].name`                                    | MiniMessage · empty                   | Optional                                                                                                                                              |
| `rewards.items[].lore`                                    | MiniMessage list · `[]`               | Optional                                                                                                                                              |
| `rewards.items[].custom-model-data`                       | integer · `0`                         | Applied above zero                                                                                                                                    |
| `rewards.commands`                                        | string list · `[]`                    | Console commands; `%player%`, `%uuid%`                                                                                                                |
| `rewards.xp`                                              | integer · `0`                         | Direct experience points                                                                                                                              |
| `rewards.money`                                           | decimal · `0.0`                       | Parsed but unused; Vault is not wired                                                                                                                 |
| `rewards.broadcast`                                       | MiniMessage · empty                   | Broadcast when nonempty; `%player%`                                                                                                                   |
| `failure.message`                                         | MiniMessage                           | Sent on failure                                                                                                                                       |
| `failure.commands`                                        | string list · `[]`                    | Console commands; `%player%` replaced                                                                                                                 |
| `failure.remove-mobs`                                     | boolean · `true`                      | Cleanup behavior                                                                                                                                      |
| `failure.boss-prevents-collapse`                          | boolean · `true`                      | Keeps session alive past time expiry while a boss lives                                                                                               |
| `random-gates.ownership-mode`                             | string · `NONE`                       | `NONE` is competitive/ownerless behavior; other values act as owned (comment names `FIRST_HIT`)                                                       |
| `random-gates.allow-pvp`                                  | boolean · `true`                      | PvP rule for competitive gateway participants                                                                                                         |
| `random-gates.drops.ground-drop`                          | boolean · `true`                      | Respawn mob drops as tracked ground items                                                                                                             |
| `random-gates.drops.stack`                                | boolean · `true`                      | Parsed in drop branch; normal Bukkit stacking remains                                                                                                 |
| `random-gates.drops.merge-radius`                         | decimal · `2.0`                       | Parsed but unused                                                                                                                                     |
| `random-gates.hologram.remove-on-end`                     | boolean · `true`                      | Remove the random-rift armor-stand hologram                                                                                                           |

### Random spawning

| Path under `random-spawn`                 | Type · default                  | Rules                                                                                                         |
| ----------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `enabled`                                 | boolean · `false`               | Enables scheduled checks                                                                                      |
| `timing.check-interval`                   | seconds · `600`                 | Validator range guidance 10–3600; scheduler clamps to at least 10                                             |
| `timing.spawn-chance`                     | percent · `25.0`                | Runtime clamps to 0–100                                                                                       |
| `timing.max-active`                       | integer · `3`                   | Validator guidance 1–50                                                                                       |
| `timing.lifetime`                         | seconds · `900`                 | `-1` disables lifetime; validator guidance otherwise 60–7200                                                  |
| `player-scaling.enabled`                  | boolean · `true`                | Adds chance for online players above base                                                                     |
| `player-scaling.base-player-count`        | integer · `5`                   | Base online count                                                                                             |
| `player-scaling.extra-chance-per-player`  | decimal · `1.5`                 | Added percentage points                                                                                       |
| `player-scaling.max-chance`               | percent · `60.0`                | Scaling cap                                                                                                   |
| `worlds.default.enabled`                  | boolean · `true`                | Default world policy                                                                                          |
| `worlds.default.spawn-chance-modifier`    | decimal · `1.0`                 | Multiplier                                                                                                    |
| `worlds.default.max-active`               | integer · `2`                   | Per-world cap                                                                                                 |
| `worlds.overrides.<world>.*`              | same object                     | Exact Bukkit world name; unknown loaded-late worlds warn                                                      |
| `restrictions.min-distance-from-spawn`    | blocks · `500`                  | Candidate rejection radius                                                                                    |
| `restrictions.min-distance-between-rifts` | blocks · `800`                  | Candidate rejection radius                                                                                    |
| `restrictions.height.min/max`             | integers · `50/120`             | Min above max prevents spawning                                                                               |
| `restrictions.blocked-blocks`             | material list · `[]`            | Reject ground/top blocks                                                                                      |
| `restrictions.require-loaded-chunks`      | boolean · `true`                | Avoid unloaded chunks                                                                                         |
| `restrictions.min-clear-radius`           | blocks · `3`                    | Local clearance scan                                                                                          |
| `biomes.enabled`                          | boolean · `false`               | Enables biome filter                                                                                          |
| `biomes.filter-mode`                      | string · `BLACKLIST`            | Only exact `WHITELIST` selects whitelist semantics                                                            |
| `biomes.list`                             | biome-name list · `[]`          | Case-insensitive names                                                                                        |
| `despawn.idle-timeout`                    | seconds · `300`                 | Inactivity threshold                                                                                          |
| `despawn.player-proximity-radius`         | blocks · `100`                  | Nearby player detection                                                                                       |
| `announcements.mode`                      | string · `GLOBAL`               | `DISABLED`, `SUBTLE`, `GLOBAL`; an unknown value matches no send branch                                       |
| `announcements.subtle-radius`             | blocks · `200`                  | Audience radius for subtle mode                                                                               |
| `announcements.messages.spawn/despawn`    | MiniMessage string lists · `[]` | `{x}`, `{y}`, `{z}`, `{world}`, `{type}`, `{time}`; packaged `&` codes are not translated by `MessageService` |
| `debug.enabled`                           | boolean · `false`               | Random-spawn debug master                                                                                     |
| `debug.log-spawn-attempts`                | boolean · `true`                | Attempt logs                                                                                                  |
| `debug.log-failed-locations`              | boolean · `true`                | Candidate failure logs                                                                                        |

### Activation conditions

All paths below are under `spawn-conditions`. Admin starts pass `isAdmin=true`; gateway-key activation passes false. A player with the configured bypass node also bypasses conditions.

| Path                                     | Default                           | Notes                                                             |
| ---------------------------------------- | --------------------------------- | ----------------------------------------------------------------- |
| `enabled`                                | `true`                            | Master switch                                                     |
| `bypass-permission`                      | `infinityrifts.bypass.conditions` | Dynamic permission string                                         |
| `worlds.enabled/filter-mode/list`        | `true` / `BLACKLIST` / `[]`       | Exact world names, case-insensitive                               |
| `biomes.enabled/filter-mode/list`        | `false` / `BLACKLIST` / `[]`      | Biome names                                                       |
| `location.min-distance-from-spawn`       | `0`                               | Blocks                                                            |
| `location.min-distance-from-other-rifts` | `50`                              | Checks active random rifts                                        |
| `location.height.enabled/min/max`        | `false` / `0` / `320`             | Y range                                                           |
| `location.blocked-blocks`                | `[]`                              | Materials                                                         |
| `location.require-sky-access`            | `false`                           | Highest-block visibility test                                     |
| `location.require-solid-ground`          | `true`                            | Block below must be solid                                         |
| `time.enabled/allowed-times`             | `false` / `[]`                    | `DAY`, `NIGHT`, `DAWN`, `DUSK`                                    |
| `weather.enabled/allowed-weather`        | `false` / `[]`                    | `CLEAR`, `RAIN`, `THUNDER`                                        |
| `player.min-level`                       | `0`                               | Experience level                                                  |
| `player.required-permissions`            | `[]`                              | All nodes required                                                |
| `player.blocked-gamemodes`               | `[]`                              | Bukkit game-mode names                                            |
| `player.cooldown-seconds`                | `0`                               | Per-player, per-gateway in-memory cooldown                        |
| `messages.*-denied`                      | model strings                     | See [messages](/infinity-rifts/docs/messages-and-localization.md) |

## Important preset inconsistency

The shipped `fire_gate.yml` places `random-gates` beneath `random-spawn`, but the Java model maps it at the gateway root. Consequently that nested block is ignored and the root model defaults are used. Put it beside `random-spawn`, not inside it:

```yaml
random-spawn:
  enabled: true
  # timing, worlds, restrictions, etc.

random-gates:
  ownership-mode: NONE
  allow-pvp: true
  drops:
    ground-drop: true
    stack: true
    merge-radius: 2.0
  hologram:
    remove-on-end: true
```

## Minimal complete example

```yaml
id: custom_gate
display-name: "<aqua>Custom Gateway"
description: "A small test gateway"
item: { material: NETHER_STAR, name: "<aqua>Gateway Key", lore: [], custom-model-data: 0, glint: true }
settings: { max-time-seconds: 180, spawn-radius: 8, allow-multiple-players: false, max-players: 4, cost: 0.0 }
bossbar:
  gateway: { title: "<aqua><name> - <time>", color: BLUE, style: SEGMENTED_10 }
  wave: { title: "<yellow>Wave <wave>/<max> - <wave-time> - <mobs>", color: YELLOW, style: SOLID }
highlighting: { enabled: true, glow-color: AQUA, particles: { enabled: true, type: FLAME, count: 3 } }
waves:
  1:
    time-limit: 60
    spawn-delay: 0
    mobs:
      - { type: ZOMBIE, amount: 2, name: "<green>Rift Zombie", health: 20.0, damage: 5.0, boss: false }
    rewards:
      - { type: XP, amount: 10, value: "" }
rewards: { items: [], commands: [], xp: 25, money: 0.0, broadcast: "" }
failure: { message: "<red>The gateway collapsed.", commands: [], remove-mobs: true, boss-prevents-collapse: true }
random-spawn: { enabled: false }
spawn-conditions: { enabled: true, bypass-permission: infinityrifts.bypass.conditions }
random-gates:
  ownership-mode: NONE
  allow-pvp: true
  drops: { ground-drop: true, stack: true, merge-radius: 2.0 }
  hologram: { remove-on-end: true }
```

Unknown or misspelled keys may be ignored by object mapping. Back up files, reload, and inspect validator messages after every schema change.