How to add support for new visual pets/muuns in the MU client

Visual pets and muuns are one of the strongest customization hooks on a MU Online server: a new critter that follows the character around, with its own effect, becomes a coveted cash shop item or event reward. But "adding a pet" is not a client-only task — it is a two-sided job that has to marry the visuals (model, texture, animation in the client) with the existence and validation of the item (on the server). This advanced guide walks through the entire flow: understanding the .bmd model pipeline, preparing the texture and animation, registering the model in the client, making sure the item exists on the server, and testing the sync. It is technical work, so take it slow and back up at every step.

Prerequisites

• A working, paired server and client. If you do not have that foundation yet, build it first by following the guide on how to create a MU Online server.
• A .bmd import/export tool compatible with your season (3ds Max or Blender plugins, or standalone BMD conversion tools).
• A MU texture converter (.ozj/.ozt/.ozb).
• An image editor (GIMP/Photoshop) for the textures.
• Your emulator's item table editor (ItemList/Item.bmd or equivalent) and access to the server's database/config.
• A backup of the client's Data/ folder and the server's item configs.

The two halves: client and server

Before touching any file, keep this split clear in your head:

If you only do the client half, the pet may show up for you, but the server does not know that item exists — it will not persist in the database, cannot be dropped/purchased correctly, and other players may see nothing. If you only do the server half, the item exists but shows up "invisible" or as a generic model. A complete pet = both halves married together.

How the client renders a pet/muun

MU Online loads 3D models in the .bmd format, which packs mesh, skeleton, animations, and texture references together. Each model has a numeric index that the engine uses to know which file to load when an item or creature needs to be drawn.

The simplified flow (the concept is real; details vary by season/client):

1. The equipped/active item passes a type/index to the engine;
2. The engine maps that index to a .bmd file (e.g., in Data/Item/ or Data/Monster/);
3. The .bmd references textures by name, which the engine looks for in the same folder;
4. The engine plays the appropriate animation (idle, walk) from the skeleton embedded in the .bmd.

Recommended strategy: start from an existing model

Modeling a pet from scratch, exporting it with the correct skeleton and animations, and not crashing the client is hard. The lowest-risk approach is to derive from a muun/pet that already works:

• You guarantee the skeleton and animations are valid (inherited from the original);
• You only swap what gives it a new identity: the texture and, optionally, the mesh;
• The crash risk drops dramatically.

Only move to a fully new model if you have experience with your season's .bmd pipeline.

Step 1 — Prepare the model

Option A: recolor/retexture an existing pet (recommended)

1. Locate the .bmd and textures of the base pet (e.g., an existing muun in Data/...);
2. Back everything up;
3. Convert the .ozt/.ozj texture to .png/.jpg;
4. In the editor, recolor or repaint the texture while keeping the size and UV map layout;
5. Convert back to the original format;
6. If you want a SEPARATE item (not to replace the original), copy the .bmd and the texture with new names/indexes and adjust the internal texture references in the .bmd to point to the new name.

Option B: import a new model

1. Import a .bmd base from your season into the 3D tool (to inherit the skeleton);
2. Replace/adjust the mesh while keeping the rig (bones) compatible;
3. Adjust the UV map for your texture;
4. Export back to .bmd with the same animation pattern;
5. Test the model in isolation before registering it.

Step 2 — Prepare and place the texture

1. Create the texture at the size expected by the UV map (powers of 2 are safest: 128x128, 256x256 — varies by season/client);
2. Use .ozt if you need transparency (cutouts, feathers, cloth); .ozj for solid textures;
3. Name the texture exactly as the .bmd references it;
4. Place the texture in the same folder the engine expects for that model;
5. Confirm in the editor that there is no "dirty" alpha channel that would leave parts invisible.

Step 3 — Register the model in the client

The client needs to associate the item index with your .bmd. How this is done varies:

• Client with an external table: edit the mapping file (e.g., an item/muun table in text or binary) by adding the row for the new index pointing to your .bmd and texture;
• Client with the mapping in the executable: you need the client source or a tool from the distribution to insert the new index.

General steps for the external table case (example, varies by season/client):

1. Open the client's item/model table;
2. Locate the pet/muun index range;
3. Add a new entry with a free index (do not reuse an occupied index, or you overwrite another item);
4. Point the entry to your .bmd and texture names;
5. Save and reload the client.

Step 4 — Create the item on the server

Now the server half. The pet item must exist in the emulator's item table, with the same index/section the client expects.

1. Open your emulator's item editor (ItemList, Item.txt, or a table in the database — varies by emulator);
2. Add the pet item at the same section/index you used in the client;
3. Set its properties: name, whether it is a muun/pet, duration (if temporary), associated bonuses;
4. If the pet grants a stat effect (e.g., an attack/defense bonus), configure that in the server's item/muun effects area;
5. Save and reload the server configs.

Step 5 — Test the sync

1. Generate the item on a test account (via a GM command or a controlled drop);
2. Equip/activate the pet and verify:

• The model shows up correctly (not invisible, not a box, not a T-pose);
• The texture is right (no undue white/black areas);
• The idle and walk animations play;
• The server's effect/bonus is applied;

1. Log in with a second account and confirm that the second player also sees the first player's pet;
2. Log out and back in and verify that the item persists in the database.

The second-account test is decisive: it is what proves the server half is working, not just your customized client.

Common errors and fixes

Distribute the pet to players

Since the visuals live in the client, every player has to receive the new files, otherwise only those with the updated client see the pet.

# Package the pet's new files (PowerShell + 7-Zip)
& "C:\Program Files\7-Zip\7z.exe" a -t7z -mx=9 patch-pet.7z Data\

# Integrity hash to publish
Get-FileHash patch-pet.7z -Algorithm SHA256 | Select-Object Hash

Add the model and texture files to the launcher/updater list so the update reaches everyone automatically. Only release the item in the cash shop or in events after the client patch has been distributed — otherwise players buy a pet nobody can see.

Launch checklist

• Backup of the client's Data/ folder and the server's item configs
• Model derived from a valid season base (skeleton/animations inherited)
• Texture created at the UV map size and in the right format (.ozt/.ozj)
• Texture named exactly as the .bmd references it, in the correct folder
• New index chosen from a free range (no collision with existing pets)
• Model registered in the client (external table or source)
• Item created on the server at a section/index consistent with the client
• Pet effect/bonus configured on the server
• Tested: model, texture, animation, and effect on one account
• Validated with a second account (another player sees the pet)
• Item persists after logout/login
• Client patch distributed via the launcher BEFORE releasing the item
• Custom index spreadsheet updated

Frequently asked questions