Repository navigation
feat: Import pets from standardized desktop-pet packages into Character Packages - #118
Merged
Merged
Conversation
This was referenced Aug 31, 2026
scripts/import-pet.py translates a pet once into a reviewed, hand-tunable Character Package; characters/cat is its first import (#112). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Every pet sampled (cat, labubu, tiga, hachiware) draws petdex's running-right row heading left. --walk-row picks the other row and --mirror-walk flips it for the pet whose only clean walk heads left. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Generated sheets place the character a few pixels differently in every cell, which played back as bobbing and sideways drift; and their row semantics are labels each pet interprets loosely — one pet's jumping row is a sword lunge. Every frame now plants its lowest pixels on the canvas bottom (the #96 recipe) and registers to its animation's first frame by solid-pixel overlap; --map recuts any animation from the row a pet actually drew. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per-frame bottom planting turned every mid-stride foot tuck into body jerk. Frames now register to their animation's first frame by overlap in both axes, the animation grounds as a unit, and only a frame left floating visibly grounds itself. petscodex cells also drop the fragments a neighboring frame leaves across the grid line. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Generated pets are cut off a colored background: the fringe, a one-pixel rim, and even whisker strokes keep the matte's tint, and a straight-alpha resample smears what hides under alpha zero back into view. Matte-tinted pixels near the body adopt their nearest untinted opaque neighbor, ones too far or too dark just lose the tint, resampling goes premultiplied, and a pet that is simply green is recognized by its opaque body and left alone. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…nality --stand names the on-screen height, --map sleep=5:2 takes the curled-up eyes-closed pose the failed row carries, and personality.txt is written by hand — a pet description is provenance, not a voice. Python bytecode joins .gitignore, and a committed pycache leaves. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
cargo reruns build scripts only for changes it is told to watch, so a package imported into characters/ sat invisible while the app searched a stale copy in target/debug/characters. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
omesser
force-pushed
the
import-pet-112
branch
from
August 31, 2026 16:22
3f775a1 to
286e2e7
Compare
This was referenced Aug 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
scripts/import-pet.pytranslates a pet from a standardized desktop-pet ecosystem into a Character Package once — frames, TOML manifest, provenance header — ready for review and hand-tuning (#112). Not a runtime dependency and not a live bridge: the output is ours. It is the one script allowed to need Pillow (webp rules out the stdlib), and it declares success only aftercharacter::loadaccepts the output, through the newcrates/core/examples/validate.rs.The importer
flowchart LR A["petscodex pack<br/>pet.json + spritesheet.webp"] -->|"--format petscodex"| C B["Shimeji-ee pack<br/>shime*.png + actions.xml"] -->|"--format shimeji"| C C["animations<br/>frames, fps, loop, variant_of"] --> D["emit<br/>align, resample, render_mode"] D --> E["characters/<id>/"] --> F["character::load<br/>via examples/validate.rs"]Two adapters, one pipeline.
sprite-atlas.ts(v1/v2, integer-scaled variants), the issue's row mapping,waitingas an idlevariant_ofring member, row fps fromround(frames * 1000 / durationMs).actions.xmlpose sequences mapped by the Take BMO from the shimejishop pack, and let art declare smooth rendering #96 defaults (Stand→idle, Bouncing→land, Pinched→hold, …), every frame mirrored to head right, fps from pose Duration ticks, and a standard-conf fallback for the bare-PNG packs shimejishop distributes.render_modeis detected from partial alpha and palette size, sleep is synthesized from idle's stillest frame plus a one-pixel breath where the source has none, and a starter behavior set is copied from BMO's.--accept-license; the provenance header records ecosystem, pet id, URL, and mapping.Try it
Prerequisites: a uv venv with Pillow (never a system Python — the script says so itself if Pillow is missing) and a working
cargo(validation runscargo run -p ai-buddy-core --example validate).Sampled so far — all four import and validate:
cat--stand 100 --map sleep=5:2characters/cat/; sleep is the failed row's curled-up pose, stands 100 pxlabubutigahachiware--walk-row 1 --mirror-walktom--map sleep=6:2,3 --map react=7 --map hold=5:5,6 --map fall=5:5,6 --map land=6:0--maprecuts them; walk is the default rowWhat to look for after any import: walk must head right (the engine mirrors leftward travel), every pose should sit on the ground line, and every animation must read as its name — the row semantics are labels each generated pet interprets loosely, and
--map animation=row[:frames]recuts one from the row this pet actually drew (recorded in the manifest header). Sleep stays the synthesized idle pair until hand-tuned or remapped. A shimeji pack works the same way with--format shimejiand a pack directory or zip.--forcereplaces an existing output directory on re-import.The cat, the acceptance import
characters/cat/, from the installednpx petscodex install catpackage: 45 frames on a 113x110 canvas (--stand 100), smooth at scale 1, all nine required animations plus thewaitingring, sleep recut from the failed row's curled-up pose (--map sleep=5:2), and a hand-writtenpersonality.txt— the importer deliberately writes none.The sanity import caught a real defect, and sampling three more pets settled it: every pet sampled draws petdex's
running-rightrow heading left, so the importer defaults walk to row 2 (the one drawn heading right).--walk-rowpicks the other row and--mirror-walkflips it, for pets like hachiware whose only clean walk heads left. The tool tells the operator to eyeball walk direction on every import.Hand-tuning worth doing later (#122): the landing burst is kept deliberately — revisit if it reads as damage rather than impact. The sleep half of #122 is resolved here by
--map sleep=5:2.The BMO re-import check
The same tool imports the shimejishop BMO zip (46 bare shime PNGs, no conf) through the standard-conf fallback, and the result validates: 123x120 vs the hand-built 126x128, same required set plus climb. The differences are exactly #96's hand-tuning — sing/skate/ballwalk variants and hand-picked talk/sleep frames. Checked in a scratchpad, not committed: the repository needs one BMO.
Left out, deliberately
The contact-sheet fallback for convention-less formats (#121), and adapters beyond these two — eSheep/ScreenMate descendants and VPet were noted as candidates, not surveyed in depth.
Verify
.venv/bin/python scripts/import-pet.py --self-testcargo test --all-targets(298 green — cat joins the shipped-characters test) andnode --test tests/(6)npx petscodex list🤖 Generated with Claude Code