> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/event/invasionmanager.md). # Invasions Scheduled monster invasions across the world. Each invasion is its own self-contained XML file under `Data/Event/Invasions/`. Up to 30 invasions are supported. The legacy `InvasionManager.dat` file is no longer read. Every invasion now has its own schedule, message strings, spawn map groups, and monster table inside one XML. ## File Location ``` Data/Event/Invasions/ - .xml ``` The 3-digit `NNN` prefix is the **stable numeric index** used by `ForceStart`, the `/invasion` console command, and `EventTimerSlot` binding. Anything after `-` is decorative and ignored by the loader. Inside the XML, `` is the human-readable label. Loaded once at GameServer startup. Gated by [Event.dat](/docs/gameserver/event-dat.md#invasion-manager) `InvasionManagerSwitch`. Use the in-server GUI **Reload** action (or restart) to re-scan the folder after edits. ## Default invasions shipped | File | EventTimerSlot | | ------------------------- | -------------------- | | `000 - Skeleton King.xml` | 14 | | `001 - Red Dragon.xml` | 15 | | `002 - Goldens.xml` | 16 | | `003 - White Wizard.xml` | 17 | | `004 - New Year.xml` | -1 (no client timer) | | `005 - Rabbits.xml` | -1 | | `006 - Summer.xml` | -1 | | `007 - Cursed Santa.xml` | 21 | | `008 - Medusa.xml` | 22 | Add a new invasion by dropping in ` - .xml` with a free `NNN` (0-29). ## XML Layout ```xml ... ... ... ... ``` ### `` attributes | Attribute | Type | Default | Effect | | ------------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Name` | string | `"Unnamed"` | Human-readable invasion name (logs, GUI, message substitutions) | | `DurationSec` | int | `600` | Maximum run time in seconds. Invasion ends on timeout, boss-policy satisfied, or all monsters dead | | `MinOnlineUsers` | int | `0` | Pre-start gate. If fewer players are online, the invasion is postponed (and `NotEnoughPlayers` message is broadcast if configured) | | `AnnounceLeadSec` | int | `60` | Seconds before start to broadcast `AnnounceBeforeStart` | | `AnnounceMessageType` | enum | `Disabled` | `Disabled` or `GoldenCenter`. Render style for the pre-start announce | | `FinalMessageType` | enum | `Disabled` | Same enum; render style for `Start` / `End` | | `MonsterCountMessageType` | enum | `Disabled` | Same enum; render style for `MonsterKilled` progress messages | | `EventTimerSlot` | int | `-1` | Slot ID broadcast over `C2:F3:E9` for the client event-timer UI. `-1` = no client broadcast | | `BossEndPolicy` | enum | `First` | `First` = any boss kill ends the invasion. `All` = invasion runs until every spawned boss dies. `Never` = boss kills never end the invasion; ends only on timer or when all monsters (trash + bosses) are dead | | `ClusterAroundBoss` | 0 or 1 | `0` | `1` = trash monsters spawn within `ClusterRadius` tiles of the boss anchor. `0` = trash scatters independently across the MapGroup rectangle | | `ClusterRadius` | tiles | `20` | Radius used when `ClusterAroundBoss=1` | ### `` Optional chat / center-screen strings. Empty children are silent. | Element | When broadcast | Substitutions | | ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `` | `AnnounceLeadSec` before start | `{0}` = seconds remaining | | `` | Invasion begins | none | | `` | Invasion ends (timer / boss / cleanup) | none | | `` | Start gated by `MinOnlineUsers` | `{0}` = additional players needed | | `` | Trash monster death (rendered via `MonsterCountMessageType`) | `{0}` killer name, `{1}` monster class name (from [Monster.xml](/docs/data/monster/monster.md)) | | `` | Boss death | `{0}` killer name, `{1}` map, `{2}` X, `{3}` Y, `{4}` boss class name (from [Monster.xml](/docs/data/monster/monster.md)) | ### `` Each `` is one calendar firing time. Multiple entries = multiple firings per day. Wildcard `*` matches any value. ```xml ``` Attributes: `Year`, `Month`, `Day`, `DoW` (day of week, 0-6), `Hour`, `Min`, `Sec`. All accept `*` for "any". ### `` Spawn-anchor rectangles. The runtime picks **one `` row per matching `Index`/`SubIndex` pair** when the invasion fires and uses that rectangle to position monsters. ```xml ``` | Attribute | Effect | | ---------------------- | --------------------------------------------------------------------------------------- | | `Index` | Group ID. Must match a value in `` | | `SubIndex` | Alternate spawn region for the same group. One is selected at random per invasion cycle | | `Map` | Target map index ([MapManager.xml](/docs/data/mapmanager.md)) | | `X1`, `Y1`, `X2`, `Y2` | Spawn rectangle bounds (tile coords) | | `Comment` | Optional, ignored by loader | ### `` Per-group spawn definitions. Every matching `` row spawns `Count` instances of `MonsterClass`. ```xml ``` | Attribute | Effect | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | `GroupIndex` | Matches `MapGroups/` | | `SubIndex` | Matches `MapGroups/`. Only rows whose `SubIndex` matches the chosen MapGroup spawn this cycle | | `MonsterClass` | Monster class index ([Monster.xml](/docs/data/monster/monster.md)) | | `Range` | Random scatter radius around the anchor point (tiles) | | `Count` | How many instances to spawn | | `Boss` | `1` = counted by `BossEndPolicy` and triggers `BossKilled` on death. `0` = trash mob | | `RegenType` | `0` = no respawn during invasion. Non-zero = respawn after `RegenTimeSec` | | `RegenTimeSec` | Respawn delay in seconds when `RegenType != 0` | | `ItemBag` | EventItemBag entry granted on death. `-1` = no bag drop ([EventItemBag.xml](/docs/data/eventitembag.md)) | | `MinUsersToSpawn` | Population gate per-monster. `-1` = always spawn. Otherwise spawn only when online users >= this value | | `Comment` | Optional, ignored | ## Runtime hooks * **GUI**: GameServer's invasion panel exposes Start / Reload / state inspection per invasion. * **GS console**: `/invasion start ` and `/invasion start ` force-fire bypass schedule + online gate. * **EventTimerInfo**: invasions with `EventTimerSlot >= 0` broadcast remaining time / state to the client tooltip system. See [EventTimerInfo.xml](/docs/data/plugins/eventtimerinfo.md). * **HUD**: active invasion state is mirrored to a dedicated client HUD. The HUD lists up to 16 concurrent event rows per page; with more than 16 active at once the extra rows are not shown. ## Cross-File Dependencies | Value | Related in | | ------------------------------- | ----------------------------------------------------------------------------------- | | Master enable | [Event.dat](/docs/gameserver/event-dat.md#invasion-manager) `InvasionManagerSwitch` | | `MonsterClass` | [Monster.xml](/docs/data/monster/monster.md) | | `Map` | [MapManager.xml](/docs/data/mapmanager.md) | | `ItemBag` | [EventItemBag.xml](/docs/data/eventitembag.md) | | `EventTimerSlot` name + tooltip | [EventTimerInfo.xml](/docs/data/plugins/eventtimerinfo.md) | ## Common Issues * **Invasion never triggers** - `InvasionManagerSwitch = 0` in Event.dat; or all `` entries have past times for the day; or `MinOnlineUsers` not met * **Monsters do not spawn** - `` `SubIndex` does not match the `` randomly chosen this cycle; or `MapGroups` rectangle lands on non-walkable tiles * **Boss spawns but no announcement** - `` element empty, or `EventTimerSlot` not configured for HUD readback * **Invasion ends too early on a boss kill** - `BossEndPolicy="First"` ends on any boss death. `"All"` ends on the *last* boss death - with only one boss spawned it behaves identically to `"First"` (the only kill is the last kill). Use `"Never"` to let the event run until the timer or all monsters (trash + bosses) are dead, regardless of boss kills * **Monsters keep respawning mid-invasion** - `RegenType != 0`; set to `0` for single-wave behavior * **Two invasions at the same time** - intended when distinct files have overlapping schedule entries. Use different `` times to sequence * **Edits ignored after Reload** - file lacks `` root, or `NNN` prefix collides with another file (loader keeps first, logs the rest)