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

# CustomMonsterVisual

Client-side monster and NPC visual overrides (name, model folder, BMD, scale, animation remap and speeds)

Client-side visual overrides for custom monsters and NPCs. Synced to each client via GameDataSync at login. Only entries listed here get custom visuals; all other monsters use the client's hardcoded defaults.

{% hint style="info" %}
The configured `BMD` always wins: the client evicts whatever numbered `MonsterNN.bmd` model occupied that slot and loads your file in its place. Custom monsters do **not** need numbered `MonsterNN.bmd` files and there is no "off-by-one" file naming to account for — put custom models in `Data\Custom\Monster` (`Folder="2"`) under their real names.
{% endhint %}

## File Location

```
Data/Plugins/World/CustomMonsterVisual.xml
```

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

## Schema

```xml
<CustomMonsterVisuals>
    <Monster Id="..." Type="..." Name="..." Folder="..." BMD="..." Size="..."
             ActionIdle="..." ActionIdle2="..." ActionWalk="..."
             ActionAttack1="..." ActionAttack2="..." ActionShock="..." ActionDie="..."
             IdleSpeed="..." WalkSpeed="..." AttackSpeed="..." ShockSpeed="..." DieSpeed="..."
             MoveSpeed="..." />
</CustomMonsterVisuals>
```

All animation attributes are optional — omit them entirely for a BMD that already uses the standard monster animation order.

## Attributes

