From ec5ff0d8386264bc6430ffb6d20f883a9d6dc7c3 Mon Sep 17 00:00:00 2001 From: Moshu <1709219+DatMoshu@users.noreply.github.com> Date: Sat, 3 Oct 2026 09:14:47 -0500 Subject: [PATCH] Describe current content authoring workflow in public README --- README.md | 187 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 107 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index fbb1071..3095357 100644 --- a/README.md +++ b/README.md @@ -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// 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 "" +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 ``` -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= -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.