/character-bundle

name: character-bundle
description: Produce one illustrated character SpriteFrames resource from high-level body-action intent, optional character and style references, and a resolved animation plan.

Character Bundle

Produce one player, enemy, NPC, summon, boss, creature, or skin as one `SpriteFrames` resource. Read `.godotmaker/asset-runtime/asset-skill-contract.md` and `.godotmaker/asset-runtime/animation-planning.md`. This standalone skill does not read or write `ASSETS.md`, tags, stage state, manifests, or worker dispatch state.

Request and planning

Require `asset_type: "character-bundle"`. The caller supplies a non-empty ordered `spec.actions` list. Each action needs a unique `name` and a concise `intent` describing pose beats, gameplay feel, and motion trajectory; it may state whether the action loops. The caller does not prescribe frame count, FPS, frame durations, names, or grid. Resolve those from the shared animation-planning guidance. A caller may choose a power-of-two `spec.frame_canvas_px`; otherwise default the runtime canvas to 256 px.

Before provider dispatch, write `.godotmaker/asset-generation/plans/<asset_id>_animation_plan.json` and `.godotmaker/asset-generation/plans/<asset_id>_resolved_request.json`. The plan top level records `asset_id`, `frame_canvas_px`, and `identity_anchor_origin`. For every action, first resolve temporal cadence: named motion phases, transition frames, and any intentional holds. Then record `name`, `cadence` as an ordered list of `{phase, frame_names}` entries covering every resolved frame exactly once, pose beats, frame count, fps, loop, frame durations, grid, source-batch plan, `runtime_canvas_px`, and rationale. Do not choose the frame count by mechanically assigning one frame to each pose beat. The resolved request has ordered `required_actions`; every resolved action retains its public `intent` and has `name`, `grid`, ordered `frame_names`, positive `fps`, explicit `loop`, and one positive `frame_durations` value per frame. `grid.columns * grid.rows` equals the frame count. Validate this resolved request with `tools/asset_animated_bundle_contract_check.py --kind request` before processing or compiling.

Use exact resolved grid and frame order for a source batch, but do not treat planning guidance as a reason to reject a valid artistic request. When a fixed-size provider source would make a dense action too small for the chosen canvas and safe area, split the action into source batches and preserve every batch's prompt, raw source, attachments, and report. Combine their resolved frames in action order before compiling one SpriteFrames resource.

Carry the visual rules stated in `brief` into every provider prompt as written; they are the visual specification for this bundle. Examples of the style language they establish are `hand-drawn cel-shaded fantasy`, `comic-book ink and flat color`, and `painterly storybook`. Pixel-art production is unsupported in this family; stop clearly when it is requested. Do not use nearest-neighbor resampling.

References and identity anchor

External references are optional and condition those rules rather than replace them: an attached `style` or `canonical` image supplies identity, palette, and continuity, never a style rule the brief did not state. Validate each path is a readable image, preserve its `canonical` or `style` role, resolve `res://` from the project root, and attach the actual images to the declared provider. Never replace an image attachment with a path in prompt text. Use only the declared `native`, `codex`, `gemini`, `openai`, `grok`, or `wan` provider; do not silently switch. Stop clearly when the selected provider cannot generate or attach the required images, and stop with a blocker when a supplied reference contradicts a rule stated in `brief` instead of dropping either one.

Choose one identity anchor:

1. Use a suitable user `canonical` image directly for every action. Do not generate a duplicate canonical merely to satisfy the workflow. 2. When a user character image is cropped or unsuitable as a full-body action anchor, derive a full-body canonical from it and retain the source relationship. 3. When no user character image exists, generate a full-body canonical. Finalize it and copy the finalized image to `assets/generated/character-bundle/<asset_id>/<asset_id>_canonical.png`; return it as a `reference` output so the user receives the generated character image.

Record `identity_anchor_origin` as `user_provided`, `provider_derived`, or `provider_generated`. Every action receives the identity anchor as an actual image attachment. It also receives every external reference in role-preserving attachment order.

Provenance

Keep raw sources, finalized anchors, prompts, reports, rejected attempts, and curation output under `.godotmaker/asset-generation/`. Store a distinct prompt and provider report for every provider attempt, including retries and source batches. Use `canonical/<asset_id>_canonical.png`, `sources/<asset_id>_<action>_source.png`, `reports/<asset_id>_canonical_source.json`, `reports/<asset_id>_<action>_provider.json`, and `reports/<asset_id>_<action>_process.json` for a single source batch; add `_batch<N>` before the suffix for additional batches. Each provider report records provider, model when available, coding model, reasoning, source path, reference roles, attached local paths, attachment count, and `provider_trace`.

`provider_trace` contains `provider`, `tool_call_id`, `image_model_identity`, `coding_model`, `reasoning`, and ordered absolute `referenced_image_paths`. Use `image_model_identity: "not_exposed_by_subscription_runtime"` only when the runtime does not reveal it. For Codex, call image generation once per attempt and pass every attachment through `referenced_image_paths`.

Use only provider outputs or user-provided images as visual sources. Do not draw, synthesize, or edit art with ad hoc Pillow, System.Drawing, ImageMagick, SVG, canva