Skip to content

Import pets from standardized desktop-pet packages into Character Packages #112

Closed
3 of 3 issues completed

Description

@omesser

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 a variant_of = "idle" ring member.
  • walk ← row 1 (already heading right, the Engine's default; Frame.facing mirrors 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); pick scale from cell size so the on-screen sprite lands near shimeji size (~100–130 logical px).
  • Every output validated by character::load before 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_license in 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 petscodex produces characters/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

  1. omesser commented on Aug 31, 2026

    @omesser
    OwnerAuthor

    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/&lt;id&gt;/"] --> 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?"]
    
    Loading

    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-right heading 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_LICENSES allowlist 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_mode builds a set of byte values (≤256 always, so every import is pixelated — the cat's smooth art misdeclared); choose_scale can only upscale, so 192x208 cells land at ~200 logical px with no resample path; no walk-facing handling (the cat moonwalks); and no character::load run per import, which this issue requires. Its tests/test_import_pet.py is executed by no runner in CI, and its fixture manifest references bare filenames where shipped packages use frames/.

    #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 new validate example), 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)

    1. Contact-sheet fallback for convention-less packs — the one sentence of this issue with no counterpart in either PR.
    2. Hand-tune the imported cat — sleep from the react row's curled pose; a look at land's impact burst.

    eSheep/ScreenMate descendants and VPet get adapter tickets when someone actually wants a pet from them, not before.

  2. omesser commented on Aug 31, 2026

    @omesser
    OwnerAuthor

    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).

  3. omesser commented on Aug 31, 2026

    @omesser
    OwnerAuthor

    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:

    One adapter per format behind one importer; formats without a machine-readable convention are out of scope — for those the tool emits a numbered contact sheet and a skeleton manifest for a human (or an agent with eyes) to categorize.

    After:

    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.

    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: land from pull-up-over-an-edge frames, sleep from a Tripping frame, react from three ceiling-cling frames that read as nothing. The bad react passed character::load clean, 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.

  4. added this to the V1 milestone on Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified, ready for an AFK agent

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions