Guide Troubleshooting

Guide: Troubleshoot a failing step

Goal: when something in SpriteMotion breaks, find which layer failed (install, servers, export, fit, render, staging), read the right log, fix it, and if it is a bug, file an issue that can be reproduced.

The FAQ lists individual errors and their fixes. This guide is the order to check things in.

Prerequisites

• A terminal in the repository root.
• The Python environment from Installation (.venvs\spritemotion).

Steps

1. Run the test suite

.venvs\spritemotion\Scripts\python.exe -m pytest -q

Or launchers\dev\run-tests.bat. This checks schemas, tools and, when Blender is found, headless Blender runs. A failure here points at the install, not at your item.

Result	Meaning
All pass	the install is fine; go to step 2
Blender tests skipped	Blender wasn't found: set SPRITEMOTION_BLENDER
UO extraction test skipped	SPRITEMOTION_UO_SOURCE isn't set (only needed for extraction and client staging)
Import errors	the virtual environment is missing or stale: redo Installation step 1

2. Check Blender on its own

launchers\dev\blender-smoke.bat

It runs Blender headless (rig export, camera projection, render placement) and writes to workspace\blender-smoke. If it fails, every build will too. Usual cause: the wrong Blender (4.2 or newer is needed; the female pose scene needs 5.2).

3. Check the servers

Tool	Default address	Start with
Content Studio	http://127.0.0.1:8772	launchers\editor\content-studio.bat
Fit Lab	http://127.0.0.1:8774	launchers\editor\fit-lab.bat <pack>
Both		launchers\editor\workbench.bat <pack>

If a page doesn't load, read the terminal that started the server. Port … has another service or pack means another program, or Fit Lab with a different pack, holds the port. Stop it, or serve on another port:

python tools/fit-lab/run.py serve --pack <pack> --port 8790

4. Find the failing layer

Symptom	Layer	Look at
Fit Lab has no items, or "no export for this pack"	export	workspace/ultima-online/fit-lab/<pack>/manifest.json; rerun run.py export --pack <pack> --force
An item is missing after a mapping change	export	the export is reused until you pass --force
Save status turns red or shows a conflict	fit	the message itself; see conflicts
The preview looks fine, the render doesn't	render	the Blender render is the final word: masking guide
A build fails	render	the job's build.log
Frames clipped or empty	render	the job's validation.json
A rebuild refuses	render	the model, renderer, meshes or palette changed: build fresh
The client rejects the item	staging	the staging report: occupied IDs, UOP shadowing (FAQ)

5. Read the job folder

Every build has workspace/ultima-online/content-studio/jobs/<id>/:

File	Tells you
status.json	state and error message
build.log	Blender's full output; search for Error or Traceback
job.json	the exact settings and the frozen fit the job used
scene-report.json	the model, camera and canvas used, plus the resolved fit, body masking mode and hidden body faces per block
validation.json	per-frame alpha and anchor checks

job.json answers most "why didn't my change show up" questions: jobs freeze their fit and mapping when they start.

6. Undo damage to a fit

• History tab: the last 100 steps; click one to go back.
• Restore backup (History tab): the last three disk saves, from lab-adjustments-backups/.
• Browser recovery restores unsaved edits after a reload, unless browser storage was cleared.

7. Report a bug

If the steps above point at SpriteMotion, open an issue with:

• what you did, what you expected, and what happened;
• the OS, Blender version and commit (git rev-parse --short HEAD);
• the error lines from build.log or the terminal;
• a screenshot using the CC0 starter or your own models.

Expected output

The failing layer identified, the fix applied, and pytest plus a preview build passing again; or an issue with enough to reproduce it.

Common mistakes

• Posting client art or commercial-pack renders in an issue. Don't: reproduce with the CC0 starter. Also remove machine paths (your user folder, your games folder) from logs before pasting them.
• Debugging the item before the install. Run step 1 first; a missing Blender looks like a broken item.
• Two servers on one pack. Two Fit Lab tabs or servers saving the same pack cause conflicts. Use one.
• Deleting workspace/ to start over. It holds your exports, fits, backups and jobs. Remove one job or one export instead.