CustomPets.xml

Adds pets and rideable mounts as helper items (equip slot 8). Pets follow the character and can collect zen; mounts are ridden, with their own animation set and movement speed. Both are injected into the item table at boot and synced to the client automatically.

File Location#

Data/Plugins/Items/CustomPets.xml

Loaded once at GameServer startup and streamed to clients on connect. Models live in Data/CustomPets/ (item and pet models) and Data/CustomSkill/ (ridden mount meshes); the client mirrors both folders.

Schema#

<CustomPets>
    <Pet   Index="..." Name="..." Model="..." .../>
    <Mount Index="..." Name="..." ItemModel="..." MountMesh="..." .../>
</CustomPets>

Every entry occupies a group-13 sub-index. The global item index is 13 * 512 + Index, so Index="150" is item 6806.

Shared Attributes#

Attribute	Type	Default	Effect
`Index`	150-254	-	Group-13 sub-index. Must be unique
`Name`	string (up to 31 chars)	-	Item name. The GameServer aborts on startup if this is longer than 31 characters
`Scale`	float	`1.0`	Render scale of the model
`RequireLevel`	int	`0`	Minimum character level to equip
`Durability`	int	-	Maximum durability

Pet Attributes#

Attribute	Type	Default	Effect
`Model`	filename	-	Pet model in `Data/CustomPets/`, with its textures beside it
`IdleAction`	int or list	`0`	Animation(s) played while standing. A comma-separated list (up to 8) makes the pet cycle: each entry plays for at least 3 seconds and until its loop finishes, then a different one is picked at random
`WalkAction`	int	-	Animation played while following the owner
`ZenPickup`	0/1	`0`	`1` = walks to nearby dropped zen and collects it, `0` = follow only
`DamageIncrease`	int	`0`	Outgoing attack bonus while equipped
`Absorption`	int	`0`	Incoming damage absorbed while equipped
`HPDrainPerAttack`	int	`0`	HP subtracted per attack while the damage bonus applies
`DurabilityDrain`	int	`0`	Durability lost per damage taken. `0` = never drains

Mount Attributes#

A mount is the same helper item, but the character rides it instead of being followed. The rider sits on the ridden mesh and plays a borrowed ride posture while the mesh plays its own animation pages. Mounts do not grant a castable skill.

Attribute	Type	Default	Effect
`ItemModel`	filename	-	Inventory-icon model in `Data/CustomPets/`
`MountMesh`	filename	-	Ridden animated model in `Data/CustomSkill/`
`RiderStyle`	`uniria` \| `darkhorse` \| `fenrir`	`uniria`	Which borrowed rider posture the character plays
`Speed`	int	`0`	Movement speed while riding. `0` = no boost. For reference, Fenrir is 15-19 and Dark Horse is 17
`Flying`	0/1	`0`	`1` = may enter Icarus and Kanturu 3 without wings (Dinorant/Fenrir behavior). `0` = ground mount, wings still required
`StuckRate`	int	`0`	Flinch chance while ridden, from reflect and defensive hits. `0` = never flinch
`IdleAction` `WalkAction` `RunAction` `CastAction`	int or list	-	Mount-mesh animation pages. Each accepts a comma-separated list; out-of-range values are clamped
`MountOffset`	`"forward,side,up"`	`"0,0,0"`	Shifts the ridden mesh relative to the rider so the saddle lines up under the ride pose

Animation Speed#

Attribute	Applies to	Default
`IdleAnimSpeed`	Pet and mount idle	`0.25` on pets, `0.4` on mounts
`WalkAnimSpeed`	Pet and mount walk	`0.25` on pets, `1.0` on mounts
`RunAnimSpeed`	Mount run	`0.6`
`CastAnimSpeed`	Mount cast	`0.4`

Values are animation frames per server tick. The pet defaults are deliberately conservative - if a pet looks like it is moving in slow motion, raise them (for example IdleAnimSpeed="0.4" WalkAnimSpeed="0.5").

Transparency: BlendMesh and PageModes#

Models imported from other clients often expect their glow pages to be drawn additively. Loaded as-is, those pages render as opaque black boxes.

Attribute	Value	Effect
`BlendMesh`	`-1`	None (default)
	`-2`	Every page additive
	`-3`	Auto: the largest mesh stays solid, every other page additive
	`N`	Page `N` additive
`PageModes`	`"0:opaque,2:additive,5:hidden"`	Per-page override applied on top of `BlendMesh`, for pages 0-15. Modes: `normal`/`opaque`, `additive`/`add`, `hidden`/`hide`. Unlisted pages inherit `BlendMesh`

A typical mixed model is BlendMesh="-2" PageModes="0:opaque" - everything glows except the solid body page.

There is also a no-config alternative: name the model's textures with the _R suffix (for example ghost_R.jpg) and the engine tags them at load time.

Both attributes work on <Pet> and <Mount>.

Item Options#

+Luck, +additional option and +excellent are not configured here. They come from ItemOption against the global index range 6806-6910, in the Custom Pets block appended to that file.

Examples#

<Pet Index="150" Name="Baby Bear" Model="babybear.bmd"
     IdleAction="0,1,3" WalkAction="2" Scale="0.85"
     ZenPickup="1" DamageIncrease="0" Absorption="10"
     HPDrainPerAttack="0" DurabilityDrain="0"
     RequireLevel="10" Durability="255"/>

<Mount Index="155" Name="Ice Dragon"
       ItemModel="icedragon_item.bmd" MountMesh="icedragon.bmd"
       RiderStyle="fenrir" Scale="1" Speed="17" Flying="1"
       IdleAction="0,1,5,6,7" WalkAction="2" RunAction="3" CastAction="4"
       RequireLevel="150" Durability="255" BlendMesh="-3"/>

<Mount Index="158" Name="Fierce Lion"
       ItemModel="fiercelion_item.bmd" MountMesh="fiercelion.bmd"
       RiderStyle="fenrir" Scale="1" Speed="17" Flying="0"
       IdleAction="0,1,5,6,7" WalkAction="2" RunAction="3" CastAction="4"
       RequireLevel="150" Durability="255" BlendMesh="-1"
       MountOffset="-35,0,-10"/>

Important Behavior#

Name length is fatal. A Name over 31 characters stops the GameServer at startup rather than skipping the entry.
Models must exist on both sides. The server only publishes filenames; the client needs the matching model and textures in Data/CustomPets/ (and Data/CustomSkill/ for ridden meshes) or the pet appears invisible.
Flying is enforced server-side. A ground mount does not let a wingless character into Icarus or Kanturu 3 no matter what the client shows.
The rider pose cannot move. It is baked into the player model, so mount alignment is corrected with MountOffset on the mount, never on the character.

Common Issues#

Pet or mount is invisible - model file missing on the client, or the filename in Model/MountMesh does not match the file exactly
Black boxes around a model - additive pages rendered opaque; set BlendMesh="-3", or -2 with PageModes="0:opaque"
Animation looks like slow motion - raise IdleAnimSpeed/WalkAnimSpeed, which default low for pets
Character floats above or sinks into the mount - tune MountOffset (forward,side,up)
GameServer will not start after an edit - a Name longer than 31 characters, or a duplicate Index
No +luck or +option ever rolls - the global index range is not covered in ItemOption