Repository navigation
Description
Goal
A one-time importer: point it at a pet from a standardized desktop-pet ecosystem, get a complete ai-buddy Character Package — frames, TOML Character Manifest (animations, render_mode, scale, variant_of rings), provenance header — ready for review and hand-tuning. Not a runtime dependency and not a live bridge; it translates once and the output is ours.
Format 1, fully specified: petscodex / petdex
crafter-station/petdex with the gallery at petscodex.com. npx petscodex install cat lands a package at ~/.codex/pets/<id>/:
pet.json—{ id, displayName, description, spritesheetPath }. Nothing else; all pose semantics are conventions in the consuming code.spritesheet.webp— a fixed grid: 8 columns of 192x208 cells, 9 rows (atlas v1) or 11 (v2), integer-scaled variants accepted. Layout detection:src/lib/sprite-atlas.ts. Row semantics:src/lib/pet-states.ts, verbatim:
| row | state | frames | duration | purpose |
|---|---|---|---|---|
| 0 | idle | 6 | 1100ms | breathing/blinking loop |
| 1 | running-right | 8 | 1060ms | locomotion right |
| 2 | running-left | 8 | 1060ms | locomotion left |
| 3 | waving | 4 | 700ms | greeting |
| 4 | jumping | 5 | 840ms | anticipation, lift, peak, descent, settle |
| 5 | failed | 8 | 1220ms | sad/error reaction |
| 6 | waiting | 6 | 1010ms | patient idle variant |
| 7 | running | 6 | 820ms | in-place run |
| 8 | review | 6 | 1030ms | focused inspecting |
v2's rows 9–10 are newer than that table — read the current pet-states.ts (and pet-sprite.tsx) at import-tool-writing time.
Proposed mapping to the Required Animation Set
idle← row 0;waiting(row 6) becomes avariant_of = "idle"ring member.walk← row 1 (already heading right, the Engine's default;Frame.facingmirrors left — row 2 is discarded, or diffed against a mirrored row 1 as a sanity check).fall← rows 4's peak/descent frames;land← descent/settle,loop = "once".react← row 5 (or its first frames,loop = "once").talk← row 3 (waving reads as addressing you).sit← row 8 (review: sitting still, focused).sleep← synthesized: idle's stillest frame, dimmed or duplicated with the 1px breath — petdex v1 has no sleep.hold← jumping's lift frame pair, or failed's first two.climb— skip; it is optional and falls back to walk.
Frame durations map to fps: round(frames * 1000 / durationMs), clamped to our bounds.
Format 2, proven by hand: shimeji packs
BMO (#96) was imported manually from a 46-frame shimeji pack. The importer should automate that recipe: per-frame PNGs with conventional numbering plus each pack's actions.xml/behaviours.xml (Shimeji-ee) naming pose sequences — a richer source of pose semantics than numbering alone. The BMO import is the reference for every mechanical step.
The survey
Before building, a short scan of what else follows a standard worth an adapter: Shimeji-ee (large community, XML behaviors), petscodex (above), and whatever else has both a gallery and a fixed convention (eSheep/ScreenMate XML descendants, VPet). One adapter per format behind one importer; formats without a machine-readable convention are out of scope, and get no import path at all. The contact sheet and skeleton manifest this sentence once promised were built (#147), driven, and rejected: see ADR-0009 and #121.
Importer shape
scripts/import-pet.py <source-dir-or-zip> --format petscodex|shimeji -o characters/<id>/. One-time authoring tool, not a build step, so Pillow is acceptable here (document that it is the one script allowed to need it — decoding webp rules out stdlib).- Output frames as PNG on a uniform per-Character canvas. Crop to the per-animation union bbox so registration survives; align each ANIMATION's collective baseline to the canvas bottom (per-row minimum margin — never per-frame, which would flatten a jump). The floating-sit bug fixed in Take BMO from the shimejishop pack, and let art declare smooth rendering #96 is the cautionary tale.
- Emit TOML with
render_mode = "smooth"for drawn/AA art (detect: color count or alpha histogram),"pixelated"plus a quantisation pass for true pixel art (the ADR-0006 recipe); pickscalefrom cell size so the on-screen sprite lands near shimeji size (~100–130 logical px). - Every output validated by
character::loadbefore the tool declares success; bounds (frame side, total pixels, package size) enforced by the loader already. - Provenance: manifest header names the source ecosystem, pet id, and URL. petdex carries per-pet licenses (
pet_licensein its schema; surfaced in the gallery) — the importer must print the license and refuse silently-unknown ones without--accept-license. Imported characters are development assets unless their license says otherwise; README's attribution section gets a line per import.
Acceptance
import-pet.py ~/.codex/pets/cat --format petscodexproducescharacters/cat/that loads, plays all nine required animations, and looks right in the app (idle ring with waiting, walk mirrored both ways, jump-derived fall/land).- The same tool re-imports BMO from its shimeji pack and produces a package equivalent to Take BMO from the shimejishop pack, and let art declare smooth rendering #96's hand-built one (same mapping decisions recorded as the shimeji adapter's defaults).
Activity
omesser commentedon Aug 31, 2026
Plan
Two PRs exist for this issue. The plan below reconciles them and scopes what stays open. Nothing merges or closes until the owner verifies.
The shape
flowchart LR P["petscodex pack<br/>pet.json + spritesheet.webp"] -->|"--format petscodex"| M S["Shimeji-ee pack<br/>shime*.png + actions.xml<br/>(standard conf when absent)"] -->|"--format shimeji"| M M["common shape<br/>animations: frames, fps, loop, variant_of"] --> G{"license known<br/>or accepted?"} G -->|no| X["refuse without --accept-license"] G -->|yes| E["emit: per-animation union bbox,<br/>collective baseline to canvas bottom,<br/>one resample into the shimeji band,<br/>render_mode from alpha + palette"] E --> O["characters/<id>/"] --> V["character::load<br/>(examples/validate.rs)"] V -->|errors| K["fail, keep output for inspection"] V -->|ok| R["human review: walk heads right?<br/>sleep reads as sleep?"]The two decisions no code can make stay human: walk facing (petdex rows render as drawn and pets disagree with the row labels — the real cat draws
running-rightheading left) and whether synthesized sleep reads as sleep. The tool ends every import by saying so.The PRs, read against the acceptance criteria
#114 (petscodex only, synthetic fixture; self-declares "does not close it"): the row mapping, fps clamp, per-animation union bbox, and license gate are right, and the
KNOWN_LICENSESallowlist is a good idea worth stealing. It stops short of the acceptance scenario, and four defects mean its cat would not look right in the app:detect_render_modebuilds a set of byte values (≤256 always, so every import ispixelated— the cat's smooth art misdeclared);choose_scalecan only upscale, so 192x208 cells land at ~200 logical px with no resample path; no walk-facing handling (the cat moonwalks); and nocharacter::loadrun per import, which this issue requires. Itstests/test_import_pet.pyis executed by no runner in CI, and its fixture manifest references bare filenames where shipped packages useframes/.#118 (both adapters): covers the petscodex acceptance scenario with the real installed cat committed under
characters/(loads through the existing shipped-characters test and the newvalidateexample), the shimeji adapter with the #96 defaults, mirroring, and a standard-conf fallback verified against the actual shimejishop BMO zip, the license gate, provenance headers, README attribution, and a--self-test. Remaining gaps are recorded in its description.Disposition proposed: merge #118, close #114 as superseded, and port #114's one steal — the known-license allowlist — as a small follow-up to the gate (today #118 only distinguishes declared from undeclared; an allowlist would auto-accept MIT/CC0-class licenses and still stop the rest).
What stays open after #118 (sub-issues)
eSheep/ScreenMate descendants and VPet get adapter tickets when someone actually wants a pet from them, not before.
Import pets from petscodex and shimeji packs into Character Packages
omesser commentedon Aug 31, 2026
Done via #118 (merged): both adapters behind scripts/import-pet.py, characters/cat as the acceptance import (all nine required animations plus the waiting ring, validated by character::load, in the shipped-characters test), and the BMO re-import checked against the real shimejishop zip. What grew beyond the issue during testing: --walk-row/--mirror-walk, --map row remapping, --stand sizing, matte defringe, per-frame registration with collective grounding, cell-edge bleed stripping, and a build.rs watch so fresh imports are found on the next run.
Remaining scope lives in the sub-issues: #121 (contact-sheet fallback for convention-less packs), #122 (cat's landing-burst call — its sleep half is resolved), #130 (license allowlist for the gate).
omesser commentedon Aug 31, 2026
Edited one sentence in the body, in "The survey". It promised something this repo has now decided against, and a closed issue that states a withdrawn promise is worse than one that states the decision.
Before:
After:
Why it changed, 2026-09-01: #121 tracked that promise and #147 built it. An agent drove the finished flow end to end. It completes, and against the source pack's own
conf/actions.xml— which the flow never reads — three of the nine Animations were filled from art meaning something else:landfrom pull-up-over-an-edge frames,sleepfrom a Tripping frame,reactfrom three ceiling-cling frames that read as nothing. The badreactpassedcharacter::loadclean, and only rendering the package and looking at the sprite caught it.A flow whose failure mode is a Character that validates and is wrong costs more than no import path. A source gets a real adapter that knows its pose semantics, or it gets nothing. Recorded in ADR-0009 (#157); #121 closed
wontfix; #147 closed unmerged with its branch kept.Nothing else in this body changed, and this issue stays closed.