xingaobio/kobutai-character

Kobutai Character

Kobutai (小舞台) is a browser extension and desktop app: a small chibi character performs on the page while music, videos, live streams or podcasts play. This skill turns the user's favourite character image (or a description) into a character Kobutai can import:

upload ─► character card ─► profile sheet + base pose ─► state GIFs ─► make_pack.py ─► pet.json + spritesheet.webp

Reply in the user's language (English, 日本語 or 中文). Keep image prompts in English.

Read these when you reach the step that needs them:

• references/kobutai-contract.md - sheet geometry, which GIF becomes which Kobutai state, import and share rules
• references/prompts.md - every image prompt, the style blocks, and per-performance action lists
• references/originality.md - what to do with third-party characters, OCs, pets and real people

Image generation

Use the host's built-in image generation for every picture:

• Codex: the $imagegen system skill (built-in image_gen tool). Do not call the Image API or a CLI unless the user explicitly asks; that path needs their API key.
• ChatGPT: native image generation.

Images 2.6 (Nov 2026) can return animated GIFs. Ask for a GIF for every animated state. If the host returns a still image, refuses GIF output, or the GIF is unusable, use the grid fallback in references/prompts.md (8 frames as a 4 x 2 grid PNG); make_pack.py slices it.

Attach base.png (and the user's upload, labelled "identity reference only") to every state generation. A state generated without the base attached is invalid: regenerate it.

Progress checklist

Show and update this checklist (task list if the host has one):

1. Reading your character
2. Drawing the profile sheet
3. Animating the states
4. Packing for Kobutai
5. Checking and delivering

Workflow

1. Read the character

Look at every uploaded image and write RUN/character.json (RUN = kobutai-<id>/ in the workspace; in ChatGPT, /mnt/data/kobutai-<id>/). Fields and an example are in references/prompts.md § Character card. Decide:

• mode - original / own / personal per references/originality.md. Default for a recognisable third-party character is original: an original character inspired by its mood, colours and role, not a copy.
• style - kobutai (house chibi style, matches the built-in cast; default) or keep (keep the upload's art style, still compact and full-body).
• scene - what the character does while content plays (sing, dance, DJ, play an instrument, cosy listen, watch and react, take notes ...). Pick from § Performance scenes.
• genres / type - suggested Kobutai tags, used later in the extension's share dialog.
• chroma - #00FF00, or #FF00FF when the character has green in it.

Send the user ONE short message with the card (name, look in one line, mode, style, scene, tags) and ask them to confirm or change anything. Proceed on the default if they say "go" or don't care. If the upload has no clear single character, ask which one.

2. Profile sheet and base pose

1. Generate RUN/profile.png with § Profile sheet: front, three-quarter, side and back views, four expressions and a palette strip, no text. This is the user's model sheet; show it to them.
2. Generate RUN/base.png with § Base pose, attaching profile.png: one relaxed full-body standing pose, three-quarter view, on the flat chroma background. Every state is drawn from this.

If identity is off (face, hair, outfit, palette), fix it here; every later step copies base.png.

3. Animate the states

Generate into RUN/states/, one job per file, base.png attached each time:

File	Kobutai use	Required
idle.gif	standing by, nothing playing	yes
playing.gif	the performance loop while content plays (most important)	yes
paused.png	ONE still "waiting for you" pose (Kobutai holds a single frame)	recommended
appear.gif	entrance, played once when the character is drawn	recommended
click.gif	reaction when poked, played once	recommended
error.gif	confused / sad loop	optional
walk.gif, review.gif	only used when the pack is also a Codex pet	optional

Use § State GIF with the action list for the chosen scene. Order: idle and playing first, check them, then the rest. After each file, check quickly: same character, about 8 distinct frames, one plain background, whole body inside the frame, feet on one baseline, no text, no floating effects. Regenerate a failing state alone with § Repair; never restart the whole run for one bad state.

Downloaded GIFs/PNGs from ChatGPT or $CODEX_HOME/generated_images/ must be copied into RUN/states/ with exactly these names.

4. Pack

python3 <skill_dir>/scripts/make_pack.py RUN                 # Kobutai (up to 8 frames per row)
python3 <skill_dir>/scripts/make_pack.py RUN --target codex  # exact Codex-pet frame counts

Needs Pillow + numpy (pip install pillow numpy, scipy optional). The script keys out the background (or keeps real transparency), drops duplicate frames, matches scale across GIFs, aligns feet, writes the 1536 x 1872 Petdex/Codex sheet and validates it exactly as Kobutai's importer does. Options: --grid playing=4x2 for a grid image with another layout, --scale click=0.9 when one source came out too big or small, --key-low/--key-high for a stubborn background.

Exit code 2 means validation failed; read out/qa/report.json, fix the source, rerun.

If the host cannot run Python (some ChatGPT setups), deliver profile.png, base.png, the state files and character.json as a zip and tell the user to run the same command locally.

5. Check and deliver

Open out/qa/contact.png and out/qa/preview.gif and look. Reject and repair when:

• any row changes the face, hair, outfit, palette or props
• the character pops in size or jumps sideways between frames or between states
• a pose is clipped at the cell edge, or the background left a coloured fringe or specks
• the playing loop is visually static, or idle is a big motion
• at ~120 px tall (the size Kobutai shows) the character is no longer recognisable

Then deliver:

1. kobutai-<id>.zip containing <id>/pet.json + <id>/spritesheet.webp
2. profile.png and preview.gif to look at and share
3. How to use it (from references/kobutai-contract.md § Import): Kobutai → Import → choose pet.json and spritesheet.webp together. Optional: copy the folder to ~/.codex/pets/<id>/ to use it as a Codex pet too.
4. Only for original and own mode: they can submit it to the weekly community library from the extension (My imported characters → Share with everyone, CC BY 4.0, credit name required), with the genres from the card. For personal mode say plainly it is for their own use only.

Keep RUN/ (card, profile, base, states) so a later "make the dance faster" or "redo click" only regenerates one state.

Cost

A full run is about 8 image generations (profile, base, idle, playing, paused, appear, click, optional error) plus repairs. Tell the user before starting a second full run.