/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 `godot_artifact` are objects with exactly `type` and `path`: animated FX uses `{ "type": "grid_sheet", "path": "res://..._sheet.png" }` and `{ "type": "SpriteFrames", "path": "res://....tres" }`; static FX uses `{ "type": "single", "path": "res://....png" }` and `{ "type": "Texture2D", "path": "res://....png" }`. Every artifact path is a contained `res://` or project-relative path. Each step records `reason`, `command_or_code`, `inputs`, `outputs`, `modified_files`, `diagnostic`, and `repair`. 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 `modified_files` 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