Installation

Installation

This page sets up SpriteMotion for the current UO equipment workflow (Content Studio, Fit Lab and the Blender build). The older reconstruction workflow has extra steps at the end.

What you need

Requirement	Why	How SpriteMotion finds it
Your own Ultima Online client files (legally obtained)	Sprite extraction (original reference sprites), client staging, the outfit lab, region masks and the client-dependent test	SPRITEMOTION_UO_SOURCE = your UO client folder (with anim.mul / anim.idx)
UO_Model3D source folder, v13 (by Levy), obtained separately	The canonical body, rig, 35 actions and reference renderer used by every UO build	Installed once with tools/uo-content/pipeline.py setup --source <folder>
Blender 4.2+ (4.2 LTS and 5.2 LTS tested; 5.2 LTS recommended for new work)	Fit Lab export, all rendering and VD output	SPRITEMOTION_BLENDER, else the newest install under Program Files
Python 3.10+	Everything	On PATH; the project venv goes in .venvs/spritemotion/
Godot 4.7 (optional)	Only for the Sprite Pose Editor	tools/godot/, downloaded by launchers\pipeline\0-setup.bat

No game data is included. SpriteMotion never ships UO client files, extracted sprites, the canonical body scene, commercial asset packs or generated game content. Everything you extract or render stays in the ignored workspace/ and outputs/ folders on your machine.

1. Clone and create the Python environment

Windows (PowerShell):

git clone https://github.com/DatMoshu/SpriteMotion.git
cd SpriteMotion
py -3 -m venv .venvs/spritemotion
.venvs/spritemotion/Scripts/python.exe -m pip install -e ".[test]"

Linux / macOS:

git clone https://github.com/DatMoshu/SpriteMotion.git
cd SpriteMotion
python3 -m venv .venvs/spritemotion
.venvs/spritemotion/bin/python -m pip install -e ".[test]"

The package lives in common/ and imports as spritemotion. Its runtime dependencies are only NumPy and Pillow; [test] adds pytest and jsonschema.

2. Point SpriteMotion at your UO client

This step is required for anything that reads the client. Either edit the one launcher settings file, launchers\_shared\config.bat, and fill in the value after the =:

if not defined SPRITEMOTION_UO_SOURCE set "SPRITEMOTION_UO_SOURCE=<your UO client folder>"

or set an environment variable (an environment variable always wins over config.bat):

setx SPRITEMOTION_UO_SOURCE "<your UO client folder>"

export SPRITEMOTION_UO_SOURCE="<your UO client folder>"

Without it, these will not work: launchers\pipeline\1-extract-uo.bat (sprite extraction), the outfit lab, region masks, and the test that checks the bundled body-400 annotations against your frames. Client staging takes the same folder as --client <client-folder>; it reads from it and writes patched copies elsewhere.

Nothing is copied from the client into the repository.

3. Install the UO_Model3D body (v13)

The current UO equipment workflow is built on UO_Model3D v13 by Levy: the shared body (UO_Body_0x190.blend), its 112-bone rig UO_Rig, the 35 original actions and the reference render/bind/VD tools. The model and its artwork are not in this repository; obtain the source folder separately and extract it.

.venvs/spritemotion/Scripts/python.exe tools/uo-content/pipeline.py setup --source "<extracted-UO_Model3D-folder>"

This installs the scene and its reviewed tools into workspace/ultima-online/canonical-model, keeping source hashes and attribution. It does not use the older v12 archive. Do not run setup while builds are active. Re-running setup with another source folder is also how you roll back to an earlier model version.

4. Blender

Install Blender yourself. If it is not on PATH or in the usual Windows install folder, set SPRITEMOTION_BLENDER to the executable (in config.bat or the environment). A .blend saved by 5.2 may not open correctly in 4.2, so switch a whole project at once.

5. Start the tools

launchers/editor/workbench.bat cc0-starter

sh launchers/editor/workbench.sh cc0-starter

The workbench prepares the CC0 starter lab export if it is missing, then starts Content Studio (http://127.0.0.1:8772) and Fit Lab (http://127.0.0.1:8774). Continue with Quick Tour: Workbench.

Individual launchers:

Windows	Linux / macOS	Opens
launchers\editor\content-studio.bat	sh launchers/editor/content-studio.sh	Content Studio, port 8772
launchers\editor\fit-lab.bat <pack>	sh launchers/editor/fit-lab.sh <pack>	Fit Lab, port 8774
launchers\editor\workbench.bat [pack]	sh launchers/editor/workbench.sh [pack]	Both

The shell launchers use .venvs/spritemotion/bin/python, then python3; set SPRITEMOTION_PYTHON to override. They can be run with sh without changing file permissions. Without the venv you can also run python tools/uo-content/studio.py directly.

All settings

Every setting resolves in this order: environment variable, then launchers\_shared\config.bat, then the built-in default. config.bat is the only launcher file you should edit.

Setting	Default	Purpose
SPRITEMOTION_UO_SOURCE	none	Your UO client folder
SPRITEMOTION_BLENDER	newest Blender under Program Files	Blender executable
SPRITEMOTION_PYTHON	.venvs\spritemotion\Scripts\python.exe	Python for the launchers
SPRITEMOTION_FIT_PACK	none	Default pack for Fit Lab and the workbench
SPRITEMOTION_SIDECAR	../SpriteMotion-Sidecar	Local folder for licensed pack mappings and scripts (never pushed)
SPRITEMOTION_GODOT	tools\godot\Godot_v4.7-stable_win64.exe	Godot for the Sprite Pose Editor
SPRITEMOTION_DATASET	workspace\ultima-online\body-400	Dataset for the pose editor and pipeline launchers
SPRITEMOTION_BLEND, SPRITEMOTION_ARMATURE, SPRITEMOTION_MAPPING	workspace\ultima-online\model.blend, none, Rigify mapping	Reconstruction workflow: your model, its armature and rig mapping
SPRITEMOTION_FRAME_START, SPRITEMOTION_FRAME_STEP	1, 4	Reconstruction timeline: source frame f is keyed at start + f x step
SPRITEMOTION_UO_ANIM_SOURCE	auto	Force mul or uop when extracting

Optional: the reconstruction workflow

For the Sprite Pose Editor and the extract/fit/render/compare loop:

launchers\pipeline\0-setup.bat          :: venv, package, and the checksum-verified Godot 4.7 download
launchers\editor\sample-character.bat   :: try the editor on the procedural sample (no game data needed)
launchers\pipeline\1-extract-uo.bat     :: extract body 400 from your client (needs SPRITEMOTION_UO_SOURCE)

On other platforms run python tools/godot/fetch.py for Godot.

Verify the install

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

Blender tests run when Blender is found; the UO extraction test runs only when SPRITEMOTION_UO_SOURCE is set. Problems? See the FAQ.