Character Bundle

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.

Use an explicit visual style or attached style image. Examples 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. Validate each path is a readable image, preserve its canonical, style, or screen 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, or wan provider; do not silently switch. Stop clearly when the selected provider cannot generate or attach the required images.

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, canvas, Godot drawing, inline scripts, color blocks, placeholders, or fake atlases. Existing controlled asset tools may process real provider or user images.

Produce

1. Validate the public request shape. Resolve and archive the animation plan and resolved request.
2. Select or create the identity anchor. A generated anchor must be full-body, match the selected style, and preserve an intended ground reference. When its provider source uses the controlled magenta background, finalize it with tools/asset_image_finalize.py --background magenta; preserve an already-transparent user image rather than replacing its pixels.
3. For every resolved source batch, generate a sheet with the identity anchor and all external references attached. Prompt for the concrete pose beats, exact grid, full-body separation, safe gutters, selected visual style, and only the intended body action. Keep every intended body and prop contour complete inside its source frame; a wide pose may use the available frame area but must not cross into a neighboring frame.
4. Process real source sheets with tools/asset_action_process.py using --kind body, --align feet, the resolved grid and names, --cell-size <frame_canvas_px>, and --recover-edge-touch. Preserve candidates, reports, frames, transparent sheets, GIFs, and stable PNG paths.