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

# CustomArena

Scheduled PvP tournament arenas. Each arena defines its own schedule, entry gates (level / reset / master reset), class whitelist, point scoring, and teleport targets. Up to 30 independent arenas can be scheduled on one server.

## File Location

```
Data/Plugins/Events/CustomArena.xml
```

Loaded once at GameServer startup. Supports hot reload via plugin admin command.

## Root Attributes

```xml
<CustomArena Enabled="..." VictimScoreDecrease="..." KillerScoreIncrease="...">
```

| Attribute             | Type   | Effect                                                          |
| --------------------- | ------ | --------------------------------------------------------------- |
| `Enabled`             | 0 or 1 | Master toggle                                                   |
| `VictimScoreDecrease` | int    | Points deducted per death. Clamped so score never drops below 0 |
| `KillerScoreIncrease` | int    | Points awarded per kill                                         |

## Messages

19 customizable message strings inside a `<Messages>` block. Each `<Text Id="N" Value="..."/>` replaces the default broadcast for that event type.

```xml
<Messages>
    <Text Id="1" Value="[%s] will close in %d minute(s)"/>
    ...
</Messages>
```

| Id | Meaning                                                                                                    | Format args                           |
| -- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| 1  | Alarm countdown                                                                                            | `%s`=ArenaName, `%d`=MinutesLeft      |
| 2  | Arena closed                                                                                               | `%s`=ArenaName                        |
| 3  | Standby notice                                                                                             | `%s`=ArenaName, `%d`=StandTime        |
| 4  | Arena started                                                                                              | `%s`=ArenaName                        |
| 5  | Arena finished                                                                                             | `%s`=ArenaName                        |
| 6  | Winner announce                                                                                            | `%s`=ArenaName, `%s`=PlayerName       |
| 7  | Rank result                                                                                                | `%s`=ArenaName, `%d`=Rank, `%d`=Score |
| 8  | Cannot enter (generic restriction: party, guild war, duel, personal shop, already inside, map server down) |                                       |
| 9  | Arena not currently open                                                                                   |                                       |
| 10 | Max players reached                                                                                        |                                       |
| 11 | Min level required (`%d`=MinLevel)                                                                         |                                       |
| 12 | Max level exceeded (`%d`=MaxLevel)                                                                         |                                       |
| 13 | Min master level (`%d`=MinMasterLevel)                                                                     |                                       |
| 14 | Max master level (`%d`=MaxMasterLevel)                                                                     |                                       |
| 15 | Min resets (`%d`=MinReset)                                                                                 |                                       |
| 16 | Max resets (`%d`=MaxReset)                                                                                 |                                       |
| 17 | Min master resets (`%d`=MinMasterReset)                                                                    |                                       |
| 18 | Max master resets (`%d`=MaxMasterReset)                                                                    |                                       |
| 19 | Class not allowed                                                                                          |                                       |

Keep the format specifiers or replacement text will be garbled.

## Arenas

Each arena is wrapped in its own `<Arena Index="0-29">` block and contains its own `<Schedule>` and `<Rules>` elements. The schedule is per-arena, not global.

```xml
<Arena Index="0">
    <Schedule>
        <Time Year="-1" Month="-1" Day="-1" DayOfWeek="-1" Hour="20" Minute="0" Second="0"/>
    </Schedule>
    <Rules Name="..." AlarmTime="..." StandTime="..." EventTime="..." CloseTime="..."
           StartGate="..." FinalGate="..."
           MinUser="..." MaxUser="..." MaxDeath="..."
           MinLevel="..." MaxLevel="..."
           MinMasterLevel="..." MaxMasterLevel="..."
           MinReset="..." MaxReset="..."
           MinMasterReset="..." MaxMasterReset="..."
           DW="..." DK="..." FE="..." MG="..." DL="..." SU="..." RF="..." />
</Arena>
```

### Schedule

```xml
<Time Year="-1" Month="-1" Day="-1" DayOfWeek="-1" Hour="20" Minute="0" Second="0"/>
```

`-1` = wildcard. `DayOfWeek`: `1` = Sunday through `7` = Saturday. Multiple `<Time>` entries can be added to schedule the same arena at several instants.

### Rules

