studioigor/ref2game/codex

ref2game: reference → alive, playable 2D game slice

You turn a reference into a live, playable slice in its style. The user watches it in a browser page that reloads itself while you work. You also deliver the assets and a packed build.

There are two sources of truth:

• art/gen/*.png: the generated art;
• live/*.js: the code (effects, rigs, simulation, scene).

This folder is self-contained: scripts, engine templates, references and Playwright.

Codex runtime

• <skill> is this skill's directory. Run project scripts from the project root; quote paths that contain spaces.
• Image generation. All raster generation and creative edits use the session's built-in imagegen tool (image_gen__imagegen / image_gen.imagegen, per its schema). Never ask the user to pick a generator. There are no providers, plugins, API keys, command or manual backends, and no nested Codex CLI or other image skills. scripts/gen.py prepares the tool's arguments (prepare), imports the image it returned (import) and offers offline alpha and pixel tools; it cannot call the tool from Python (references/generators.md).
• Tools. Ask with functions.request_user_input_async when available, otherwise briefly in chat. Open images with view_image, run scripts with exec_command, edit files with apply_patch, and open the live URL with open_in_codex when available.
• Subagents. Critics and video-study helpers are subagents: start them with collaboration.spawn_agent, continue them with collaboration.send_message / collaboration.followup_task, and stay within the available concurrency slots. If delegation is unavailable, run the same check yourself and label it self-review.
• Turn model. Codex cannot send a message after its turn ends. Progress updates may show the live build at once, but critic results are collected and folded in before the turn's final message. Never promise a later message.
• Python. Use an interpreter with Pillow, NumPy and SciPy. setup.sh takes REF2GAME_PYTHON=/absolute/path/to/python3 and never installs packages itself; use the same interpreter for the other scripts. If dependencies are missing, prepare a project-local environment instead of modifying system Python.

Principles

1. Ask, don't guess.

• If something is the user's call and the reference doesn't settle it, ask with functions.request_user_input_async when available (2–3 short options, the recommended one first), otherwise briefly in chat. Keep working on what doesn't depend on the answer.
• Typical questions: what game this becomes, who the player is, the scope, a style choice, an ambiguous note.
• Group questions together. Decide technical matters yourself and state those decisions in your progress message.

1. Visible progress in minutes.

• The page runs on placeholders from minute one.
• Real art replaces them piece by piece.
• Never leave the user long without a visible change.

1. AI paints, code rules.

• Generate one piece or depth band per call, always with the reference and the verbatim style bible.
• Code owns scale, light, haze, outline, alpha, and all motion and effects (references/art.md).

1. Alive means systems, not loops.

• Shared forces, springs, things that react, an event bus that drives juice, a camera that travels.
• Pick what fits this game's world (references/gamefeel.md, references/effects.md).

1. Rigs, measured. The bar is a finished, shipped game.

• Every actor gets a cut-out rig with authored poses: the player, enemies, every NPC and every animal (references/animation.md).
• NPCs work at their station, facing it; some walk routines. Animals move their neck, ears and tail.
• No action is faked by rotating, scaling or bobbing a whole sprite.
• Every rig reports its joints and passes the measured checks of `qa.mjs` before anyone looks at it: foot slide, ground, limp, stride, knee, stretch, arm phase, aim at the impact, pops, rigid-only motion, coverage (animation.md §14). Frame-by-frame cycle sheets and the motion critic then judge the rest.

1. Independent critics.

• They run in the background on assets, modules, motion, frames and feel.
• At most 3 rounds each.
• They gate approval, never what is shown in the live page (references/critics.md).

1. The user is never the first to find a defect a check could find.

• qa.mjs (automatic) runs after every change to the HUD, a rig, an emitter or the render pipeline, and before anything is shown as done: HUD text inside its panel at worst-case strings, emitted effects drawn where the sim emits them, walk cycles that really move the limbs, time-driven effects that really move and don't sweep when a state changes.
• Critics are launched by default at the gates, without being asked, in the background: they never block the live page, the next step or a progress update; their results are folded in before the turn's final message (the turn model above). Speed is the point of this skill; the automatic check is the blocking one because it takes seconds.
• Every defect the user reports becomes a check: a QA state, an anchor or a cycle that would have caught it (Phase 4).
• The bar is "a clip of a shipped indie game", not "works": critics.md §0 is the polish checklist.

1. Fidelity to the reference is the default bar. Unless the user asks for "inspired by", the game must look nearly identical to the reference, not merely "in its style":

• the same camera angle and scale, the same layout (the reference's composition is the level's first screen), the same palette, value planes and light pools, the same character and prop designs, density of actors, effects and HUD layout;
• it is measured, not eyeballed: a match state in SCENE.QA() restages the reference's composition, and the fidelity critic (critics.md §5a) compares it with compare.py at the same scale, region by region;
• the fidelity critic runs at both gates and after every visual change batch, in the background; fold its top fixes into the next pass;
• don't over-polish on your own. After a pass that visibly closes the gap, show the result (live URL, the match frame next to the reference, axis scores, the top remaining gaps) and ask (principle 1): keep polishing (naming the next 2–3 fixes and roughly how long) or stop here. One fidelity pass per gate is the default; further rounds (up to 5) only when the user says to continue.

1. Deterministic and data-first.

• Render is a function of time and sim state.
• The level is data.
• The attract demo is a scripted replay, checked headless.

The references are background knowledge, not rules: the reference and the user decide.

Step 0: look, then ask once

Look at the reference first (view_image for a still). For a video, run study.py probe and make one contact sheet. Then ask once (principle 1), grouping everything:

• What game this becomes and who the player is, when the picture doesn't make it obvious. Each option says what the player does in this picture.
• Anything else you can't settle yourself.

Never ask about the image generator: built-in imagegen is fixed (generators.md (a)). All art goes through it, with arguments from gen.py prepare and back through gen.py import. Don't route generation through other image skills or tools.

After the answer:

1. Once the project exists (Phase 1), run gen.py check. It checks local inputs only (the style bible and style refs), not the tool.
2. The first production asset doubles as the capability probe (generators.md (c)): no throwaway probe and no budget question, since there is no per-image cost.
3. If imagegen is unavailable, report the blocker and keep building on placeholders; don't offer other generators.

Phase 1: setup and study

bash <skill>/scripts/setup.sh <project> --ref <reference> --genre side|top|blank
cd <project> && bash <skill>/scripts/serve.sh      # run in background; prints the LIVE: URL

The base is only a starting point:

• side: side view;
• top: top-down or 3/4;
• blank: an empty stage with pointer and keyboard input, for anything else.

Send the live URL right away.

1. Quick study (about 5 min) (references/study.md):

• run study.py probe and study.py image;
• write art/style_bible.txt (references/styles.md);
• start generating the pieces the first frame needs most (e.g. the backdrop, the main depth bands, terrain, the hero anchor): gen.py prepare → imagegen → gen.py import, one call per asset, overlapping calls only when the tool supports it. The first one is the capability probe (generators.md (c)).

1. While it runs, finish the study (including study/MATCH.md: the reference decomposed into a stageable layout, study.md §4.7):

• study/STYLE.md;
• study/PLAN.md: layers, assets in generation order, effects, interactions, level data, attract beats.

1. Shape the base into this game on placeholders:

• the mover or interaction model;
• collision;
• sort order;
• camera;
• level;
• attract script.

references/genres.md has notes per family. Keep the engine and the sim/scene contracts (references/engine.md).

Phase 2: first real frame

1. Generate in PLAN order, one imagegen call per distinct asset or part sheet (references/generators.md (d)):

• write the asset prompt in art/prompts/NAME.txt; gen.py prepare NAME art/prompts/NAME.txt [--ref IMG=role] [--size WxH] [--alpha auto|native|none] [--pixel] writes the call's arguments to art/requests/NAME.json;
• call imagegen with the prepared prompt, referenced_image_paths and transparent_background, and nothing else;
• inspect the result, then gen.py import NAME /returned/path [--replace] (raw copy, alpha validation, log);
• make independent calls in parallel only when the tool supports it, otherwise back to back; keep coding meanwhile.
• Prompt scaffold: references/art.md.

1. As each asset lands:

• slice.py;
• prep.py;
• put it in the scene (the page reloads);
• start the asset critic in the background.
• A change of texture resolution or display size lands in the same step as the scene code that sizes it (SIZES): the user is watching the live page, and oversized sprites, even briefly, read as broken.

1. While images generate, build the effects this reference and style need (references/effects.md, references/styles.md).
2. Hero. Approve the hero anchor in a real rig pose (feet under the hips, free limbs), then make its part sheet and variants (variantfix.py). Do the same for every actor in the animation list (animation.md §13), NPCs and animals included.
3. Gate A. qa.mjs passes (seconds). Launch the asset + frame + fidelity critics in the background (the fidelity critic on frames/qa/match.png) and send the live page and a few stills right away in a progress update; keep working, and fold the critics' top fixes into the next iteration when they land.

Phase 3: make it alive