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

# Invader System

````
# Invader System

The **Invader System** is an expanded server-wide world-boss system designed for high-performance, dynamic events with deep admin customization.

Invaders are more than normal bosses. They can summon minions, change phases, corrupt the world, trigger server-wide panic, and apply punishments or blessings depending on whether players successfully defend the server.

---

# Feature Overview

| Feature | Description |
|---|---|
| **Dynamic Reinforcements** | Invaders can summon minions at specific HP thresholds. |
| **Environmental Hazards** | Bosses can emit area-of-effect pulses that debuff nearby players. |
| **Multi-Phase Battles** | Invaders can change form, palette, moves, and stats mid-fight. |
| **Defense Pylons** | Bosses can spawn protective crystals that reduce incoming damage. |
| **World Hunger / Panic** | A global Heat system that rises on failure and falls on success. |
| **Invasion Events** | Scheduled server events with boosted spawns and world modifiers. |
| **Persistent Leaderboard** | Tracks lifetime player damage against Invaders. |
| **Punishments & Blessings** | Server-wide consequences or rewards based on Invader outcomes. |
| **Optimized Performance** | Uses throttled checks and integrated boss logic to reduce server lag. |

{% hint style="info" %}
The Invader System is meant to create large-scale server moments where the entire community is encouraged to participate.
{% endhint %}

---

# Dynamic Reinforcements

**Dynamic Reinforcements**, also called **Minions**, allow Invaders to summon support Pokémon during battle.

These minions can distract players, apply pressure, and make the fight feel more chaotic and dangerous.

---

## How Minions Work

Minions are configured inside the `minions` section of an Invader JSON file.

Each minion wave can trigger when the boss reaches a specific HP percentage.

| Option | Description |
|---|---|
| `hpThresholdPercent` | The boss HP percentage that triggers the minion wave. |
| `species` | The Pokémon species summoned as minions. |
| `count` | Number of minions spawned. |
| `level` | Level of the summoned minions. |
| `statsMultiplier` | Multiplier applied to the minions' stats. |
| `palette` | Optional custom palette for the minions. |
| `form` | Optional custom form for the minions. |

---

## Minion Behavior

| Behavior | Description |
|---|---|
| Auto Spawn | Minions spawn automatically when the boss reaches the configured HP threshold. |
| Auto Cleanup | Minions despawn when the boss is defeated or despawns. |
| Stat Scaling | Minions can be made stronger using `statsMultiplier`. |
| Custom Identity | Minions can use custom species, levels, palettes, and forms. |

{% hint style="warning" %}
Minions are automatically cleaned up after the Invader fight ends to prevent leftover mobs from cluttering the world.
{% endhint %}

---

## Example Minion Config

```json
"minions": [
  {
    "hpThresholdPercent": 50,
    "species": "Zubat",
    "count": 5,
    "level": 75,
    "statsMultiplier": 2.0
  }
]
````

### Example Breakdown

| Setting              | Value   | Result                                         |
| -------------------- | ------- | ---------------------------------------------- |
| `hpThresholdPercent` | `50`    | Minions spawn when the Invader reaches 50% HP. |
| `species`            | `Zubat` | Zubat minions are summoned.                    |
| `count`              | `5`     | Five minions spawn.                            |
| `level`              | `75`    | Each minion is level 75.                       |
| `statsMultiplier`    | `2.0`   | Minion stats are doubled.                      |

***

## Environmental Hazards

**Environmental Hazards** make standing near an Invader dangerous.

Hazards pulse at configurable intervals and affect players within a certain radius.

***

### Hazard Options

| Option            | Description                               |
| ----------------- | ----------------------------------------- |
| `type`            | The hazard type.                          |
| `intervalSeconds` | How often the hazard pulses.              |
| `radius`          | How far the hazard reaches from the boss. |

***

### Hazard Types

| Hazard          | Effect                                                      |
| --------------- | ----------------------------------------------------------- |
| `GRAVITY_WELL`  | Slows players and prevents jumping or flying near the boss. |
| `ABYSSAL_PULSE` | Applies a harmful status effect to players within range.    |

***

### Gravity Well

`GRAVITY_WELL` is designed to keep players grounded and make movement around the Invader more difficult.

It can apply effects such as:

* Slowness
* Jump prevention
* Flying disruption
* Reduced mobility near the boss

```
"hazards": [
  {
    "type": "GRAVITY_WELL",
    "intervalSeconds": 30,
    "radius": 50.0
  }
]
```

***

### Abyssal Pulse

`ABYSSAL_PULSE` sends out a damaging or debuffing pulse to nearby players.

This can be used for dark, poison, shadow, or corruption-themed Invaders.

```
"hazards": [
  {
    "type": "ABYSSAL_PULSE",
    "intervalSeconds": 45,
    "radius": 40.0
  }
]
```

{% hint style="danger" %}\
Hazards are best used carefully. Very short intervals or very large radiuses can make fights overwhelming for players.\
{% endhint %}

***

## Multi-Phase Battles

**Multi-Phase Battles** allow a single Invader to transform during combat.

A phase can change the boss visually, mechanically, or both.

***

### Phase Options

| Option               | Description                                  |
| -------------------- | -------------------------------------------- |
| `hpThresholdPercent` | HP percentage where the phase activates.     |
| `newForm`            | Changes the boss's form.                     |
| `newPalette`         | Changes the boss's palette or texture style. |
| `newMoves`           | Replaces or updates the boss's moveset.      |
| `statMultiplier`     | Buffs the boss's stats during the phase.     |
| `announcement`       | Message broadcast when the phase activates.  |

***

### Example Phase Config

```
"phases": [
  {
    "hpThresholdPercent": 50,
    "newForm": "Mega",
    "newPalette": "shadow",
    "newMoves": [
      "Dragon Ascent",
      "V-create",
      "Draco Meteor",
      "Dragon Dance"
    ],
    "statMultiplier": 1.5,
    "announcement": "&cPhase 2!"
  }
]
```

### Example Breakdown

| Setting              | Value        | Result                              |
| -------------------- | ------------ | ----------------------------------- |
| `hpThresholdPercent` | `50`         | Phase activates at 50% HP.          |
| `newForm`            | `Mega`       | Boss changes into its Mega form.    |
| `newPalette`         | `shadow`     | Boss changes to a shadow palette.   |
| `newMoves`           | 4 moves      | Boss receives a new moveset.        |
| `statMultiplier`     | `1.5`        | Boss stats increase by 50%.         |
| `announcement`       | `&cPhase 2!` | Message is broadcast to the server. |

{% hint style="info" %}\
Phases are useful for making one boss feel like multiple fights in a single encounter.\
{% endhint %}

***

## Interactive Defense Pylons

**Defense Pylons** add a tactical objective to Invader fights.

Instead of only attacking the boss, players may need to destroy protective structures first.

***

### How Pylons Work

Pylons are usually represented by **End Crystals**.

While pylons are alive, the Invader receives damage reduction.

| Option                    | Description                                     |
| ------------------------- | ----------------------------------------------- |
| `enabled`                 | Whether pylons are active for this Invader.     |
| `count`                   | Number of pylons spawned around the boss.       |
| `spawnRadius`             | Distance from the boss where pylons spawn.      |
| `damageReductionPerPylon` | Damage reduction provided by each active pylon. |

***

### Example Pylon Config

```
"pylons": {
  "enabled": true,
  "count": 3,
  "spawnRadius": 20.0,
  "damageReductionPerPylon": 0.3
}
```

### Example Breakdown

| Setting                   | Value  | Result                                           |
| ------------------------- | ------ | ------------------------------------------------ |
| `enabled`                 | `true` | Pylons are active.                               |
| `count`                   | `3`    | Three pylons spawn.                              |
| `spawnRadius`             | `20.0` | Pylons spawn around the boss within this radius. |
| `damageReductionPerPylon` | `0.3`  | Each pylon reduces damage by 30%.                |

***

### Damage Reduction Example

If an Invader has `3` pylons and each pylon gives `0.3` damage reduction:

| Active Pylons | Damage Reduction |
| ------------- | ---------------- |
| `3`           | `90%`            |
| `2`           | `60%`            |
| `1`           | `30%`            |
| `0`           | `0%`             |

{% hint style="warning" %}\
Players should destroy pylons quickly. Leaving them active can make the boss nearly impossible to damage.\
{% endhint %}

***

## Panic System

The **Panic System**, also called **Global Heat** or **World Hunger**, tracks how dangerous the server has become.

When the community fails to defeat Invaders, Heat rises.

When the community successfully defeats Invaders, Heat falls.

***

### Heat Values

Heat ranges from `0` to `100`.

| Heat Level | Meaning                                                          |
| ---------- | ---------------------------------------------------------------- |
| `0`        | Server is stable.                                                |
| `25`       | Invader activity is increasing.                                  |
| `50`       | The world is becoming dangerous.                                 |
| `75`       | The server is in panic.                                          |
| `100`      | Maximum danger. Invaders are heavily empowered or more frequent. |

***

### Panic Options

| Option                  | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `heatIncreaseOnFailure` | How much Heat increases when an Invader despawns undefeated. |
| `heatDecreaseOnSuccess` | How much Heat decreases when an Invader is defeated.         |

***

### Example Panic Config

```
"panic": {
  "heatIncreaseOnFailure": 20,
  "heatDecreaseOnSuccess": 10
}
```

### Example Breakdown

| Result                      | Heat Change |
| --------------------------- | ----------- |
| Invader despawns undefeated | `+20` Heat  |
| Invader is defeated         | `-10` Heat  |

{% hint style="danger" %}\
At high Heat levels, future Invaders can become more common, making repeated failures increasingly dangerous for the server.\
{% endhint %}

***

## Invasion Events

**Invasion Events** are scheduled server-wide events that modify Invader behavior for a limited time.

They can be used for special boss weeks, seasonal events, server disasters, or admin-run story events.

***

### Event Config Location

Invasion Event JSON files are stored in:

```
config/titans/invasion_events/
```

***

### Event Features

| Feature           | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| Time Windows      | Events can start and end using timestamp values.           |
| Weather Lock      | Events can force server-wide weather.                      |
| Spawn Boosts      | Events can increase the spawn chance of specific Invaders. |
| Targeted Invaders | Events can affect one Invader or multiple Invaders.        |

***

### Common Event Options

| Option                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `name`                  | Display name of the event.                     |
| `enabled`               | Whether the event can run.                     |
| `startTimeMillis`       | Timestamp for when the event starts.           |
| `endTimeMillis`         | Timestamp for when the event ends.             |
| `targetInvaders`        | Invader IDs affected by the event.             |
| `spawnChanceMultiplier` | Spawn chance multiplier for targeted Invaders. |
| `globalWeatherLock`     | Weather forced during the event.               |
| `announcementMessage`   | Message broadcast when the event activates.    |

***

### Example Event Config

```
{
  "name": "The Deep Sea Week",
  "enabled": true,
  "startTimeMillis": 1714176000000,
  "endTimeMillis": 1714780800000,
  "targetInvaders": [
    "kyogre"
  ],
  "spawnChanceMultiplier": 5.0,
  "globalWeatherLock": "RAIN",
  "announcementMessage": "&b[EVENT] The oceans rise! Kyogre sightings have drastically increased."
}
```

***

## Persistent Leaderboard

The **Persistent Leaderboard** tracks lifetime player damage against Invaders.

This gives players a reason to participate in every defense event, even if they do not get the final hit.

***

### Leaderboard Details

| Feature        | Description                                                |
| -------------- | ---------------------------------------------------------- |
| Data Storage   | Saved in `invader_leaderboard.json`.                       |
| Tracked Stat   | Lifetime damage dealt to Invaders.                         |
| Player Command | `/titans invaders top`                                     |
| Purpose        | Encourages long-term competition and server participation. |

***

## New Invader Commands

| Command                            | Permission     | Description                                                    |
| ---------------------------------- | -------------- | -------------------------------------------------------------- |
| `/titans invaders top`             | `titans.use`   | View the persistent damage leaderboard.                        |
| `/titans invaders active`          | `titans.use`   | View current active world punishments and blessings.           |
| `/titans invaders multipliers`     | `titans.use`   | View the exact multipliers currently affecting the world.      |
| `/titans invaders panic get`       | `titans.admin` | Check the current server Heat level.                           |
| `/titans invaders panic set <val>` | `titans.admin` | Manually set the server Heat level from `0` to `100`.          |
| `/titans invaders event list`      | `titans.admin` | See which scheduled invasion events are active.                |
| `/titans invaders clear [name]`    | `titans.admin` | Clear a specific Invader punishment or all active punishments. |
| `/titans invaders reload`          | `titans.admin` | Live-reload all Invader and event configs.                     |

***

## Configuration Reference

The following blocks can be added to an Invader JSON file.

```
{
  "minions": [
    {
      "hpThresholdPercent": 50,
      "species": "Zubat",
      "count": 5
    }
  ],
  "hazards": [
    {
      "type": "GRAVITY_WELL",
      "intervalSeconds": 30,
      "radius": 50.0
    }
  ],
  "phases": [
    {
      "hpThresholdPercent": 50,
      "newForm": "Mega",
      "announcement": "&cPhase 2!"
    }
  ],
  "pylons": {
    "enabled": true,
    "count": 3,
    "damageReductionPerPylon": 0.3
  },
  "panic": {
    "heatIncreaseOnFailure": 20,
    "heatDecreaseOnSuccess": 10
  }
}
```

***

## Full System Flow

```
Invader Spawns
↓
Players Fight the Invader
↓
Minions, Hazards, Phases, and Pylons Activate During Combat
↓
If Players Win:
  - Heat decreases
  - Blessings may activate
  - Leaderboard damage is saved
↓
If Players Fail:
  - Heat increases
  - Punishments may activate
  - Future Invaders become more dangerous
```

***

## Recommended Admin Usage

| Goal                            | Recommended Feature                                  |
| ------------------------------- | ---------------------------------------------------- |
| Make fights more tactical       | Use `pylons` and `phases`.                           |
| Make fights more chaotic        | Use `minions` and `hazards`.                         |
| Create server-wide consequences | Use `panic` and punishments.                         |
| Create limited-time events      | Use `invasion_events`.                               |
| Encourage player competition    | Enable the persistent leaderboard.                   |
| Make bosses feel cinematic      | Combine phases, announcements, weather, and hazards. |

***

## Quick Summary

| System                     | Purpose                                                   |
| -------------------------- | --------------------------------------------------------- |
| `minions`                  | Summons reinforcement waves during combat.                |
| `hazards`                  | Applies pulsing area effects around the boss.             |
| `phases`                   | Changes the boss mid-fight.                               |
| `pylons`                   | Adds protective structures that reduce boss damage taken. |
| `panic`                    | Tracks global server Heat based on success or failure.    |
| `invasion_events`          | Allows scheduled boosted Invader events.                  |
| `invader_leaderboard.json` | Stores lifetime Invader damage records.                   |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://titans.gitbook.io/titans/invader-system.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.