fx-bundle

name	fx-bundle
description	Produce a standalone static Texture2D effect or one explicitly timed animated SpriteFrames effect.

FX Bundle

Use this Skill for one detached foreground effect: a projectile, impact, explosion, pickup, muzzle flash, slash arc, aura loop, or dust effect. It delivers either one static Texture2D or one animated SpriteFrames; it never delivers a PackedScene, particle node, trail, shader, sound, light, collision shape, lifecycle script, or a multi-node effect.

Read .godotmaker/asset-runtime/asset-skill-contract.md before accepting the request. For animation rhythm, also read .godotmaker/asset-runtime/animation-planning.md; it supplies planning ranges, not a reason to change an explicit request or reject a valid style.

Validate the shared request with tools/asset_skill_contract_check.py, then validate this family with tools/asset_animated_bundle_contract_check.py --kind request. At final handoff, call the latter with --request <request.json> --result <result.json>. The family checker binds spec.mode to the runtime type and source layout.

Boundary and STOP

The request has asset_type: "fx-bundle" and spec.mode equal to static or animated. References are optional. Pixel-art requests are unsupported in this version: stop clearly rather than quantizing, nearest-neighbour scaling, or labelling ordinary art as pixel art.

Stop only when a required input is unreadable, a declared provider or required reference attachment is objectively unavailable, the request is contradictory, or it asks for an unsupported deliverable such as a particle PackedScene. An image-processing, import, compiler, metadata, path, or validation failure is a production diagnostic: repair it and recheck it before deciding to stop.

This is a standalone Skill. Do not require /gm-asset, tags, stage state, ASSETS.md, generated manifests, or worker registration. A caller may register the returned ready entry separately.

Request contract

• static has no required_actions or actions. It returns one transparent Texture2D at assets/generated/fx-bundle/<asset_id>/<asset_id>.png with a single source layout.
• animated has exactly one required action and exactly one action with the same name. The action has grid.columns, grid.rows, non-empty ordered frame_names, positive fps, explicit boolean loop, and one positive relative duration per frame. The grid contains exactly one cell per frame. It returns one SpriteFrames resource at assets/generated/fx-bundle/<asset_id>/<asset_id>.tres with a grid_sheet source layout.

Never infer timing, frame order, grid, or loop state. Reject duplicates, missing frames, non-positive timing, mismatched durations, or mismatched grid cell count.

Provider, references, and provenance

1. Read the declared provider guide at .godotmaker/asset-runtime/references/providers/<provider>.md. The runtime installs this guide from the shared gm-asset provider contract. Execute that provider route only; do not silently substitute native, codex, gemini, or openai.
2. With no references, generate from the request's identity, gameplay role, direction, scale, frame count or static target, intended visual style, isolated foreground, solid #FF00FF source background, and no text or UI.
3. With references, validate every referenced path is readable, preserve its role, and attach the actual image to the chosen provider. A pathname in a text prompt is not an attachment. For Codex, resolve each res:// reference to its actual local readable path and pass those exact paths through referenced_image_paths; for the scripted OpenAI/Gemini routes use asset_source_generate.py reference inputs. If the selected route cannot attach them, stop rather than dropping or replacing the reference.
4. For Codex, write a one-item generation plan with require_provider_trace: true, then record the actual generated image path, tool-call ID, coding model/reasoning, image-model identity (or not_exposed_by_subscription_runtime), reference roles, and resolved attachment paths. Claim that image with python .godotmaker/asset-runtime/tools/codex_image_claim.py --plan <plan.json> --report <generated-paths.json> --project-root . --out-report <claim.json>. Never directly copy a Codex image into the project. Missing claim evidence is a STOP.
5. Write .godotmaker/asset-generation/traces/<asset_id>.json. It contains asset_id; provider.requested, provider.actual, and, when applicable, provider.referenced_image_paths as the exact absolute local paths passed to the image-provider call; ordered references with the request role, res:// path, sha256, and literal attachment: "referenced_image_paths"; artifacts.raw_sources, provider_claim, process_reports, final_frames, source_layout, and godot_artifact; and ordered steps. source_layout and are objects with exactly and : animated FX uses and ; static FX uses and . Every artifact path is a contained or project-relative path. Each step records , , , , , , and . Project tools are preferred, but a temporary image tool or diagnostic script is allowed when this trace is truthful; its name alone is never a failure. When a temporary script is created, list that script's exact path in the same step's as well as the generated assets it changes; do not omit the script merely because it is an implementation detail.

References influence scale, direction, palette, and visual style. Do not claim they were attached or validated unless the provider trace proves it.

Production loop

Work in the following loop until every applicable L0-L4 check passes or a real STOP condition occurs. Never mark the first failed check as the final result.

1. Generate and preserve a raw source image. Keep the foreground on a solid #FF00FF background before deterministic cleanup, with no text or UI.
2. Choose the static or animated path below. Keep raw sheets, final PNGs, reports, source layout, final artifact, and Godot artifact in the trace.
3. Construct the shared asset result and run standalone_validation.compile_and_validate() for the applicable L0-L4 checks. Read the diagnostic, then repair source art, processing parameters, metadata, paths, or Godot artifact and rerun the checks.
4. Only after all applicable L0-L4 levels pass, set validation.passed: true, write the final result, and run the request/result handoff checker. Preserve the build fingerprint as evidence; /gm-asset validates the result and records it directly in ASSETS.md. Then write that generic result object to ASSET_RESULT.json in the project root and return only its JSON contents: no Markdown links, prose, or alternate result shape. L5/L6 visual judgment belongs to the private Eval, not this production Skill.

Godot executable for L3/L4

L3 is a real Godot import/load probe, not a PATH-presence check. When GM_EVAL_GODOT_PATH is set, it is the pinned executable for this run: pass that exact value to compile_and_validate(..., godot_path=...) (or leave its historical "godot" placeholder for the shared validator to resolve). Do not replace it with a bare godot, discover another installation, or mark L3 as passed without invoking it. Outside an Eval, resolve the configured executable with python tools/agent_runtime.py godot_path; if it is genuinely absent or unrunnable, record the diagnostic and STOP only after the production repair options are exhausted.

Static path

Use tools/asset_sheet_process.py --snap-mode autoslice only when every disconnected foreground component is itself one logical effect. Do not supply --grid to autoslice. Follow it with curation and tools/asset_curation_select.py; selection invokes asset_image_finalize.py for transparent cleanup, aspect-preserving scaling, centering, and padding before the stable PNG is published.

If disconnected sparks, fragments, glow, or dust semantically form one effect, preserve the whole composition instead. Use an explicit one-cell/grid curation route or finalize the full source deterministically; do not let autoslice split one effect into unrelated runtime assets. If autoslice --names does not match the detected regions it returns needs_regeneration without partial output. Treat that as a repair diagnostic: regenerate or relayout the source, or correct the intended naming; never drop regions or silently assemble a different effect.

After selecting one candidate at the final PNG path, compile and validate its Texture2D output through the shared route. Preserve the reports and fingerprint as result evidence; do not create a registration record.

Animated path

Use tools/asset_action_process.py with --kind fx, the declared explicit grid, ordered frame names, action name, FPS, loop flag, durations, magenta cleanup, and --align center. Preserve raw sheet, processed transparent frames, delivery sheet, GIF preview, processing report, and action metadata. Animation never uses autoslice or an atlas assembler. Publish each processed frame at assets/generated/fx-bundle/<asset_id>/<asset_id>_<action>_<frame>.png; this is the canonical frame path consumed by the L0-L4 SpriteFrames validation route. Pass --final-dir assets/generated/fx-bundle/<asset_id> and --final-prefix <asset_id>_<action> and --final-sheet-name <asset_id>_sheet.png to the action processor. Do not use only <asset_id> as the final prefix: each declared frame_name already carries its own ordered frame label, so omitting the action prefix changes the stable runtime path. The separate final sheet name preserves the one stable source-layout path consumed by the SpriteFrames compiler.

Use grid.columns * grid.rows, ordered frame_names, frame_durations, and loop as the only frame-slicing facts. Do not split, merge, or reorder frames from components, bounds, or autoslice regions.

On status: "needs_regeneration", preserve the report, repair or regenerate the same source with the declared grid, and process it again. If visual grid rejections remain after suitable provider repair, process the preserved source again with the same grid, names, timing, delivery paths, and --fixed-grid-fallback. Do not run connected-component recovery. Preserve the action report's structured warnings[], complete compilation and L0-L4, and copy a concise warning summary to the final result's string validation.notes.

Compile and validate the one SpriteFrames artifact through the shared route. Preserve frame order, grid, timing, loop state, alignment, paths, and fingerprint as result evidence.

Result shape

An animated result has one SpriteFrames runtime output and one stable grid_sheet source. A static result has one Texture2D runtime output at the same stable PNG path as its single source. Both final results include explicit passing L0 through L4 evidence; no other runtime Godot type is valid. ASSET_RESULT.json is the final machine-readable handoff, not a report link or a summary of another JSON file.

Trace finalization

Before writing ASSET_RESULT.json, reread the emitted trace and validate its own paths against the files on disk. source_layout and godot_artifact live inside trace.artifacts, never at the trace root. For an animation, trace.artifacts.final_frames is the exact ordered list from the action processor's recorded final-frame paths; do not reconstruct or edit these names by string concatenation. Reject and repair the trace if a listed frame is missing, the count differs from the request, a field is outside artifacts, or the layout/artifact type and path do not match the final result.

{
  "artifacts": {
    "source_layout": { "type": "grid_sheet", "path": "res://assets/generated/fx-bundle/<asset_id>/<asset_id>_sheet.png" },
    "godot_artifact": { "type": "SpriteFrames", "path": "res://assets/generated/fx-bundle/<asset_id>/<asset_id>.tres" }
  }
}