# EventTimerInfo

The EventTimerInfo configuration controls what event information is displayed in the client's Event Timer window. It defines event names and rich tooltip descriptions that help players understand upcoming events, their rewards, and how to participate.

## File Location

`GameServer/Data/Plugins/EventTimerInfo.xml`

## Overview

This system provides a modern event timer interface by:

* Displaying event names in the timer window
* Showing rich tooltip descriptions with formatted sections
* Supporting up to 42 different event types (0-41)
* Automatically updating based on server event schedules
* Providing visual states (disabled, waiting, starting soon, active)

The client requests event data via packet `0xF3:0xE8`, and the server responds with `0xF3:0xE9` (C2 header type) containing all enabled event information.

## Event Index Reference

Events are organized into three categories:

| Index Range | Category    | Description                                                         |
| ----------- | ----------- | ------------------------------------------------------------------- |
| 0-13        | Core Events | Main server events (Blood Castle, Devil Square, Castle Siege, etc.) |
| 14-27       | Invasions   | Special invasions and boss events                                   |
| 28-41       | Arenas      | Class-specific PvP arenas                                           |

### Core Events (0-13)

| Index | Default Name    | Source                             |
| ----- | --------------- | ---------------------------------- |
| 0     | Blood Castle    | ServerDisplayer.EventBc            |
| 1     | Devil Square    | ServerDisplayer.EventDs            |
| 2     | Chaos Castle    | ServerDisplayer.EventCc            |
| 3     | Illusion Temple | ServerDisplayer.EventIt            |
| 4     | Lottery         | ServerDisplayer.EventCustomLottery |
| 5     | Quiz Event      | ServerDisplayer.EventCustomQuiz    |
| 6     | Bonus Event     | ServerDisplayer.EventCustomBonus   |
| 7     | Moss Merchant   | ServerDisplayer.EventMoss          |
| 8     | Drop Event      | ServerDisplayer.EventDrop          |
| 9     | Boss Event      | ServerDisplayer.EventKing          |
| 10    | Team vs Team    | ServerDisplayer.EventTvT           |
| 11    | Kanturu         | Kanturu system state               |
| 12    | Crywolf         | Crywolf system state               |
| 13    | Castle Siege    | Castle Siege system state          |

### Invasions (14-27)

| Index | Default Name      | Source                               |
| ----- | ----------------- | ------------------------------------ |
| 14    | Golden Invasion   | ServerDisplayer.EventInvasion\[0]    |
| 15    | Red Dragon        | ServerDisplayer.EventInvasion\[1]    |
| 16    | White Wizard      | ServerDisplayer.EventInvasion\[2]    |
| 17    | Skeleton King     | ServerDisplayer.EventInvasion\[3]    |
| 18    | Raklion           | Raklion system state                 |
| 19    | Imperial Guardian | Imperial Guardian system state       |
| 20    | Guild vs Guild    | ServerDisplayer.EventGvG             |
| 21-27 | Invasion 8-14     | ServerDisplayer.EventInvasion\[7-13] |

### Arenas (28-41)

| Index | Default Name | Class Filter                            | Note                          |
| ----- | ------------ | --------------------------------------- | ----------------------------- |
| 28    | Survivor     | All classes                             |                               |
| 29    | DM vs DM     | Dark Knight only                        | DM = Dark Master (3rd class)  |
| 30    | GM vs GM     | Dark Wizard only                        | GM = Grand Master (3rd class) |
| 31    | BM vs BM     | Blade Master only                       | BM = Blade Master (3rd class) |
| 32    | FM vs FM     | Soul Master only                        | FM = Fist Master (3rd class)  |
| 33    | LE vs LE     | Magic Gladiator only                    | LE = Lord Emperor (3rd class) |
| 34    | ELF vs ELF   | Elf only                                |                               |
| 35    | SUM vs SUM   | Summoner only                           |                               |
| 36-41 | Arena 9-14   | ServerDisplayer.EventCustomArena\[8-13] |                               |

{% hint style="info" %}
**Arena Naming**: The source code uses abbreviated 3rd class names (DM, GM, FM, LE) as defaults. The distributed XML file overrides these with full class names (DK, DW, SM, MG) for better player clarity. You can customize these names to match your server's terminology.
{% endhint %}

## Configuration Format

### Event Entry

| Attribute | Type   | Default    | Description                                                                |
| --------- | ------ | ---------- | -------------------------------------------------------------------------- |
| `Index`   | int    | (required) | Event index (0-41). Must be unique.                                        |
| `Enabled` | bool   | true       | Whether event appears in timer window. Set to false to hide unused events. |
| `Name`    | string | (required) | Display name shown in timer window (max 31 characters).                    |

### Tooltip Structure

Tooltips support two formats:

**Modern `<Line>` Format (Recommended):** Each `<Line>` element represents one line of text in the tooltip. This format does NOT automatically add brackets - you must type them manually.

```xml
<Tooltip>
    <Line>[Header]</Line>
    <Line>Content here</Line>
</Tooltip>
```

**Legacy `<Section>` Format:** Uses `<Section Header="...">` elements where brackets are automatically added around headers.

```xml
<Tooltip>
    <Section Header="Description">Content here</Section>
</Tooltip>
```

**Formatting rules:**

* Empty `<Line></Line>` creates spacing between sections
* Maximum 255 characters total per tooltip (longer descriptions are truncated)
* Use the `<Line>` format for all new configurations

## Event States

The server automatically determines event states based on remaining time:

| State         | Display            | Condition                            |
| ------------- | ------------------ | ------------------------------------ |
| Disabled      | Hidden             | Enabled=false OR remainTime=-1       |
| Waiting       | Normal countdown   | remainTime > 300 seconds (5 minutes) |
| Starting Soon | Yellow/highlighted | remainTime < 300 seconds             |
| Active        | Active indicator   | remainTime = 0                       |

## Important Behavior

{% hint style="info" %}
**State-Based Events**: Some events (Crywolf, Castle Siege, Kanturu, Raklion, Imperial Guardian) use their game system state rather than simple timers. The plugin automatically handles state-to-time conversion.
{% endhint %}

{% hint style="warning" %}
**Tooltip Length Limit**: Each tooltip can contain up to 255 characters. Longer descriptions will be truncated. Keep tooltips concise and use `<Line>` spacing efficiently.
{% endhint %}

{% hint style="info" %}
**Event Name Length**: Event names are limited to 31 characters (EVENT\_NAME\_LEN - 1). Longer names will be truncated when sent to the client.
{% endhint %}

{% hint style="warning" %}
**Index Conflicts**: If you define multiple events with the same Index, only the first one loaded will be used. Always use unique indices.
{% endhint %}

## Examples

{% tabs %}
{% tab title="Simple Event" %}

```xml
<!-- Blood Castle with basic description -->
<Event Index="0" Enabled="true" Name="Blood Castle">
    <Tooltip>
        <Line>[Description]</Line>
        <Line></Line>
        <Line>PvE survival event for levels 15-400.</Line>
        <Line>Fight through waves to protect the statue.</Line>
        <Line></Line>
        <Line>[Rewards]</Line>
        <Line>- Jewel of Chaos</Line>
        <Line>- Ancient Items</Line>
        <Line>- Experience bonus</Line>
    </Tooltip>
</Event>
```

{% endtab %}

{% tab title="Disabled Event" %}

```xml
<!-- Hide Imperial Guardian if your server doesn't run it -->
<Event Index="19" Enabled="false" Name="Imperial Guardian">
    <Tooltip>
        <Line>This event is not available.</Line>
    </Tooltip>
</Event>
```

{% endtab %}

{% tab title="Arena Event" %}

```xml
<!-- Simple arena description -->
<Event Index="28" Enabled="true" Name="Survivor Arena">
    <Tooltip>
        <Line>[Description]</Line>
        <Line></Line>
        <Line>Free-for-all PvP arena.</Line>
        <Line>Last survivor wins!</Line>
        <Line></Line>
        <Line>[Rules]</Line>
        <Line>- No potions or buffs</Line>
        <Line>- Pure skill combat</Line>
    </Tooltip>
</Event>
```

{% endtab %}

{% tab title="Custom Event" %}

```xml
<!-- Custom invasion event -->
<Event Index="21" Enabled="true" Name="Ice Queen">
    <Tooltip>
        <Line>[Description]</Line>
        <Line></Line>
        <Line>The Ice Queen invades the server!</Line>
        <Line>Defeat her for amazing rewards.</Line>
        <Line></Line>
        <Line>[Location]</Line>
        <Line>Random spawns in Lorencia</Line>
        <Line></Line>
        <Line>[Rewards]</Line>
        <Line>- Jewel of Guardian</Line>
        <Line>- Frozen equipment</Line>
        <Line>- Massive experience</Line>
    </Tooltip>
</Event>
```

{% endtab %}
{% endtabs %}

## Tooltip Design Guidelines

### Structure Your Tooltips

Use a consistent pattern across all events:

1. **Description** - What is this event?
2. **Requirements/Location** - How to access it
3. **Rewards** - What players can earn
4. **Rules/Strategy** - Special mechanics

### Use Clear Headers

```xml
<Line>[Description]</Line>  <!-- Main event explanation -->
<Line>[How to Enter]</Line> <!-- Access requirements -->
<Line>[Rewards]</Line>      <!-- Loot information -->
<Line>[Rules]</Line>        <!-- Special mechanics -->
<Line>[Strategy]</Line>     <!-- Tips for success -->
<Line>[Location]</Line>     <!-- Where it happens -->
```

