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

# CustomEventDrop

Scheduled item-drop events. Each event drops a configured list of items at a specific map location over a short time window, with alarm and completion announcements. Up to 10 independent events can be scheduled per server.

## File Location

```
Data/Plugins/Events/CustomEventDrop.xml
```

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

## Schema

```xml
<CustomEventDrop Enabled="...">
    <Messages>
        <Text Id="..." Value="..."/>
    </Messages>
    <Event Index="...">
        <Schedule>
            <Time Year="..." Month="..." Day="..." DayOfWeek="..." Hour="..." Minute="..." Second="..."/>
        </Schedule>
        <Rules Name="..." DropMap="..." DropX="..." DropY="..." DropRange="..."
               AlarmTime="..." EventTime="..." />
        <Items>
            <Item ItemIndex="..." ItemLevel="..." DropCount="..." DropDelay="..."/>
        </Items>
    </Event>
</CustomEventDrop>
```

## Root Attributes

| Attribute | Type   | Effect        |
| --------- | ------ | ------------- |
| `Enabled` | 0 or 1 | Master toggle |

## Messages

| Id  | Meaning         | Format args                      |
| --- | --------------- | -------------------------------- |
| `1` | Alarm countdown | `%s`=EventName, `%d`=MinutesLeft |
| `2` | Event started   | `%s`=EventName                   |
| `3` | Event finished  | `%s`=EventName                   |

Keep the format specifiers or the broadcast text will be garbled.

## Event

`Index` is 0-9 (max 10 events per server). Each event can have multiple scheduled starts and its own drop list.

## Schedule

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

`-1` = wildcard. `DayOfWeek`: same mapping as [CustomArena.xml](/docs/data/plugins/customarena.md#schedule) (`1`=Sunday through `7`=Saturday). Multiple `<Time>` entries are allowed; each is evaluated as a separate occurrence and the earliest future one wins.

## Rules

| Attribute         | Default | Effect                                                                                                                        |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `Name`            | empty   | Event display name used in announcements (max 31 characters)                                                                  |
| `DropMap`         | 0       | Map index where items spawn                                                                                                   |
| `DropX` / `DropY` | 0       | Drop center coordinates                                                                                                       |
| `DropRange`       | 5       | Half-extent of the scatter box around the center. Each drop jitters X by up to +/- `DropRange` and Y by up to +/- `DropRange` |
| `AlarmTime`       | 5       | Minutes before the event starts to announce (triggers Text 1 once per remaining minute)                                       |
| `EventTime`       | 3       | Duration in minutes the event stays active; all drops must fire within this window                                            |

Drop locations that land on a safe-zone tile or an obstacle tile are retried up to 50 times. If no free tile is found, the item drops at the exact center (`DropX`, `DropY`).

## Items

One `<Item>` per staged drop. The plugin iterates the list every tick during the Start state and fires any entries whose `DropDelay` has been reached.

| Attribute   | Default | Effect                                                                                           |
| ----------- | ------- | ------------------------------------------------------------------------------------------------ |
| `ItemIndex` | 0       | Item ID. `Type * 512 + SubIndex` per the [Item.xml](/docs/data/item/item.md) indexing convention |
| `ItemLevel` | 0       | Item +level, 0-15                                                                                |
| `DropCount` | 1       | Number of copies dropped in one burst                                                            |
| `DropDelay` | 0       | Seconds after event start before this item drops. Use to stagger drops across the window         |

Each burst also triggers a fireworks packet to every user whose viewport includes the drop coordinates.

{% hint style="info" %}
Each `<Item>` entry fires exactly once per event instance. To drop multiple bursts of the same item, add multiple `<Item>` rows with different `DropDelay` values.
{% endhint %}

## Example

{% code title="CustomEventDrop.xml fragment" %}

```xml
<Event Index="0">
    <Schedule>
        <Time Year="-1" Month="-1" Day="-1" DayOfWeek="-1" Hour="19" Minute="0" Second="0"/>
        <Time Year="-1" Month="-1" Day="-1" DayOfWeek="-1" Hour="23" Minute="0" Second="0"/>
    </Schedule>
    <Rules Name="Drop de itens" DropMap="0" DropX="145" DropY="135" DropRange="5"
           AlarmTime="5" EventTime="3"/>
    <Items>
        <Item ItemIndex="6159" ItemLevel="0" DropCount="3" DropDelay="0"/>
        <Item ItemIndex="6159" ItemLevel="0" DropCount="3" DropDelay="10"/>
    </Items>
</Event>
```

{% endcode %}

Fires at 19:00 and 23:00 daily. Announces 5 minutes before start. Runs for 3 minutes at Lorencia coord (145, 135) with a 5-tile scatter radius. Drops 3 Jewels of Chaos at start and 3 more at T+10 seconds.

## Cross-File Dependencies

| Attribute                | Related in                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `ItemIndex`, `ItemLevel` | [Item.xml](/docs/data/item/item.md)                                                                    |
| `DropMap`                | [MapManager.xml](/docs/data/mapmanager.md)                                                             |
| Event scheduling model   | [Event overview](/docs/data/event.md)                                                                  |
| Pickup gate              | [Common.dat](/docs/gameserver/common-dat.md) `ItemDropTime` controls how long drops stay on the ground |

## Common Issues

* **Items never drop** - `Enabled="0"`, event `Index` outside 0-9, or `<Schedule>` has no future occurrence
* **Items always spawn on the exact center tile** - scatter target tiles are all blocked (safe zone or obstacle); move `DropX` / `DropY` to open ground or widen `DropRange`
* **All drops pile on one tile** - `DropRange="0"` was clamped to 1 internally but produces near-zero jitter; widen to scatter
* **Event name shows as literal `%s`** - message `Value` missing the `%s` specifier
* **Same item seems to drop twice from one entry** - it does not; check for duplicate `<Item>` rows with identical `DropDelay`
* **Multiple events overlap on the same map** - intentional or unintentional; pay attention if two event indexes fire at the same coordinates close in time