Skip to content

Refresh README around Content Studio and Fit Lab #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DatMoshu merged 1 commit into from
Oct 3, 2026
Merged

Refresh README around Content Studio and Fit Lab #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 107 additions & 80 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,103 +1,130 @@
# SpriteMotion

**Create new UO content:** the [Content studio](tools/uo-content/README.md) accepts text-configured item templates, pictures and 3D models, mounts equipment on the shared **UO_Model3D v13** rig, renders animations and exports VD plus classic-client import packages. Start with `launchers/editor/content-studio.bat`. This is the active item-authoring workflow; the reconstruction tools documented below remain available as historical research and annotation utilities.
**Create, fit and render equipment for Ultima Online's classic 2D characters.**

Reconstruct editable 3D characters and animations from existing 2D sprites, so
artists can create compatible new animation frames, clothing, and equipment.
SpriteMotion is a local content-authoring toolkit. Bring a 3D item, artwork or a
mapped asset pack into the **Content Studio**, adjust its placement on an animated
body in **Fit Lab**, and use Blender to produce transparent equipment frames and
client import packages. Your models, game data and generated content stay on your
machine.

Classic 2D games drew each character from a few fixed directions. SpriteMotion
reads those frames from a game you own, lets people mark where the joints are,
and fits a 3D rig to those marks. The fitted poses go into Blender, where they
are rendered back through the game's camera and compared with the original
sprites. Each pass through this loop makes the 3D version a little more
faithful. Once it matches, new frames, outfits and weapons can be rendered
from the model and still line up with the original art.
**Status: public development preview.** The tools are available now; fitting and
rendering still need broader animation and in-game validation. This is not yet a
one-click installation or a guarantee that every item fits every animation.

![Sprite Pose Editor on the sample character](docs/images/sample-character-editor.png)
## The tools

## What is in the repository, and what is not

| Included | Not included, ever |
| Tool | What it does |
|---|---|
| Tools: the Sprite Pose Editor (Godot), the Python pipeline, and Blender scripts | Game files, extracted sprites, renders or sprite sheets |
| Per-game **adapters** that read *your* local installation | Models, `.blend` scenes, rigs from a game |
| **Annotations**: joint coordinates, with provenance and fingerprints | Anything under `workspace/` (your local working area) |
| A procedural sample character, drawn by our own script | |

Annotations are numbers: joint positions and a SHA-256 fingerprint of the frame
they were drawn on. They only become useful next to art you extract yourself.
When the art differs from what an annotation was drawn for, the annotation is
reported as a mismatch and not applied. See
[docs/annotation-format.md](docs/annotation-format.md).

## Layout

```text
common/ shared Python package (imports as `spritemotion`); knows nothing about any game
schemas/ JSON Schemas for datasets, skeletons, annotations and game descriptions
tools/sprite-pose-editor Godot 4.7 editor for reviewing and correcting joint annotations
tools/blender/ Blender scripts: export rig/actions, key fitted poses, render every view
tools/godot/ where the Godot executable goes (not committed)
games/<game>/ adapter, profiles, skeletons, bundled annotations, recipes, research
examples/sample-character redistributable procedural character for trying the whole loop
launchers/ Windows .bat launchers (edit launchers/_shared/config.bat only)
tests/ pytest suite (unit + integration, Blender tests when Blender is present)
workspace/ your local data: extracted frames, models, fits, renders (gitignored)
| [Content Studio](tools/uo-content/README.md) | Imports equipment models, applies artwork to templates, configures builds and reviews rendered animations. |
| [Fit Lab](tools/fit-lab/README.md) | Previews mapped parts on the animated body; adjusts slot offset, rotation, scale and binding; tunes body hiding under clothing. |
| [Blender build pipeline](tools/uo-content/README.md#outputs-and-importing) | Produces transparent PNG frames, an editable item scene, VD animation data, review sheets and import packages. |
| [Client staging tools](tools/uo-content/README.md#outputs-and-importing) | Prepare new client files and equipment definitions for review without modifying the source client installation. |
| [Sprite Pose Editor](tools/sprite-pose-editor/README.md) | The earlier reconstruction workflow: annotate original sprites and fit a rig to those measurements. Still available for research and annotation. |

Fit Lab includes undo/redo, a 100-step history, autosave, browser crash recovery
and the previous three disk saves. Enlarged previews can animate and cycle
directions independently, with original UO pixels, a 3D body or content-only views.
It can also load a folder of already fitted, self-contained GLBs. See the
[Fit Lab guide](tools/fit-lab/README.md) for requirements and recovery behavior.

Text input configures equipment templates; pictures supply template artwork.
Neither is an unrestricted text-to-3D or single-image reconstruction system.
Agent-assisted artwork and geometry can enter through the same asset pipeline.

## Start with Content Studio

You need **Python 3.10+**, **Blender 4.2+**, and a separately obtained, compatible
**UO_Model3D** source folder for the current UO equipment workflow. The reference
model and its artwork are not included in this repository. Godot is only needed
for the separate Sprite Pose Editor or a GUO host, not the standalone web tools.

From a checkout, on Windows:

```powershell
py -3 -m venv .venvs/spritemotion
.venvs/spritemotion/Scripts/python.exe -m pip install -e ".[test]"
.venvs/spritemotion/Scripts/python.exe tools/uo-content/pipeline.py setup --source "<extracted-model-folder>"
launchers/editor/content-studio.bat
```

Supported games: [Ultima Online](games/ultima-online/README.md) (classic 2D
client, human male body 400, all 35 actions, 1,680 annotated frames).
Open **http://127.0.0.1:8772**. Choose an equipment type, supply an asset or configure
a template, then make a preview build before attempting a full build. Review the
result across actions and directions before staging it for a client/server test.
Set `SPRITEMOTION_BLENDER` if Blender cannot be found automatically. See the
[Content Studio guide](tools/uo-content/README.md) for model inputs, configuration,
outputs and import limitations.

On other platforms, create and activate a Python environment, run
`python -m pip install -e ".[test]"`, then use the same Python setup command and
`python tools/uo-content/studio.py`.

## Quick start
## Open Fit Lab

Requirements: Python 3.10+, [Godot 4.7](tools/godot/README.md) for the editor,
and [Blender 5.2 LTS or 4.2 LTS](tools/blender/README.md) for reconstruction.
Fit Lab needs a prepared asset-pack mapping, item list and Blender export.
Commercial packs and their pack-specific scripts belong in a private local
sidecar; they are not supplied by the public repository. Follow the
[asset-pack setup guide](docs/asset-packs.md) and [Fit Lab export instructions](tools/fit-lab/README.md)
first, then run:

```bat
launchers\pipeline\0-setup.bat :: creates .venvs\spritemotion
launchers\dev\run-tests.bat
launchers\editor\sample-character.bat :: open the editor on the sample
launchers\dev\sample-loop.bat :: fit -> Blender -> render -> compare, on the sample
launchers\editor\fit-lab.bat <pack>
```

On other platforms, see [docs/getting-started.md](docs/getting-started.md);
every launcher is a thin wrapper around a documented command.
Open **http://127.0.0.1:8774**. The launcher reuses an existing export; it does not
prepare an arbitrary folder of raw models automatically. You can also set
`SPRITEMOTION_FIT_PACK` instead of passing the pack name.

With your own Ultima Online client:
Live previews help compare fits. Their poke-through measurements are approximate
and do not reproduce every Blender holdout or push-out rule. Final rendered frames
and an in-game test are the acceptance checks.

```bat
set SPRITEMOTION_UO_SOURCE=<your UO folder with anim.mul>
launchers\pipeline\1-extract-uo.bat :: extract body 400 and apply the bundled annotations
launchers\editor\sprite-pose-editor.bat
## Published code and ongoing work

