> 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/custompets.md). # CustomPets Custom pets and rideable mounts with bespoke models, animations, and combat bonuses 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 ```xml ``` 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 `` and ``. ## Item Options `+Luck`, `+additional option` and `+excellent` are **not** configured here. They come from [ItemOption](/docs/data/item/itemoption.md) against the global index range `6806`-`6910`, in the Custom Pets block appended to that file. ## Examples {% tabs %} {% tab title="Zen collector pet" %} ```xml ``` {% endtab %} {% tab title="Flying mount" %} ```xml ``` {% endtab %} {% tab title="Ground mount with saddle fix" %} ```xml ``` {% endtab %} {% endtabs %} ## 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](/docs/data/item/itemoption.md)