> 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/itememitters.md). # ItemEmitters Bone-anchored particle, sprite, effect, and beam emitters for custom items — glows, sparks, flames, and lightning without client changes Attaches ongoing visual emitters to an item worn by a player: a flare that sits on a wing bone, sparks that drip from a sword tip, lightning that arcs between two bones. Each `` row is one spawner anchored to one bone of the item's model. An item can have any number of rows. This complements [CustomItemVisual.xml](/docs/data/plugins/customitemvisual.md) (which controls the model itself — tint, glow color, additive pages) and [ItemPageEffects.xml](/docs/data/item/itempageeffects.md) (which animates the model's own mesh pages). ItemEmitters adds **new** visuals *around* the model. The file is optional. If it is absent or malformed, nothing is emitted and the server keeps running. The server sends the whole table to the client at login; the client does the rendering. ## File Location ``` Data/Plugins/Items/ItemEmitters.xml ``` Loaded once at GameServer startup. ## Dependencies * `Type` / `Index` identify the item, matching [Item.xml](/docs/data/item/item.md). * Delivered to the client at login. A player who is already online needs to re-login to receive changes. * Emitters render wherever the item's 3D model renders — worn on a character, dropped on the ground, and in inventory/shop 3D previews (the same behavior as vanilla wing effects, whose icons twinkle in the inventory). * Emitters respect the wing particle distance limit (`ChromeLOD_MediumDistance` in the client config): distant characters skip them, same as vanilla wing effects. ## Configuration ```xml ``` ### Attributes | Attribute | Required | Default | Description | | ---------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------- | | `Type` / `Index` | yes | — | Item identity (same as Item.xml) | | `Bone` | yes | 0 | Bone index of the item's BMD the emitter is anchored to | | `BoneTo` | joints only | unused | Second bone — the other end of a `joint` beam | | `Kind` | yes | — | `sprite`, `particle`, `effect`, or `joint` (see below) | | `Bitmap` | kind ≠ effect | — | Texture asset name from the catalog below | | `Effect` | kind = effect | — | Effect model name from the catalog below | | `R` `G` `B` | no | 255,255,255 | Color tint, 0–255. Most effect textures are white/grayscale, so this IS the effect's color | | `Scale` | no | 1.0 | Size. Sprites: world size multiplier. Particles/effects: spawn scale. Joints: beam width multiplier | | `Rate` | no | 0 | Milliseconds between spawns. `0` = once per game tick (25/sec). Ignored by sprites (they are cheap per-frame draws) | | `Offset` | no | 0,0,0 | `"x,y,z"` offset from the bone, in the bone's local space | | `Speed` | no | 0 | Sprites only: continuous rotation speed | | `SubType` | no | 0 | Behavior variant of the asset (see catalog notes) | {% hint style="info" %} To find bone indices, wear the item in game and use the `$bones` chat command — it draws every bone with its index over the model. Bone counts differ per BMD; a `Bone` past the model's last bone is silently skipped. {% endhint %} ## Worked example: Wings of Satan The shipped `ItemEmitters.xml` includes a complete example on Wings of Satan (Type 12, Index 2): steady demonic glows at the wing tips, flame licks on the membranes, and embers off the spine. **Step 1 — find the bones.** Wear the item and use the `$bones` chat command, or open the BMD in the [MU Online BMD Viewer](https://github.com/xulek/muonline-bmd-viewer). For `Wing03.bmd`: bones 2/3 carry the right wing, 6/7 the left wing, 0 the spine. **Step 2 — place emitters on those bones:** ```xml ``` Design notes worth copying: * One `sprite` per anchor carries the "always on" identity (cheap, steady, never flickers); `particle` rows add motion on top. * The two flames use **different `Rate` values** (180/230) and different `SubType`s so they never spawn in lockstep — synchronized emitters read as mechanical. * Total budget: two per-frame sprites + \~14 particles/second. Safe even with a dozen players wearing it on screen. **Step 3 — tune in game.** Wear the item, edit numbers, restart GS, re-login. `Scale` on sprites is world size; on particles it feeds each type's own size roll, so expect to iterate. {% hint style="info" %} Weapons work the same way (most weapon BMDs have a single bone 0, so placement is done with `Offset` along the blade axis) — but on **mounted** characters the in-hand weapon renders at the sit pose, which can put it (and its emitters) inside the mount. Prefer wings/armor anchors until that placement quirk is addressed. {% endhint %} ## The four kinds | Kind | What it is | Cost guidance | | ---------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `sprite` | A camera-facing glow quad redrawn every frame at the bone. The standard "shining point" on vanilla wings. Steady, never flickers | Cheapest. Use freely | | `particle` | A spawned puff that lives its own life after spawning (drifts, fades). Smoke, sparkles, embers | Use `Rate` of 100+ ms. Each spawn takes a pool slot | | `effect` | A full 3D effect model instance (thunder bolt, shockwave). Heaviest visual | Use `Rate` of 300+ ms | | `joint` | A textured beam/trail between `Bone` and `BoneTo` (or a flicker at one bone if `BoneTo` is omitted) | One per row is maintained continuously | ## Asset catalog These are the asset names the client accepts. A row with any other name is **dropped at login** and logged to the client console (`[ItemEmitters] Unknown asset name`), so a typo never crashes anything — the emitter just doesn't appear. Family textures accept a `+N` frame suffix (e.g. `BITMAP_SHINY+4`) — different frames are genuinely different pictures, worth previewing in game. ### Textures for `sprite` and `particle` {% hint style="warning" %} **The `+N` frame suffix is for `sprite` rows only.** Sprites are plain textured quads — any frame of a family works. Particles are different: each base name is a particle *type* with its own hardcoded movement/lifetime behavior, and the engine animates the frames itself. A particle row with `BITMAP_FLAME+1` matches no behavior and renders nothing. For `particle` rows: use the **base name** and pick the variant with `SubType` (`BITMAP_SPARK+1` is the one exception — it is its own particle type). {% endhint %} | Name | Variants | What it looks like | | --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `BITMAP_LIGHT` | — | Soft round glow ball. The workhorse — 90% of vanilla wing shine is this with a color tint | | `BITMAP_PIN_LIGHT` | — | Star-shaped glint with rays. Use `Speed` to rotate it | | `BITMAP_SHINY` | `+0`…`+6` | Sparkle/glint family. `+1` small twinkle, `+4` four-point star, `+6` big soft glow | | `BITMAP_SPARK` | `+0`…`+4` | Small hard sparks. `+1` is the classic drifting spark used by weapon effects | | `BITMAP_FLARE` | `+0`…`+1` | Lens-flare style burst | | `BITMAP_FLARE_BLUE` | — | Cold blue flare (tintable) | | `BITMAP_FLARE_RED` | — | Warm red flare | | `BITMAP_FLARE_FORCE` | — | Dense energy flare | | `BITMAP_CLUD64` | — | Wispy cloud puff. The dark-smoke aura on high-tier vanilla wings | | `BITMAP_SMOKE` | `+0`…`+4` | Smoke puffs (particle only — they drift upward) | | `BITMAP_EVENT_CLOUD` | — | Larger rolling cloud | | `BITMAP_FLAME` | `+0`…`+4` (sprite only) | Fire. As a particle use the base name: `SubType 0` = rising flame lick, `6` = faster short flame, `7`/`8` = ember shower | | `BITMAP_TRUE_FIRE` | — | Animated fire (particle; `SubType` 8/9 are the vanilla halloween torch behaviors) | | `BITMAP_ENERGY` | `+0`…`+9` | Energy wisp frames | | `BITMAP_LIGHTNING` | `+0`…`+4` | Lightning flash frames (sprite: use `Speed` for crackle rotation) | | `BITMAP_MAGIC` | `+0`…`+2` | Magic circle/rune glyphs | | `BITMAP_MAGIC_CIRCLE` | — | Full magic circle (looks best as a slow-rotating sprite with `Speed`) | ### Textures for `joint` | Name | What it looks like | | ---------------------- | -------------------------------------------------- | | `BITMAP_JOINT_SPARK` | Spark trail beam | | `BITMAP_JOINT_ENERGY` | Energy ribbon | | `BITMAP_JOINT_THUNDER` | Lightning arc (the vanilla Wings of Storm crackle) | ### Effect models for `effect` | Name | What it does | Useful SubType | | ---------------------- | ------------------------------------- | ------------------------------------ | | `MODEL_FENRIR_THUNDER` | Vertical lightning strike at the bone | `1` = the small wing-crackle variant | | `MODEL_STAR_SHINE` | Twinkling star burst | `0` | | `MODEL_SHOCKWAVE01` | Expanding ground shockwave ring | `0` | | `MODEL_WINDFOCE` | Swirling wind vortex | `2` = the buff-cast swirl | {% hint style="warning" %} The catalog is a fixed allow-list inside the client. If you need an asset that is not listed (there are hundreds more in the client), request it — adding one is a one-line client change, but it ships with the next client build, not with a config edit. {% endhint %} ## Important Behavior * **Rate and smoothness.** `Rate="0"` spawns once per 25Hz game tick — that is the vanilla effect density and frame-rate independent. Millisecond rates are also frame-rate independent. There is no way to spawn faster than once per frame, and no need to. * **Multiple rows stack.** Ten rows on one item = ten emitters running at once. The client's particle pool is shared with everything else on screen (3000 slots) — a crowded event square full of players wearing 20-emitter items will visibly eat the pool. Prefer a few well-placed emitters over bone-spam. * **Joints self-maintain.** A `joint` row keeps exactly one beam alive (it is re-created each tick internally). You do not need `Rate` on joints. * **Color is multiplicative.** `R/G/B` tints the texture. White textures take any color; colored textures (e.g. `BITMAP_FLARE_RED`) mix with the tint. * **No emitters on RF sword-form glove hands?** They work — the client maps the left/right hand models back to the owning glove item automatically. * **Changes need a re-login**, like every login-synced table. `/reload` alone does not refresh what already-online clients render. ## Common Issues | Symptom | Cause | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Emitter never appears | Check the client console for `[ItemEmitters] Unknown asset name` (typo or non-catalog asset), or `Bone` is past the model's last bone (use `$bones`) | | `particle` row accepted but invisible | Used a `+N` frame name (e.g. `BITMAP_FLAME+1`). Particles need the base name + `SubType`; `+N` is sprite-only | | Inventory icon twinkles and I don't want that | Emitters follow the model everywhere, like vanilla wing effects. Prefer subtle `Scale`/`Rate` values for items that sit in shops | | Vanishes when I walk away from another player wearing it | The wing particle distance limit — same behavior as vanilla wing effects | | Whole row list missing after editing the XML | Malformed XML: the file failed to parse and the server synced nothing. Validate the XML | | Effect spam / FPS drop in crowds | Too many `particle`/`effect` rows with `Rate="0"`. Raise `Rate`, or convert steady glows to `sprite` |