> 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/mapmanager.md).

# MapManager.xml

One entry per map. Controls PK mode, drop rates, experience scaling, MuHelper/custom-feature toggles, and the respawn gate used when a character dies on that map.

## File Location

```
Data/MapManager.xml
```

Loaded once at GameServer startup. Changes require a restart.

## Schema

```xml
<MapList>
    <Map Index="..." Name="..." NonPK="..." PKLimit="..." PKLimitResetInterval="..."
         ViewRange="..." ExperienceRate="..." ItemDropRate="..."
         ExcItemDropRate="..." SetItemDropRate="..."
         SocketItemDrop="..." ExcOptionsRateIndex="..."
         HelperEnable="..." GensBattle="..."
         CustomAttack="..." CustomStore="..." PkDropItem="..." DeathGate="..."
         HelperMinLevel="..." HelperMaxLevel="..."
         HelperExpRate="..." HelperCostMultiplier="..."
         OffAttackMinLevel="..." OffAttackMaxLevel="..."
         OffAttackMaxTime="..." OffAttackExpRate="..." />
</MapList>
```

Ship every map you want players to reach. Maps without an entry fall back to the server-wide defaults (non-PK state from [Common.dat](/docs/gameserver/common-dat.md), view range 15, experience and drop multipliers 100, all feature toggles 0, death gate 17).

## Attributes

### Identity

| Attribute | Type   | Effect                                                                    |
| --------- | ------ | ------------------------------------------------------------------------- |
| `Index`   | int    | Map number. Must match the terrain file and client data. Unique per entry |
| `Name`    | string | Display name for logs. Not shown to clients                               |

### PK and Visibility

| Attribute              | Value                      | Effect                                                                                                                                                                                                                                                                      |
| ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NonPK`                | `*`                        | Use the server-wide NonPK setting from [Common.dat](/docs/gameserver/common-dat.md)                                                                                                                                                                                         |
| `NonPK`                | `1`                        | Safe zone. All PK disabled on this map                                                                                                                                                                                                                                      |
| `NonPK`                | `2`                        | Outlaw-free zone. Outlaw (second-tier PK) status is suppressed on this map                                                                                                                                                                                                  |
| `PKLimit`              | int, `*` or `0` = off      | Maximum free (non-consensual) player kills a single source IP may commit on this map before further PK is blocked. `*` or `0` = unlimited (feature off). The counter is tracked per source IP and per map. Consensual PvP (duel, guild war, event maps) does not count      |
| `PKLimitResetInterval` | int ms, `*` = default      | Length of the rolling window for `PKLimit`, in milliseconds (for example `900000` = 15 minutes). When the window expires the IP's kill count for this map resets to zero. `*`, `0`, or negative uses the built-in default of 900000 ms. Ignored when `PKLimit` is unlimited |
| `ViewRange`            | 10-12 typical, `*` allowed | Monster and player visibility radius. Most maps use `12`; tight arenas use `10`. `*` falls back to the server default of `15`                                                                                                                                               |

### Drop Rates

All rates are out of **1,000,000** (one million). `10000` = 1%, `100000` = 10%, `1000000` = 100%.

| Attribute         | Type            | Effect                                                                    |
| ----------------- | --------------- | ------------------------------------------------------------------------- |
| `ExperienceRate`  | int %           | XP multiplier. `100` = 100% baseline, `200` = 2x                          |
| `ItemDropRate`    | int             | General item drop multiplier, percent (not per-million). `100` = baseline |
| `ExcItemDropRate` | int out of 10^6 | Chance of any drop rolling excellent. Requires monster level 25+          |
| `SetItemDropRate` | int out of 10^6 | Chance of any drop rolling ancient-set. Requires monster level 25+        |
| `SocketItemDrop`  | 0 or 1          | `1` enables socket items on this map                                      |

### Excellent Options Source

`ExcOptionsRateIndex` picks which `ItemOptionRate.xml` index controls excellent option counts:

| Value       | Behavior                                                                                                                                                                                      |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `*` or `-1` | **OG Mode (default).** `ExcItemDropRate` determines whether drops roll excellent. Uses ItemOptionRate indices 0/1 with `DropLevel - 25`, filtered item pool                                   |
| `0+`        | **Config Mode.** Use the named ItemOptionRate index directly. `ExcItemDropRate` is ignored. Any item can become excellent based on that index's rates. No DropLevel reduction, full item pool |

See [ItemOptionRate.xml](/docs/data/item/itemoptionrate.md).

### Feature Toggles

| Attribute      | Default                                         | Effect when `1`                                                                                                   |
| -------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `HelperEnable` | `1` for normal maps, `0` inside event instances | MuHelper allowed on this map                                                                                      |
| `GensBattle`   | `0`                                             | Gens faction PvP enabled                                                                                          |
| `CustomAttack` | `1` for normal, `0` for events                  | Allow PvP attack resolution via custom combat code paths                                                          |
| `CustomStore`  | Town-only                                       | Players can open personal shops here                                                                              |
| `PkDropItem`   | `1` for normal                                  | Items drop on PK death (subject to [Common.dat](/docs/gameserver/common-dat.md#pk-item-drop) `PkItemDrop*` gates) |

{% hint style="info" %}
The `CustomPick` attribute ships in the stock `MapManager.xml` for historical reasons but is not read by the current GameServer loader. Ground-pickup permission is governed elsewhere. Leave it in place for cleanliness; changing it has no effect.
{% endhint %}

### Per-map MuHelper and Offline Mode limits

Eight attributes tune MuHelper and offline-attack behavior per map. Set any of them to `*` to inherit the server-wide value. Level caps count combined level (character Level + Master Level); `0` on a max-level cap means no cap.

| Attribute              | Type              | `*` falls back to                                                                         | Effect                                                                                                                                        |
| ---------------------- | ----------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `HelperMinLevel`       | int               | [Common.dat](/docs/gameserver/common-dat.md#helper-settings-muhelper) `HelperActiveLevel` | Minimum character level to run MuHelper on this map                                                                                           |
| `HelperMaxLevel`       | int, `0` = no cap | [Common.dat](/docs/gameserver/common-dat.md#helper-settings-muhelper) `HelperMaxLevel`    | Maximum combined level to run MuHelper on this map                                                                                            |
| `HelperExpRate`        | int %             | [Common.dat](/docs/gameserver/common-dat.md#helper-settings-muhelper) `HelperExpRate`     | XP percentage earned while MuHelper is active here. `100` = full, `50` = half                                                                 |
| `HelperCostMultiplier` | int %             | `100` (no server-wide key)                                                                | Zen cost percentage multiplier for MuHelper on this map. `100` = normal, `200` = double. `*` uses `100`                                       |
| `OffAttackMinLevel`    | int               | [Common.dat](/docs/gameserver/common-dat.md#helper-settings-muhelper) `OffAttackMinLevel` | Minimum character level for offline attack on this map                                                                                        |
| `OffAttackMaxLevel`    | int, `0` = no cap | [Common.dat](/docs/gameserver/common-dat.md#helper-settings-muhelper) `OffAttackMaxLevel` | Maximum combined level for offline attack on this map                                                                                         |
| `OffAttackMaxTime`     | int minutes       | `-1` (no limit; no server-wide key)                                                       | Maximum minutes a character may stay in offline attack on this map. Overrides the per-tier `CustomAttackTime_AL*`. `*` means no per-map limit |
| `OffAttackExpRate`     | int %             | `100` (no server-wide key)                                                                | XP percentage earned during offline attack on this map. `100` = full. `*` uses `100`                                                          |

Four of these have a server-wide fallback key in [Common.dat](/docs/gameserver/common-dat.md#helper-settings-muhelper): `HelperMaxLevel`, `HelperExpRate`, `OffAttackMinLevel`, and `OffAttackMaxLevel`. `HelperMinLevel` falls back to `HelperActiveLevel`; `HelperCostMultiplier` and `OffAttackExpRate` fall back to `100`; `OffAttackMaxTime` falls back to no per-map limit. Maps with no entry in this file also use these fallbacks.

### Respawn

| Attribute   | Type | Effect                                                                                        |
| ----------- | ---- | --------------------------------------------------------------------------------------------- |
| `DeathGate` | int  | Gate index to warp the player to on death. Gate definitions in [Gate.txt](/docs/data/gate.md) |

## Drop Rate Math

Excellent and Set rolls use `random(0, 999999)`; if roll `<` rate and monster level `>= 25`, drop is excellent/set.

| `ExcItemDropRate` | Chance           |
| ----------------- | ---------------- |
| `1000`            | 0.1%             |
| `10000`           | 1%               |
| `50000`           | 5%               |
| `100000`          | 10%              |
| `1000000`         | 100% (test-only) |

## Examples

{% tabs %}
{% tab title="Town map" %}
{% code title="MapManager.xml fragment" %}

```xml
<Map Index="0"  NonPK="*" ViewRange="12"
     ExperienceRate="100" ItemDropRate="100"
     ExcItemDropRate="100000" SetItemDropRate="0"
     SocketItemDrop="0" ExcOptionsRateIndex="*"
     HelperEnable="1" GensBattle="0"
     CustomAttack="1" CustomStore="1"
     PkDropItem="1" DeathGate="17" Name="Lorencia"/>
```

{% endcode %}

Lorencia: normal PK rules, personal shops allowed, 10% excellent drop chance, respawn via gate 17.
{% endtab %}

{% tab title="Event instance" %}
{% code title="MapManager.xml fragment" %}

```xml
<Map Index="11" NonPK="*" ViewRange="10"
     ExperienceRate="100" ItemDropRate="100"
     ExcItemDropRate="100000" SetItemDropRate="0"
     SocketItemDrop="0" ExcOptionsRateIndex="*"
     HelperEnable="1" GensBattle="0"
     CustomAttack="0" CustomStore="0"
     PkDropItem="0" DeathGate="22" Name="Blood Castle 1"/>
```

{% endcode %}

Blood Castle: tight view range, no personal shops, combat routing disabled, no PK drops, respawn via gate 22.
{% endtab %}

{% tab title="Map with custom excellent index" %}
{% code title="MapManager.xml fragment" %}

```xml
<Map Index="33" NonPK="*" ViewRange="12"
     ExperienceRate="100" ItemDropRate="100"
     ExcItemDropRate="100000" SetItemDropRate="0"
     SocketItemDrop="0" ExcOptionsRateIndex="100"
     HelperEnable="1" GensBattle="0"
     CustomAttack="1" CustomStore="0"
     PkDropItem="1" DeathGate="119" Name="Aida"/>
```

{% endcode %}

Aida uses `ExcOptionsRateIndex="100"`, pulling excellent option rates from index 100 of [ItemOptionRate.xml](/docs/data/item/itemoptionrate.md) and ignoring `ExcItemDropRate`.
{% endtab %}
{% endtabs %}

## Cross-File Dependencies

| Attribute                                                                   | Related in                                                                                                                                  |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `ExperienceRate`                                                            | Combined with [Common.dat](/docs/gameserver/common-dat.md#experience-settings) `AddExperienceRate_AL0-3`                                    |
| `ItemDropRate`                                                              | Combined with [Common.dat](/docs/gameserver/common-dat.md#item-drop-settings) `ItemDropRate_AL0-3`                                          |
| `ExcItemDropRate` / `SetItemDropRate`                                       | Pool definitions in [ExcellentOptionRate.xml](/docs/data/item/excellentoptionrate.md) and [SetItemType.xml](/docs/data/item/setitemtype.md) |
| `SocketItemDrop`                                                            | Socket item definitions in [SocketItemType.xml](/docs/data/item/socketitemtype.md)                                                          |
| `ExcOptionsRateIndex`                                                       | Named rate index in [ItemOptionRate.xml](/docs/data/item/itemoptionrate.md)                                                                 |
| `HelperEnable`                                                              | Master toggle in [Common.dat](/docs/gameserver/common-dat.md#helper-settings-muhelper) `HelperSwitch`                                       |
| `HelperMaxLevel`, `HelperExpRate`, `OffAttackMinLevel`, `OffAttackMaxLevel` | Server-wide fallbacks in [Common.dat](/docs/gameserver/common-dat.md#helper-settings-muhelper) when set to `*`                              |
| `PKLimit`, `PKLimitResetInterval`                                           | Self-contained per-map/per-IP limit; consensual PvP is exempt                                                                               |
| `GensBattle`                                                                | Master system in [Common.dat](/docs/gameserver/common-dat.md#gens-system-settings) `GensSystem*`                                            |
| `PkDropItem`                                                                | Gated by [Common.dat](/docs/gameserver/common-dat.md#pk-item-drop) `PkItemDropSwitch`                                                       |
| `DeathGate`                                                                 | Gate definitions in [Gate.txt](/docs/data/gate.md)                                                                                          |
| Per-map spawns                                                              | [MonsterSetBase](/docs/data/monster/monstersetbase.md) places monsters on the maps this file enables                                        |
| Multi-GS routing                                                            | [MapServerInfo.xml](/docs/data/mapserverinfo.md) decides which GameServer owns each map when multiple servers share the world               |

## Common Issues

* **PK allowed on a town** - `NonPK="*"` instead of `"1"`. Safe-zone towns need the `1` value
* **Excellent drops never happen** - monster level is below 25; check monster definitions in [Monster.xml](/docs/data/monster/monster.md)
* **Personal shops blocked in town** - `CustomStore="0"`
* **Characters respawn in the wrong place** - `DeathGate` points at the wrong gate index; check [Gate.txt](/docs/data/gate.md)
* **MuHelper works in Lorencia but not in an event map** - event maps ship with `HelperEnable="0"` by design
* **MuHelper or offline attack rejected on a specific map for high-level characters** - `HelperMaxLevel` or `OffAttackMaxLevel` on that map (or its Common.dat fallback) is set below the character's combined level; use `0` for no cap
* **PK blocked with a "try again" notice on one map** - `PKLimit` on that map is reached for the player's IP; the window clears after `PKLimitResetInterval` ms (default 900000)
* **Missing map produces invalid warp errors** - every map the player can reach needs an entry; gaps in `Index` are allowed but the referenced map must exist