docs/website/UOFIDDLER.md

# Extracting from your own UO client (UOFiddler)

**Audience:** the shard operator, once, at setup time.
**Related:** [`SPAWN_ATLAS.md`](SPAWN_ATLAS.md) (where creature art fits),
[`../link/v8.md`](../link/v8.md) (the Asset Bridge, which is replacing this page).

> ### The cliloc conversion is gone — you no longer do this by hand
>
> **Protocol 8, phase 2.** The shard reads its own client's `Cliloc.enu` and
> serves the table over the bridge, so there is nothing to install, convert or
> copy. Press **Admin → Shard → Import** after you patch your client and that is
> the whole procedure; see [`CLILOCS.md`](CLILOCS.md).
>
> Part 1 of this guide has been deleted rather than rewritten. If you already
> have a converted file it keeps working on an install with no uo-link
> configured, but nobody should make a new one.
>
> **Creature art is next** (phase 5), after which this page goes away entirely.

What remains here reads data that **only exists inside a UO client**, and a UO
client's files are EA's, not ours to redistribute. So neither this repo nor any
image we publish can ship them — the operator extracts from **their own** client
and points the site at the result.

| Feature | What it needs | Required? | Without it |
|---|---|---|---|
| **Creature art** ([`SPAWN_ATLAS.md`](SPAWN_ATLAS.md)) | Sprites from `.mul`/`.uop` | No | Atlas pages render as text, which is the normal state |

**It is optional and it is not load-bearing.** A shard that never does any of this
is fully supported.

Everything you extract stays **outside the repository**: `spawnAtlas.art.json` and
`server/uploads/` are gitignored, so none of it can be committed by accident.

---

## Part 0 — Get UOFiddler

[UOFiddler](https://github.com/polserver/UOFiddler) is the community client-file
editor. What is left here uses its GUI to export sprites; the `Ultima.dll` this
guide used to reach for was the cliloc decompressor, and the shard has its own
now.

1. Download the latest release zip from
   <https://github.com/polserver/UOFiddler/releases/latest> — one asset, named
   `UOFiddler-<version>.zip` (4.22.2 is ~2 MB).
2. Extract it. The zip contains a single top-level folder, and the two files that
   matter are at **its root**:

   ```
   UOFiddler-4.22.2/
     UoFiddler.exe     ← the GUI (Part 2 needs this)
     Ultima.dll
     plugins/
     …
   ```

3. **Runtime:** UOFiddler 4.22.2 is built for **.NET 10**, so running
   `UoFiddler.exe` needs the .NET 10 **Desktop** Runtime (Windows only). Install
   from <https://dotnet.microsoft.com/download/dotnet/10.0>.

### Finding your client files

The art files are in your **UO client installation directory**. Look for
`art.mul` / `artLegacyMUL.uop` and the `anim*.mul` set. The EA Classic Client's
default location is:

```
C:\Program Files (x86)\Electronic Arts\Ultima Online Classic\
```

**If your shard distributes its own patched client to players, use that copy** —
it is what your players actually see. (It is also the copy the shard itself reads
from, since a ServUO server resolves `Config/DataPath.cfg` into its own client
path at boot, which is the premise the Asset Bridge is built on.)

---

## Part 2 — Creature art for the spawn atlas (optional)

**Goal:** put sprites on atlas pages. Purely cosmetic — the atlas is fully
functional as text, and `art` is NULL on every fresh import.

**This project ships no art and no art-extraction tooling, and never will.**

1. Open `UoFiddler.exe` and point it at your client directory
   (**Settings → Paths**), then open the
   **Animations** tab for creature sprites — or **Items** for object art — find
   the creature, and export as PNG. Right-click an entry for its export options,
   or use the tab's *Export All* action for a batch. (4.22.2 added an export
   option to the Animation tab's thumbnail list, which is the convenient one
   here.)
2. Put the images under `server/uploads/atlas/`.
3. Copy `server/db/data/spawnAtlas.art.example.json` to `spawnAtlas.art.json` in
   the same directory and map creature slugs to file names:

   ```json
   {
     "lizardman": "lizardman.png",
     "orc": "orc.png"
   }
   ```

   **Keys are the slugs the atlas API reports**, derived from the type names in
   your own shard's `Spawns/*.xml` — read them off the atlas rather than guessing.
   A creature with no entry renders without art, which is the default.

4. Restart, or `npm run atlas:import -- --force`.

The art map is re-read on every atlas refresh, so adding one image is an edit plus
a refresh. Both `spawnAtlas.art.json` and `server/uploads/` are gitignored.

---

## Licensing, briefly

UO's strings and sprites are EA's. Extracting from **your own** client for
**your own** shard is the arrangement here; redistributing the extracted files is
not something this project does or can advise on. That is the whole reason this
page exists instead of a download link.