| Attribute | Type   | Effect                                                                                                            |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `Id`      | int    | Monster ID (matches `Index` in [Monster.xml](/docs/data/monster/monster.md)). Negative values are skipped on load |
| `Type`    | 0 or 1 | `0` = Monster, `1` = NPC. Values above 1 clamp to `0`                                                             |
| `Name`    | string | Display name shown to clients. Truncated to 31 characters                                                         |
| `Folder`  | 0-3    | Where the client loads the BMD model from. See [Folder values](#folder-values). Values above 3 clamp to `0`       |
| `BMD`     | string | Filename without `.bmd` extension (e.g. `BullFighter`). Truncated to 31 characters                                |
| `Size`    | float  | Model scale. `0` = use the client default, `1.0` = natural scale, `0.5` = half, `2.0` = double                    |

### Folder Values

| Value | Location                                      |
| ----- | --------------------------------------------- |
| `0`   | `Data\Monster` (stock monster models)         |
| `1`   | `Data\NPC` (stock NPC models)                 |
| `2`   | `Data\Custom\Monster` (custom monster models) |
| `3`   | `Data\Custom\NPC` (custom NPC models)         |

### Animation Remap

The client always plays a fixed animation slot per situation: slot 0 while standing, slot 2 while moving, slots 3/4 when attacking, slot 5 when hit, slot 6 on death. A BMD exported from another tool or game version often stores its animations in a different order — that mismatch is what makes a custom monster freeze, slide, or play the wrong animation. These attributes tell the client which animation **inside your BMD** to use for each situation.

Default for every attribute is `-1`: keep whatever animation the BMD has at that slot. Any slot the BMD cannot fill (missing or unmapped) automatically falls back to the idle animation, so a model with only two or three animations still idles, walks and attacks without freezing.

| Attribute       | Plays when                                                  |
| --------------- | ----------------------------------------------------------- |
| `ActionIdle`    | Standing still                                              |
| `ActionIdle2`   | Secondary idle variation (rare; falls back to `ActionIdle`) |
| `ActionWalk`    | Moving                                                      |
| `ActionAttack1` | Primary attack                                              |
| `ActionAttack2` | Secondary attack                                            |
| `ActionShock`   | Taking a hit                                                |
| `ActionDie`     | Dying                                                       |

{% hint style="info" %}
Animation indices are 0-based positions inside the BMD file. Use a BMD viewer to identify which index holds which animation.
{% endhint %}

### Glow Overlay

Renders the golden-monster metal/chrome shine (the effect Golden Budge Dragon and the golden invasion monsters use) on any monster, in any color — for custom "golden", "cursed", "frozen" etc. variants.

| Attribute                   | Default | Effect                                                                                           |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `Glow`                      | 0       | `1` = enable the shine overlay. Also enabled implicitly by supplying any `GlowR`/`GlowG`/`GlowB` |
| `GlowR` / `GlowG` / `GlowB` | 1.0     | Overlay color components, `0.0`–`1.0`                                                            |

Color ideas: `1.00/1.00/0.97` classic golden · `0.78/0.08/0.52` cursed magenta · `1.00/0.00/0.00` blood red · `0.30/0.80/1.00` frozen blue.

{% hint style="info" %}
Monsters that already have a hardcoded shine (golden invasion monsters, Kundun soldiers) can be recolored too — a configured glow color overrides their built-in tint.
{% endhint %}

### Animation Speeds

All optional; `0` (or omitted) = the client's stock defaults.

| Attribute     | Default        | Effect                                                                                                                                                           |
| ------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IdleSpeed`   | 0.25           | Idle animation playback speed                                                                                                                                    |
| `WalkSpeed`   | 0.34           | Walk animation playback speed. Stock monsters range 0.18–1.2. Raise it if the feet slide behind the movement ("skating"), lower it if the feet outrun the ground |
| `AttackSpeed` | 0.33           | Attack animation playback speed                                                                                                                                  |
| `ShockSpeed`  | 0.5            | Hit-reaction playback speed                                                                                                                                      |
| `DieSpeed`    | 0.55           | Death animation playback speed                                                                                                                                   |
| `MoveSpeed`   | client default | How fast the monster physically moves between grid cells (stock monsters use roughly 15–30). Tune together with `WalkSpeed` to eliminate skating                 |

## Cross-File Dependencies

| Attribute        | Related in                                                   |
| ---------------- | ------------------------------------------------------------ |
| `Id`             | [Monster.xml](/docs/data/monster/monster.md)                 |
| `Id` (for NPCs)  | [MapManager.xml](/docs/data/mapmanager.md) NPC spawn entries |
| `Folder` + `BMD` | Client asset at the specified client-side path               |
| Sync channel     | [GameDataSync](/docs/data/game-data-sync.md) at login        |

## Example

A boss model whose BMD stores its animations as 0=die, 1=idle, 2=attack, 3=walk, with a slower walk and matching movement speed:

```xml
<Monster Id="501" Type="0" Name="Reordered Boss" Folder="2" BMD="ReorderedBoss" Size="1.2"
         ActionIdle="1" ActionWalk="3" ActionAttack1="2" ActionAttack2="2" ActionDie="0"
         WalkSpeed="0.28" MoveSpeed="22" />
```

A "cursed" variant of a stock monster with a magenta golden-style shine:

```xml
<Monster Id="502" Type="0" Name="Cursed Knight" Folder="2" BMD="CursedKnight" Size="1.0"
         GlowR="0.78" GlowG="0.08" GlowB="0.52" />
```

## Common Issues

* **Custom monster invisible** - client does not ship the BMD file at the `Folder` path; either add to client assets or use a stock `Folder=0`/`1` model
* **Monster frozen (no idle, no walk)** - the BMD's animations are not in the standard order, so the client is playing an empty/one-frame slot; set the `Action*` remap attributes
* **Monster slides/skates while moving** - walk animation speed does not match movement speed; tune `WalkSpeed` (and `MoveSpeed`) — raise `WalkSpeed` if the feet lag behind, lower it if they outrun the ground
* **Attacks look sluggish** - raise `AttackSpeed` (stock default 0.33)
* **Wrong animation plays for walk/attack** - the BMD stores animations in a different order; map the correct indices with `ActionWalk`/`ActionAttack1`/etc.
* **BMD loads for some files but not others** - the client supports BMD versions 0x0A (plain) and 0x0C (encrypted); newer-season 0x0F files will not load — re-export/convert them
* **Monster name unchanged** - `Name` attribute empty or omitted
* **Scale too small to select** - `Size` below \~0.3 makes the target selector miss; raise to at least 0.5
* **Players see stock visuals after hot reload** - visuals sync at login; existing sessions stay on the old version until relog; the model itself also loads once per client session
* **NPC renders as monster** - `Type="0"` on an NPC entry; set to `1`