### Keep It Concise

* Each line should be 40-50 characters max for readability
* Use bullet points (- or •) for lists
* Break long paragraphs into multiple lines
* Use empty lines sparingly for section breaks

### Good Tooltip Example

```xml
<Tooltip>
    <Line>[Description]</Line>
    <Line></Line>
    <Line>Team-based capture event. Carry the</Line>
    <Line>Sacred Ball to the enemy pedestal.</Line>
    <Line></Line>
    <Line>[Rewards]</Line>
    <Line>- Illusion Shard Points</Line>
    <Line>- Old Scroll / Illusion Shard</Line>
    <Line>- Special armor sets</Line>
    <Line></Line>
    <Line>[Strategy]</Line>
    <Line>- Protect your ball carrier</Line>
    <Line>- Use CC skills on enemies</Line>
    <Line>- Team coordination is key</Line>
</Tooltip>
```

## Common Issues

{% hint style="warning" %}
**Events Not Appearing**: If an event doesn't show in the timer window, verify:

1. `Enabled="true"` is set
2. The event's timer source is properly configured (check ServerDisplayer or event system)
3. The Index is valid (0-41)
   {% endhint %}

{% hint style="warning" %}
**Tooltip Not Showing**: Empty or malformed tooltips will display "No description available." Ensure:

1. At least one `<Line>` element exists inside `<Tooltip>`
2. XML is properly closed (`</Line>`, `</Tooltip>`, `</Event>`)
3. No invalid XML characters (use < > & for <, >, &)
   {% endhint %}

{% hint style="danger" %}
**Server Crash on Load**: If the server crashes when loading this file:

1. Verify XML is well-formed (matching open/close tags)
2. Check that Index values are 0-41
3. Ensure file encoding is UTF-8
4. Look for special characters that need escaping
   {% endhint %}

{% hint style="info" %}
**Default Fallback**: If the XML file fails to load or is missing, the plugin uses built-in default names and shows "No description available" for all events. The server will continue running with defaults.
{% endhint %}

## Related Configuration

| Config                                                                    | Purpose                                                                  |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [ServerDisplayer](https://axiomemu.gitbook.io/docs/gameserver/gameserver) | Event timer values (EventBc, EventDs, EventInvasion array, etc.)         |
| Event System Configs                                                      | Individual event configurations (BloodCastle.txt, DevilSquare.txt, etc.) |

## Technical Details

### Packet Format

**Client Request**: `0xF3:0xE8` (subheader 0xF3, subcode 0xE8, no additional data) **Server Response**: `0xF3:0xE9` (C2 header type, subheader 0xF3, subcode 0xE9)

Response structure:

* Header (5 bytes): Type, Size, Head (0xF3), Subhead (0xE9)
* Count (1 byte): Number of events
* Event Data (294 bytes each):
  * Index (1 byte)
  * RemainTime (4 bytes): Seconds until event (-1 = disabled)
  * State (1 byte): EVENT\_STATE enum
  * Name (32 bytes): Null-terminated string
  * Description (256 bytes): Null-terminated string with newlines

### Event Time Sources

The plugin queries different sources based on event index:

**ServerDisplayer Fields** (most events):

* `EventBc`, `EventDs`, `EventCc`, `EventIt` (core events 0-3)
* `EventCustomLottery`, `EventCustomQuiz`, `EventCustomBonus` (custom 4-6)
* `EventMoss`, `EventDrop`, `EventKing`, `EventTvT` (special 7-10)
* `EventCryWolf`, `EventCs`, `EventGvG` (large events 12-13, 20)
* `EventInvasion[14]` array (invasion slots 14-27)
* `EventCustomArena[14]` array (arena slots 28-41)

**Game System States** (state-based events):

* **Kanturu (11)**: Uses `gKanturu.GetRemainTime()`
* **Crywolf (12)**: Uses `gCrywolf.GetCrywolfState()` + EventCryWolf
* **Castle Siege (13)**: Uses `EventCsState` + EventCs
* **Raklion (18)**: Uses `gRaklion.GetRaklionState()`
* **Imperial Guardian (19)**: Uses `gImperialGuardian.GetState()`

### Loading Process

1. Server startup calls `gEventTimerInfo.LoadXML("Plugins\\EventTimerInfo.xml")`
2. XML parser reads all `<Event>` nodes
3. For each event:
   * Validates Index (0-41)
   * Stores Enabled, Name attributes
   * Parses `<Tooltip>` with `<Line>` elements
   * Trims whitespace from each line
   * Stores in internal m\_Config array
4. If XML fails to load, uses hardcoded defaults
5. Client can request data anytime via 0xF3:0xE8 packet
