> 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 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.

## 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="..." />
</CustomMonsterVisuals>
```

## 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)         |

## 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        |

## 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 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
* **NPC renders as monster** - `Type="0"` on an NPC entry; set to `1`