The instructions above describe the public `main` branch. More recent fitting
and rendering changes may be on development branches or in
[open pull requests](https://github.com/DatMoshu/SpriteMotion/pulls).

Scoped animation/direction corrections and updated masking are being integrated
through [the fitting improvements PR](https://github.com/DatMoshu/SpriteMotion/pull/1).
A shared Fit Lab inside [GUO](https://github.com/DatMoshu/GodotUO) has been tested
locally; its distribution and fresh-install onboarding are still in development.
Do not assume a SpriteMotion checkout installs the GUO integration.

## What you download

**Included:** Python and Blender tools, the web editors, game adapters, schemas,
annotation data, agent instructions, and a redistributable procedural sample.

**Not included:** UO client files, extracted sprites, the canonical body scene,
commercial asset packs, private mappings, or generated game content. Work files
and renders belong under ignored `workspace/` or `outputs/` directories. Supply
your own permitted inputs; the public code download is not a bundled UO art pack.

To explore the original reconstruction workflow without game assets, use the
[procedural sample and getting-started guide](docs/getting-started.md). The
[reconstruction workflow](docs/reconstruction-workflow.md) and
[annotation format](docs/annotation-format.md) remain documented separately.

## Contributing

Use a branch or fork and submit a pull request. Protected `main` requires the
`guard` and `build` checks and maintainer code-owner approval; administrators
retain a bypass. See [CONTRIBUTING.md](CONTRIBUTING.md) for review and content rules.

```powershell
python -m pytest -q
python -m unittest discover -s games/ultima-online/outfit-lab -q
python tools/agents/run.py --check
```

## Documentation

- [Getting started](docs/getting-started.md): install, launchers, first run
- [Reconstruction workflow](docs/reconstruction-workflow.md): annotate, fit, key, render, compare, iterate
- [Annotation format](docs/annotation-format.md): layers, provenance, fingerprints, review
- [Adding a game](docs/adding-a-game.md): writing an adapter and a profile
- [Sprite Pose Editor](tools/sprite-pose-editor/README.md)
- [Contributing](CONTRIBUTING.md), including how to submit annotations

## Principles

- **Corrections are separate from estimates.** Automatic estimates are
starting points kept in their own layer. Anything a person changed, reviewed
or approved goes in the correction layer. The effective pose is the
correction if there is one, otherwise the estimate.
- **Evidence is labelled.** Every pose records how it was made. Poses
projected from a 3D rig are marked `independent: false`, and fitting refuses
to use them as targets unless explicitly told to. A rig cannot validate
itself.
- **Nothing is guessed.** Annotations are matched to frames by identity and
fingerprint. Mismatches are reported, not silently applied.
- **Overlap is not completion.** Silhouette IoU measures shape agreement, not
anatomy, timing or correctness.
Hosted CI checks the source workflow and package build. It does not certify
proprietary-model rendering or in-game behavior. Include actual render evidence
for fitting changes, and keep private artwork and data out of commits.

## License

Code, schemas, documentation and annotations: MIT, see [LICENSE](LICENSE).
Code, schemas, documentation and annotations: **MIT**, see [LICENSE](LICENSE).
Third-party software is listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
Game names are trademarks of their owners. This project is not affiliated
with or endorsed by them.
Game names are trademarks of their owners. This project is not affiliated with
or endorsed by them.
Loading