Contributing

Contributing

SpriteMotion welcomes code, annotations, CC0 content, research notes and test reports. The authoritative rules are in CONTRIBUTING.md; this page is the practical version.

• Issues: https://github.com/DatMoshu/SpriteMotion/issues
• Discussions (questions, ideas, "I'd like to take this"): https://github.com/DatMoshu/SpriteMotion/discussions
• What needs doing: UO Parity Roadmap

Development setup

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]"

For anything that renders you also need Blender and the UO_Model3D v13 setup; for anything that reads the client, SPRITEMOTION_UO_SOURCE. See Installation. Pure Python, schema and web-UI work often needs neither.

The three required checks

Run these before you open a pull request:

.venvs\spritemotion\Scripts\python.exe -m pytest -q
cd games\ultima-online\outfit-lab; ..\..\..\.venvs\spritemotion\Scripts\python.exe -m unittest -q
python tools/agents/run.py --check

1. pytest: unit, integration and repository-guard tests. Blender tests run when Blender is found; the UO test runs when SPRITEMOTION_UO_SOURCE is set.
2. outfit-lab unittest: the outfit-lab and VD writer tests.
3. agent router check: the generated agent routers are current with CLAUDE.md and .claude/skills/.

Also: launchers\dev\editor-tests.bat if you changed the Godot editor. In your PR, say what you verified and what you did not. Blender-side changes (tools/uo-content, tools/fit-lab) need a headless Blender run, not only a syntax check. Fitting changes need actual render evidence (SpriteMotion output only).

Pull requests

Work on a branch or fork and open a PR against main. Merging needs the guard and build CI checks plus a code-owner approval; new commits dismiss stale approvals. Hosted CI covers repository guards, packaging and tests; it does not certify proprietary-model rendering or in-game behaviour.

Never commit

tests/integration/test_repository.py fails on most of these, but please don't rely on it.

Never commit	Why / where it goes instead
Game data: .mul, .uop, .idx, extracted frames, renders of game art, models or .blend scenes derived from a game	Copyright. Keep it in ignored workspace/ or outputs/.
Images under games/	Guarded by the tests
Licensed third-party assets, their mappings and pack-specific scripts	Your local sidecar (SPRITEMOTION_SIDECAR), which is never pushed
Machine paths (drive-letter paths into a user profile, games or repos folder)	Use repository-relative paths, config.bat, SPRITEMOTION_* variables or CLI options

The CC0 starter models in examples/cc0-starter are the audited exception, with their licenses and provenance hashes. Screenshots in issues must show SpriteMotion output only, never original client art.

Code rules

• Python 3.10+. common/ uses only the standard library, NumPy and Pillow, and knows nothing about any game; game logic goes in games/<game>/, loaded through game.json.
• Blender scripts run in Blender's bundled Python (no Pillow: import it lazily), take arguments after --, work under blender -b --factory-startup, and guard main() with if __name__ == "__main__":.
• New data files get a schema in schemas/; extend a schema and its doc before emitting a new field.
• New tools go in tools/<job>/ with an entry point (run.py); no loose scripts. Launchers call launchers/_shared/common.bat first and use CRLF.
• Add a test with each behaviour change.

Annotations

Annotations (2D joints on sprite frames) are the main shared asset of the reconstruction workflow.

1. Extract frames from your own client: launchers\pipeline\1-extract-uo.bat.
2. Correct poses in the Sprite Pose Editor; tick Pose approved only after checking every joint.
3. Promote reviewed corrections into the bundle:

   .venvs\spritemotion\Scripts\python -m spritemotion promote workspace\ultima-online\body-400 ^
       --bundle games\ultima-online\annotations\body-400 --sequences action-000

4. Run python -m spritemotion validate and the tests, then open a PR saying which sequences and directions you reviewed.

Good first issue areas, by skill

Skill	Ideas
Blender / Python	Use proposed_target rig bones (twist, fingers, shield, cloak/skirt chains) in pack_fit.py; a procedural Blender regression scene for CI; renderer-vs-lab comparison cases for gate 1.
Web UI (JavaScript)	Fit Lab and Content Studio usability, accessibility and keyboard handling; preview-vs-render difference labelling; keep fit-rules.mjs in parity with the Python rules.
UO file formats	anim2–anim5.mul, Body.def / Bodyconv.def / Equipconv.def routing, hues, UOP staging; verifying the untested outfit-lab options.
3D art / CC0 items	Better CC0 starter items per slot (the current accessories are basic fitting examples), with license and provenance.
Testing on Linux / macOS	Run the .sh launchers and the install from a clean checkout; report what breaks.
In-game testing on a shard	Stage a full build into a copy of your client, equip it on your own test server, record walk/combat/cast/death/mount/turn. This is gate 5 and the most valuable proof we lack.
Annotation review	Approve more body-400 poses, especially two or more directions of the same frames.
Docs	Fix anything on this wiki that didn't match what you saw.

Research notes

Findings about a game's projection, conventions or animation quirks go in games/<game>/research/. State what was measured, how, and how confident you are; label candidates as candidates, and give the method next to every number.