| Attribute                           | Effect                                                                                    |
| ----------------------------------- | ----------------------------------------------------------------------------------------- |
| `Name`                              | Arena display name (max 31 characters)                                                    |
| `AlarmTime`                         | Minutes before start to announce and open entry. Default 5                                |
| `StandTime`                         | Minutes in standby after entry closes. `0` skips                                          |
| `EventTime`                         | Main PvP duration in minutes. Default 5                                                   |
| `CloseTime`                         | Minutes for results display. `0` skips                                                    |
| `StartGate`                         | [Gate](/docs/data/gate.md) ID for teleporting players in. Must target map 40 (Silent Map) |
| `FinalGate`                         | Gate ID for teleporting players out after the event                                       |
| `MinUser`                           | Minimum participants to advance from Stand to Start. `-1` defaults to `1`                 |
| `MaxUser`                           | Maximum participants. Hard-capped at 100                                                  |
| `MaxDeath`                          | Deaths before the player is kicked to `FinalGate`. `-1` = unlimited                       |
| `MinLevel` / `MaxLevel`             | Character level range. `-1` = no limit                                                    |
| `MinMasterLevel` / `MaxMasterLevel` | Master level range. `-1` = no limit                                                       |
| `MinReset` / `MaxReset`             | Reset count range. `-1` = no limit                                                        |
| `MinMasterReset` / `MaxMasterReset` | Master reset range. `-1` = no limit                                                       |
| `DW`                                | Dark Wizard gate (tri-state, see below)                                                   |
| `DK`                                | Dark Knight gate                                                                          |
| `FE`                                | Fairy Elf gate                                                                            |
| `MG`                                | Magic Gladiator gate                                                                      |
| `DL`                                | Dark Lord gate                                                                            |
| `SU`                                | Summoner gate                                                                             |
| `RF`                                | Rage Fighter gate                                                                         |

### Class gate values

Each class attribute accepts a small integer that sets the maximum tier allowed for that class. The value is compared against the character's class-change tier plus one.

| Value | Meaning                                                                        |
| ----- | ------------------------------------------------------------------------------ |
| `0`   | Class blocked outright                                                         |
| `1`   | 1st class only (base class, e.g. Dark Wizard)                                  |
| `2`   | 1st or 2nd class allowed (e.g. Dark Wizard or Soul Master)                     |
| `3`   | 1st, 2nd or 3rd class allowed (e.g. Dark Wizard, Soul Master, or Grand Master) |

Default when the attribute is omitted is `1`.

{% hint style="info" %}
**Class gate is a ceiling, not a floor.** `2` lets 1st-tier AND 2nd-tier characters in. To restrict an arena to top-tier only, you have to fence with `MinMasterLevel` or `MinReset` instead; the class flag alone cannot express "3rd tier only".
{% endhint %}

## Match Lifecycle

Each arena cycles through these states:

1. **Empty** - Counting down to the next scheduled start. `AlarmTime` minutes before start, entry opens and countdown announcements begin.
2. **Stand** - Entry closed. Waits `StandTime` minutes for participants to gather. Drops back to Empty if participant count falls under `MinUser`.
3. **Start** - Combat phase, lasts `EventTime` minutes. Ends early if only one player remains.
4. **Clean** - Ranks are calculated and saved to the ranking database. Winner announcement broadcast server-wide. `CloseTime` minutes before the arena returns to Empty and players are teleported out via `FinalGate`.

Players exceeding `MaxDeath` are teleported to `FinalGate` mid-match and their rank is locked at 0.

## Kill Scoring

On each kill inside an active arena:

* Victim loses `VictimScoreDecrease` points (floored at 0), kill streak resets, death count and death streak increment.
* Killer gains `KillerScoreIncrease` points, kill count and kill streak increment, death streak resets.

## Cross-File Dependencies

| Attribute                | Related in                                                                          |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `StartGate`, `FinalGate` | [Gate.txt](/docs/data/gate.md)                                                      |
| Arena map (Silent Map)   | [MapManager.xml](/docs/data/mapmanager.md)                                          |
| Ranking storage          | [Event overview](/docs/data/event.md)                                               |
| Damage scaling           | [Character.dat](/docs/gameserver/character-dat.md) `CustomArenaDamageRate`          |
| Elemental scaling        | [Character.dat](/docs/gameserver/character-dat.md) `CustomArenaElementalDamageRate` |

## Common Issues

* **Arena starts but players teleport to wrong map** - `StartGate` points at a gate that is not on the Silent Map
* **No one can enter at level 400** - `MaxLevel` set below 400 for a high-level server; raise it
* **Winner announce shows literal `%s %s`** - message text missing a format specifier; the engine uses positional parameters
* **Class filter rejects everyone** - every per-class flag (`DW`/`DK`/`FE`/`MG`/`DL`/`SU`/`RF`) is `0`; at least one must be nonzero for anyone to enter
* **Points go negative** - cannot happen; victim score is floored at 0. If you see negative on-screen values, it is a display bug, not a score bug
* **Arena never triggers** - missing `<Schedule>` block inside the `<Arena>` node, or all `<Time>` entries have already passed with no recurring wildcard