Skip to content

Contact-sheet fallback: an on-ramp for pets from convention-less packs #121

Closed

Description

@omesser

Part of #112.

Why

#112's importer covers the two ecosystems with a machine-readable convention (petscodex, Shimeji-ee). For everything else the issue promised: "the tool emits a numbered contact sheet and a skeleton manifest for a human (or an agent with eyes) to categorize." Neither PR built it. Until it exists, a pack from an unknown ecosystem gets no on-ramp at all.

Scope

A third mode in scripts/import-pet.py — --format frames — taking any directory or zip of PNGs:

  • Emit a numbered contact sheet (one labeled cell per source frame, the frame's filename under it) so a human or an agent with eyes can map frames to the Required Animation Set.
  • Emit a skeleton character.manifest: provenance header naming the source, all nine required animations declared with empty frames = [] and default fps, a # frame N: <filename> index as comments.
  • Emit the frames themselves through the shared pipeline (baseline alignment and resample wait until the human fills the manifest — a skeleton import cannot know which frames form an animation, so it copies frames as-is and leaves alignment to a --realign second pass, or documents that the petscodex/shimeji paths own alignment).
  • No license gate. feat(import): Warn on an unrecognized license instead of refusing #142 removed --accept-license: a license that is missing or not in the allowlist warns and the import continues. An unknown ecosystem always means an undeclared license, so a frames import always warns.

The second-pass design (fill manifest, then align) is the open question this ticket settles first.

Acceptance

  • Pointing the tool at a directory of arbitrary PNGs produces a contact sheet and a skeleton manifest without errors.
  • A human who fills the skeleton and re-runs the finishing pass gets a package character::load accepts.

Activity

  1. omesser commented on Aug 31, 2026

    @omesser
    OwnerAuthor

    Closing wontfix. ai-buddy is not getting a generic import on-ramp: a source ecosystem gets a real adapter that knows its pose semantics, or it gets nothing.

    #147 built this ticket in full and an agent drove the finished flow end to end. It completes, and the Character it produces is wrong. 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; only rendering the package and looking at the sprite caught it.

    That is the reason, not a detail of the implementation. A pile of PNGs carries no pose semantics, so no tool reading that input can check its own answer — the categorization is a guess presented as an import, and its failure mode is a Character that validates and is wrong. That costs more than having no path, because it surfaces only when someone opens the sprite. A higher-resolution contact sheet does not touch it: those three Animations were wrong about pose meaning, not about pixels.

    Hand-categorization is still available and needs no tool — write the Character Manifest, point character::load at it.

    Recorded in ADR-0009 (#157). #147 is closed unmerged, its branch kept for reference. #112's contact-sheet sentence is corrected.

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

    wontfixThis will not be worked on

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions