Add GameCraft creation skill

README.md

@@ -21,6 +21,35 @@ The benchmark runs on top of [Harbor](https://github.com/harbor-framework/harbor
 
 ---
 
+## Quick start with the GameCraft skill
+
+**One command, any agent.** This repository includes the
+[`gamecraft-create`](skills/SKILL.md) skill for building, repairing, visually
+inspecting, and validating complete Godot 4 games for GameCraft-Bench. The
+[`skills`](https://www.npmjs.com/package/skills) CLI detects the coding agent
+you already use and installs the skill into the appropriate project directory:
+
+```bash
+npx skills add FreedomIntelligence/gamecraft-bench --skill gamecraft-create
+```
+
+Add `--list` to preview the available skill first, `-g` to install it globally,
+or `-a <agent>` to target a specific tool, such as `-a codex`,
+`-a claude-code`, or `-a cursor`:
+
+```bash
+npx skills add FreedomIntelligence/gamecraft-bench --list
+npx skills add FreedomIntelligence/gamecraft-bench --skill gamecraft-create -a codex -g
+```
+
+After installation, ask your agent to use `gamecraft-create` when implementing
+a benchmark task or preflighting an existing `/workspace/game` submission. The
+skill's references and validation utilities are kept together under
+[`skills/`](skills/), so they can also be copied manually into an agent's skill
+directory when CLI installation is unavailable.
+
+---
+
 ## Benchmark overview
 
 GameCraft-Bench is organized around three desiderata for end-to-end game generation:

skills/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: gamecraft-create
+description: Build, repair, and polish complete 2D Godot 4 micro-games from natural-language specifications, with special support for GameCraft-Bench and similar interaction-grounded game-generation tasks. Use when an agent must create a launchable Godot project, infer observable requirements from a game brief, select and integrate coherent assets, implement mechanics and progression, add readable UI and game feel, create deterministic scenario entry points and replay traces, inspect rendered gameplay, or preflight a submission for build, trace, visual, content-depth, and presentation failures.
+---
+
+# GameCraft Create
+
+Build a game that proves itself through play. Treat source code as implementation, the running Godot project as the artifact, and replayed gameplay as the evidence.
+
+## Load only what the task needs
+
+- Read [benchmark-contract.md](references/benchmark-contract.md) for GameCraft-Bench paths, scoring, trace constraints, and hard gates.
+- Read [score-aware-production.md](references/score-aware-production.md) before planning a new game or recovering a weak prototype.
+- Read [godot-implementation.md](references/godot-implementation.md) when creating project structure, gameplay state, UI, scenarios, or input in Godot 4.
+- Read [art-and-ui.md](references/art-and-ui.md) when selecting assets, defining the visual language, laying out the HUD, or polishing presentation.
+- Read [demos-and-scenarios.md](references/demos-and-scenarios.md) before implementing scenario entry points or writing replay traces.
+- Read [genre-recipes.md](references/genre-recipes.md) for the dominant family; do not load unrelated genre sections.
+- Read [visual-debugging.md](references/visual-debugging.md) when the project boots, but the rendered result or demos remain weak.
+
+## Non-negotiable outcome
+
+For GameCraft-Bench, deliver both:
+
+1. A self-contained Godot project at `/workspace/game` that launches cleanly.
+2. One to ten deterministic replay traces at `/workspace/game/demo_outputs/*.json` that visibly exercise the game.
+
+A clean build without useful traces is incomplete. A convincing screenshot without player-controlled state change is incomplete. A functioning mechanic shown with placeholder presentation is still a weak submission.
+
+## Production loop
+
+### 1. Inspect before writing
+
+1. Read the entire specification and all environment/tool instructions.
+2. Inspect Godot version, workspace contents, asset libraries, helper scripts, and the exact launch command.
+3. If a project exists, run it and inspect screenshots before modifying it.
+4. Identify the dominant interaction archetype and genre. Read only the matching references.
+
+Prefer the benchmark's `/workspace/tools/screenshot.sh` when present. Otherwise use the bundled `scripts/capture_screenshot.sh` on Linux with Godot and Xvfb available.
+
+Do not begin with a large write-first scaffold. Establish the contract and the evidence plan first.
+
+### 2. Build an observable coverage map
+
+Translate the brief into player-visible requirements. Maintain a compact table with:
+
+| Requirement | Category | Player action | Visible state change | Proof scenario | Proof trace |
+|---|---|---|---|---|---|
+
+Use the four categories `M` mechanics, `D` content depth, `V` functional visuals, and `A` art/presentation. Infer likely hidden rubric items from phrases in the specification, but never claim access to a hidden rubric.
+
+Every major requirement must have all three: implementation, a reachable state, and observable evidence. If a requirement cannot fit into a deterministic 20-second demonstration, add a scenario entry point or reduce scope while preserving the player-facing promise.
+
+### 3. Establish the vertical slice
+
+Implement one short but complete arc early:
+
+`title -> start/briefing -> player action -> system response -> goal/failure -> result -> retry`
+
+Make the first slice launchable, controllable, and visually legible before adding breadth. Use real project assets early enough that scale, collision, framing, and UI are validated against the final visual language.
+
+### 4. Add depth deliberately
+
+Expand along orthogonal axes instead of cloning content:
+
+- at least three functionally distinct entities, abilities, orders, cards, upgrades, encounters, or level variants when the brief implies variety;
+- a visible progression or escalation state;
+- both success and failure consequences;
+- a late-game, upgraded, boss, result, or alternate-state scenario;
+- differences that change decisions, not labels or colors only.
+
+Prioritize content and presentation after the core loop works. They carry most of the benchmark weight and are common failure modes.
+
+### 5. Make state readable and authored
+
+At 1280x720, make the following unambiguous without source inspection:
+
+- what the player controls;
+- current goal and available action;
+- selected, targeted, legal, dangerous, damaged, completed, and failed states;
+- resource, timer, health, progress, or turn changes;
+- transitions between title, play, upgrade/briefing, victory, defeat, and retry.
+
+Use a coherent asset pack, palette, typography, spacing system, and styled controls. Avoid default widgets, raw debug geometry, dense text, decorative labels standing in for behavior, and unrelated asset packs.
+
+### 6. Close the render-debug loop
+
+After every meaningful slice:
+
+1. Run the build gate.
+2. Capture the relevant normal or named scenario.
+3. Inspect the image, not just its existence.
+4. Exercise the same input path the trace will use.
+5. Fix visible and runtime failures, then repeat.
+
+Inspect at least title, normal gameplay, a dense or late-game state, victory, and defeat. Use [visual-debugging.md](references/visual-debugging.md) for the failure order.
+
+### 7. Engineer demonstrations as part of the game
+
+Create traces while features are implemented, not at the end. Prefer five to eight short, purposeful demos over ten redundant ones:
+
+- normal title-to-core-loop flow;
+- primary mechanic and consequence;
+- distinct content/ability variant;
+- progression, upgrade, or late-game state;
+- victory/result/retry;
+- failure or hazard when important;
+- one genre-specific showcase.
+
+Keep coordinates stable, seed randomness, start accepting input immediately in scenario mode, and remove dead time. Read [demos-and-scenarios.md](references/demos-and-scenarios.md) before writing traces.
+
+### 8. Preflight and stop only on evidence
+
+Run:
+
+```bash
+python3 <skill-root>/scripts/validate_submission.py /workspace/game
+```
+
+The validator runs the normal build gate and, by default, smoke-launches every named trace scenario when Godot is available. Also replay or screenshot every submitted scenario. Finish only when:
+
+- the project boots with the benchmark command and logs contain no parse/runtime errors;
+- every trace is valid and deterministic;
+- every claimed major feature is visible in at least one replay;
+- persistent visual qualities remain good across all relevant demos;
+- no demo exposes broken menus, overlapping UI, off-screen content, placeholder art, or long idle periods.
+
+## Bundled tools
+
+### Find coherent assets
+
+```bash
+python3 <skill-root>/scripts/asset_finder.py \
+  /workspace/assets/library /workspace/assets/library-oga \
+  --query "harbor boat water ui font" --limit 40
+```
+
+Searches by path and type and reports nearby license files. Copy chosen assets into the project; do not reference read-only libraries directly.
+
+### Build a contact sheet
+
+```bash
+python3 <skill-root>/scripts/contact_sheet.py \
+  /path/to/candidate/pack --output /workspace/asset-sheet.png --limit 80
+```
+
+Inspect the resulting image before committing to a pack.
+
+### Capture a rendered scenario outside the benchmark image
+
+Use this only when `/workspace/tools/screenshot.sh` is absent:
+
+```bash
+bash <skill-root>/scripts/capture_screenshot.sh \
+  --path /workspace/game \
+  --out /workspace/core-loop.png --frames 90 --scenario core_loop
+```
+
+This launches a real X11/OpenGL rendering path under Xvfb. It is not a substitute for replaying the actual trace.
+
+### Validate the submission contract
+
+```bash
+python3 <skill-root>/scripts/validate_submission.py /workspace/game --json
+```
+
+The validator checks structure, display settings, asset references, trace schema, scenario evidence, placeholder-risk heuristics, and the Godot build gate when `godot` is available. Treat warnings as review prompts; inspect the game before deciding they are safe.
+
+## Time allocation
+
+Use this default budget unless the task dictates otherwise:
+
+- 10% inspect, decompose, and plan evidence;
+- 25% implement the complete core arc;
+- 20% add meaningful content and progression;
+- 25% integrate art, UI, feedback, and transitions;
+- 20% capture, inspect, repair, and validate demos.
+
+When time becomes tight, preserve a coherent complete arc and strong proof. Cut unproven side systems before cutting build verification, scenarios, traces, visual inspection, or result states.
+
+## Guardrails
+
+- Do not expose, reconstruct, or hard-code hidden benchmark rubrics.
+- Do not fake interaction with self-playing showcase logic when player input is required. Scenarios may initialize state; traces must still demonstrate requested player actions.
+- Do not use labels, colors, or static screens as substitutes for functional content.
+- Do not stop at launch success.
+- Do not spend time on audio-only qualities for a visually scored benchmark; make rhythm, warning, and impact cues visible as well.
+- Do not add external dependencies when native Godot nodes and bundled assets suffice.

skills/references/art-and-ui.md

@@ -0,0 +1,133 @@
+# Art, UI, and functional visuals
+
+## Contents
+
+1. Asset-first workflow
+2. Micro art bible
+3. Scene composition
+4. Functional visual language
+5. UI system
+6. Polish pass
+7. Acceptance checks
+
+## 1. Asset-first workflow
+
+GameCraft-Bench supplies large mounted asset libraries. Browse them before inventing placeholder geometry.
+
+1. Extract nouns, materials, mood words, UI motifs, and required states from the brief.
+2. Search candidate packs with `scripts/asset_finder.py`.
+3. Build contact sheets for the best two or three packs.
+4. Choose one primary pack and at most one compatible support pack.
+5. Copy required files and license notices into the project.
+6. Validate real sprite dimensions and import behavior before layout and collisions solidify.
+7. Record the chosen palette, font, outline, scale, and UI style in a short art-bible note.
+
+Do not reference `/workspace/assets/...` at runtime. Those mounts are discovery sources; the submitted project must be self-contained.
+
+If no coherent pack exists, create a deliberate restricted style with authored sprites or generated raster assets where tools permit. Avoid turning raw Godot rectangles, circles, lines, and default controls into the dominant visual language.
+
+## 2. Micro art bible
+
+Decide these before polishing:
+
+| Decision | Example |
+|---|---|
+| Mood | cozy maritime logistics with quiet urgency |
+| Palette | deep navy, sea green, sunlit cream, coral accent |
+| Sprite scale | 32px source sprites rendered at 2x or 3x consistently |
+| Edge language | crisp pixel edges or soft painted edges, never mixed casually |
+| Typography | one display face plus one readable UI face |
+| Panel language | dark translucent cards with cream borders and 8px corners |
+| Feedback colors | cyan selection, amber warning, red danger, green completion |
+| Motion | buoyant ease-out for rewards, sharp punch for damage |
+
+Apply the same decisions to title, gameplay, HUD, briefing, upgrade, and result screens.
+
+## 3. Scene composition
+
+Use the full 1280x720 frame intentionally:
+
+- establish a clear focal play area;
+- reserve stable HUD zones rather than floating labels over action;
+- use landmarks, framing, paths, lanes, or contrast to guide attention;
+- avoid large empty fields, accidental dead margins, and tiny central gameplay;
+- separate foreground interactables from decorative background by contrast and silhouette;
+- keep camera motion bounded so UI and objectives remain visible.
+
+For dense management/strategy screens, use a dominant board or world region plus one consistent side/bottom control region. For continuous-action games, keep the world dominant and the HUD compact.
+
+## 4. Functional visual language
+
+Encode state with more than color:
+
+| State | Combine at least two channels |
+|---|---|
+| Selected | outline/halo + scale/pulse + info panel |
+| Legal action | tile/icon highlight + cursor/arrow + short instruction |
+| Illegal action | blocked marker + shake/flash + no state mutation |
+| Damage | sprite flash + impact motion + health change |
+| Pickup/delivery | carried sprite/icon + HUD update + target marker |
+| Danger | telegraph shape/sprite + warning icon + countdown |
+| Cooldown | radial/bar fill + dimmed icon + remaining value |
+| Progression | meter/unlock animation + changed stats/world visuals |
+| Victory/defeat | stable authored result screen + cause/stats + retry |
+
+Keep important state persistent long enough to appear in sampled evidence. Pair fast effects with a lasting visual outcome.
+
+## 5. UI system
+
+Use `CanvasLayer` for screen-space UI and `Control` containers for layout.
+
+Quality bar:
+
+- all controls use a shared theme;
+- buttons have normal, hover/focus, pressed, and disabled states;
+- text has sufficient contrast and does not clip;
+- hierarchy distinguishes game title, section, objective, value, and helper text;
+- numeric values align and update without reflowing the entire layout;
+- progress bars and meters include meaningful labels/icons;
+- result and upgrade screens visually belong to the same game;
+- keyboard/mouse focus is obvious where applicable.
+
+Avoid showing every internal variable. Display the decision-relevant state and use short, player-facing language.
+
+## 6. Polish pass
+
+Apply polish in this order:
+
+1. composition and camera framing;
+2. asset coherence and scale;
+3. state readability and HUD hierarchy;
+4. transitions between game phases;
+5. action feedback and game feel;
+6. environmental detail and ambient motion;
+7. final text, spacing, and edge cleanup.
+
+High-value, low-risk additions:
+
+- parallax or subtle background motion;
+- animated water, conveyor, glow, dust, stars, fog, or foliage;
+- themed panel textures, borders, icons, and cursor;
+- brief tweened screen transitions;
+- objective markers and world-space feedback;
+- distinct victory/defeat illustrations or compositions;
+- small idles on characters/machines/entities.
+
+Do not add polish that obscures state or makes traces unreliable.
+
+## 7. Acceptance checks
+
+Inspect screenshots from title, normal gameplay, busiest/late state, victory, and defeat.
+
+Reject the pass if any frame shows:
+
+- default gray Godot widgets or debug text as the dominant UI;
+- raw geometry standing in for requested characters, terrain, cards, machines, or props;
+- inconsistent sprite scaling or multiple unrelated art styles;
+- unreadable text, clipped panels, overlap, or off-screen UI;
+- unclear selected/target/hazard/objective state;
+- empty composition or excessive unused space;
+- result screens that look unrelated to gameplay;
+- labels claiming features not visible in play.
+
+The benchmark judge is slightly permissive on content and presentation relative to preliminary humans; do not use that as a target. Build to an authored vertical-slice standard.