CustomMonsterVisual.xml

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#

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

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.

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
`Id` (for NPCs)	MapManager.xml NPC spawn entries
`Folder` + `BMD`	Client asset at the specified client-side path
Sync channel	GameDataSync 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:

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

<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