FAQ

FAQ and Troubleshooting

Not sure where a problem starts? Follow Troubleshoot a failing step first. For holes and poke-through, see Clean up with masking.

General

Does SpriteMotion include Ultima Online art or client files? No. It ships code, schemas, docs, annotations (coordinates only), a procedural sample and audited CC0 starter items. You supply your own legally obtained UO client and point SPRITEMOTION_UO_SOURCE at it. Everything extracted or rendered stays in ignored workspace/ / outputs/ folders.

Do I need the UO client for Content Studio and Fit Lab? Building and fitting run on the UO_Model3D body, which you install separately. You need the client folder for sprite extraction, client staging (--client <folder>), the outfit lab, region masks and the client-dependent test. Set it up anyway: staging into a client copy and an in-game test are the real acceptance check.

Who made the 3D body? UO_Model3D (v13) is Levy's project. SpriteMotion installs it from a source folder you obtain separately; it is not redistributed here. Levy also contributed the VD tools and outfit-lab export scripts.

Is this a text-to-3D or image-to-3D generator? No. Text configures procedural templates; pictures are applied as artwork to a template. Bring a 3D model for a specific silhouette.

Which Blender version? 4.2+; 4.2 LTS and 5.2 LTS are tested, 5.2 LTS is recommended for new work. Don't mix versions within a project: a .blend saved by 5.2 may not open correctly in 4.2.

Linux / macOS? content-studio.sh, fit-lab.sh and workbench.sh exist and can be run with sh. The .bat pipeline launchers are Windows-only; their underlying Python commands work anywhere. Reports from Linux/macOS testers are very welcome.

Setup problems

"Install the v13 backend first: pipeline.py setup --source <UO_Model3D folder>" Run the setup step from Installation with the extracted model folder.

Blender is not found. Set SPRITEMOTION_BLENDER to the Blender executable, in launchers\_shared\config.bat or as an environment variable.

1-extract-uo.bat stops asking for SPRITEMOTION_UO_SOURCE. Fill in the value in config.bat (after the =) or set the environment variable to your UO client folder (the one with anim.mul / anim.idx).

Extraction reports fingerprint mismatches. Your client's frames differ from those the bundled annotations were drawn on (for example another client version). The report lists the frames; review those poses before using them.

"Not yet supported" during extraction. anim2–anim5.mul, Body.def / Bodyconv.def substitutions and hues are not read yet. The adapter stops with a clear error instead of guessing. You can force mul or uop with SPRITEMOTION_UO_ANIM_SOURCE.

Workbench and Fit Lab

"Port ... has another service or pack. Stop it before launching this workbench." Another program, or Fit Lab with a different pack, holds 8772 or 8774. The workbench never silently replaces it. Stop that process, then relaunch.

Fit Lab says there is no export for my pack. The launcher reuses an existing export; it does not turn a folder of raw models into a pack. For the CC0 starter run python tools/starter-assets/run.py --prepare-lab. For your own pack, create the item list and run python tools/fit-lab/run.py export --pack <pack> (see Asset Packs).

My GLBs are skipped by "Load fitted GLBs from a folder". They must be self-contained and already skinned with the canonical body's bone names. Raw FBX and unrigged objects go through the pack export workflow. Limits: 100 files, 50 MB each. Imports last only for the session.

Saving paused with a conflict message. Another tab or tool changed lab-adjustments.json. Choose Use disk version, or Keep my recovered edits (the disk version is backed up first).

I lost my edits. Check the History tab (last 100 steps) and Restore backup (the last three disk saves in lab-adjustments-backups/). Browser recovery also restores unsaved edits after a reload, unless browser storage was cleared or unavailable.

Poke counts look too high. They are. The metric does not model the renderer's 1 cm holdout margin or 6 mm push-out. Compare runs; don't treat counts as absolutes. Check the Blender render.

The live preview and the Blender render disagree. The Blender render is the final word. The preview lacks push-out and exact-outline edge correction. If you think the render is wrong, that is a gate-1 parity issue worth reporting.

Builds

Holes in the item sprite. The body is a holdout: body geometry in front of the item cuts it out. Turn on Hide body under clothes for the slot, adjust outward/inward distance, or add a small offset/depth correction.

"Rebuild refused" / mixed versions. The model, renderer, source meshes or palette changed since the source build. Make a fresh build.

The fit change didn't show up in an old job. Jobs freeze their mapping and fit at creation. Build again (or Rebuild changed blocks in the lab).

Clipped or empty frames. They are reported in validation, not hidden. Reduce scale or offset for the affected poses, or use a scoped correction for that action/direction.

Client staging

Staging rejects my animation ID. It is occupied. Pick an unused animation ID. The static graphic ID is a different number.

My inventory art doesn't show. artLegacyMUL.uop can shadow MUL art. The tool reports it; use inventory.png with a UOP importer.

The item shows on the male body but not female / not on a mount. Body.def / Bodyconv.def / Equipconv.def rules and female-body conversion are not authored automatically yet. Mounted actions are not yet verified.