Skip to content

feat: Import pets from standardized desktop-pet packages into Character Packages - #118

Merged
omesser merged 15 commits into
mainfrom
import-pet-112
Aug 31, 2026
Merged

omesser merged 15 commits into
mainfrom
import-pet-112

Conversation

@omesser

@omesser omesser commented Aug 31, 2026 •

Copy link
Copy Markdown
Owner

scripts/import-pet.py translates 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 after character::load accepts the output, through the new crates/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/&lt;id&gt;/"] --> F["character::load<br/>via examples/validate.rs"]
Loading

Two adapters, one pipeline.

  • petscodex: atlas detection ported from petdex's sprite-atlas.ts (v1/v2, integer-scaled variants), the issue's row mapping, waiting as an idle variant_of ring member, row fps from round(frames * 1000 / durationMs).
  • shimeji: actions.xml pose 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.
  • Shared emit: a defringe pass strips the matte halo a generator leaves around the silhouette (tinted pixels near the body adopt their nearest untinted opaque neighbor, far or dark ones just lose the tint; a pet that is simply green is recognized by its opaque body and left alone), and smooth resampling runs premultiplied so nothing hiding under alpha zero smears back into view; frames register to their animation's first frame in both axes by solid-pixel overlap (the per-cell jitter generated sheets bake in becomes body wobble if kept), then the animation plants its collective baseline on the canvas bottom (the Take BMO from the shimejishop pack, and let art declare smooth rendering #96 floating-sit lesson) — per-frame planting would jerk the body whenever the feet tuck mid-stride, so only a frame left floating visibly (a curled-up pose in a row of sitting ones) grounds itself; petscodex cells also shed small fragments glued to a vertical cell edge, the neighbor frame's art crossing the sheet's grid line. One resample factor lands the sprite in the shimeji band (~100–130 px), render_mode is 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.
  • License gate: the tool prints the pet's license and refuses a silently-unknown one without --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 runs cargo run -p ai-buddy-core --example validate).

# 0. The venv with Pillow
uv venv
uv pip install pillow

# 1. Pick a pet — the catalog is `npx petscodex list`
npx petscodex install labubu

# 2. Import it (petscodex packs declare no license, so accept explicitly)
.venv/bin/python scripts/import-pet.py ~/.codex/pets/labubu --format petscodex \
    -o characters/labubu --accept-license

# 3. Eyeball the frames under characters/labubu/frames/, then run it
cd src-tauri && AI_BUDDY_CHARACTER=labubu cargo run

Sampled so far — all four import and validate:

pet command result
cat --stand 100 --map sleep=5:2 committed here as characters/cat/; sleep is the failed row's curled-up pose, stands 100 px
labubu defaults 128x132, smooth, walk heads right
tiga defaults 103x125, smooth, walk heads right
hachiware --walk-row 1 --mirror-walk 117x125; its row 2 mixes camera angles, so mirror the clean row 1
tom --map sleep=6:2,3 --map react=7 --map hold=5:5,6 --map fall=5:5,6 --map land=6:0 its "jumping" row is a sword lunge and its sleeping art lives in "waiting", so --map recuts them; walk is the default row

What 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 shimeji and a pack directory or zip.

--force replaces an existing output directory on re-import.

The cat, the acceptance import

characters/cat/, from the installed npx petscodex install cat package: 45 frames on a 113x110 canvas (--stand 100), smooth at scale 1, all nine required animations plus the waiting ring, sleep recut from the failed row's curled-up pose (--map sleep=5:2), and a hand-written personality.txt — the importer deliberately writes none.

Cat animation set

The sanity import caught a real defect, and sampling three more pets settled it: every pet sampled draws petdex's running-right row heading left, so the importer defaults walk to row 2 (the one drawn heading right). --walk-row picks the other row and --mirror-walk flips it, for pets like hachiware whose only clean walk heads left. The tool tells the operator to eyeball walk direction on every import.

Walk rows compared

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-test
  • cargo test --all-targets (298 green — cat joins the shipped-characters test) and node --test tests/ (6)
  • The Try it section above, with any pet from npx petscodex list

🤖 Generated with Claude Code

@omesser omesser changed the title Import pets from standardized desktop-pet packages into Character Packages feat: Import pets from standardized desktop-pet packages into Character Packages Aug 31, 2026
omesser and others added 15 commits August 31, 2026 19:21
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
omesser merged commit 4a36466 into main Aug 31, 2026
2 checks passed
@omesser
omesser deleted the import-pet-112 branch August 31, 2026 16:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant