Reference to Game

Turn images, videos, sheets, sketches, models, audio, links or a written idea into a playable game—without losing its visual identity.

An input-agnostic skill and toolkit for coding agents. It gives Claude Code, Codex, Cursor and other agents a workflow for preserving style, colors, shapes, materials, camera, motion and UI, then turning that direction into real gameplay.

Reference → playable implementation. The four games below were developed from image, sheet and video references. Their source and runtime assets are included.

Install · Try a game · Use · Tools · Evidence · Scope

Why references matter

A prompt can describe “colorful” or “painterly” without specifying the decisions that make a particular game recognizable. References make those decisions concrete: the size of an accent color, a character's proportions, the softness of a shadow, the camera's distance, the way a UI panel feels like paper.

The challenge is carrying those decisions through implementation. A game can compile, run smoothly and have working mechanics while still looking unrelated to its reference. This workflow treats visual identity and playability as separate requirements. Neither can hide a failure in the other.

• Inspect before implementing. Assign authority separately for appearance, identity, mechanics, motion and UI. Preserve originals and distinguish observation from invention.
• Lock style before expanding scope. Build a small polished scene, compare it to the reference, and fix the largest mismatch before multiplying assets and levels.
• Choose the right representation. Painted sprites, 2.5D layers, procedural geometry, generated meshes and shaders can coexist. Full 3D is not automatically the most faithful choice.
• Build actual gameplay. Input, rules, state-driven UI, goals, recovery and restart. A screenshot or prerecorded showcase is not the implementation.
• Generate assets deliberately. Optional fal workflows for images, models, textures, animation studies, audio and music, with durable job IDs and duplicate-submission protection.
• Deliver inspectable evidence. Source-bound reviews, reference comparisons, rule tests, real input-driven playthroughs, measured performance and honest limitations.

Any reference, an appropriate workflow

Input-agnostic does not mean universal automatic decoding. The CLI handles intake and common media inspection; specialized formats and inaccessible links need an appropriate tool. The coding agent performs visual judgment and implementation. Exact boundaries →

The default implementation profile is Three.js + TypeScript + Vite, with support for 2D, layered 2.5D and full 3D. The contracts are engine-neutral; other engines can follow the workflow, but this release does not ship verified project generators for them.

Four worked games

Jetboat racing	Candy factory puzzle
Jungle Jetboat Jump — 3D boat and crew, painted vegetation, procedural water; ordered gates, pickups, boost, jumps and recovery.	Jellyworks — tactile machinery and candy; deterministic conveyors, mixing, molds, backpressure, edit/run modes and three solvable puzzles.

Painted meadow exploration	First-person train action
Petal Pals — painted directional characters in a 2.5D world; observe, feed, photograph, befriend, explore and save.	Sunshine Train Battle — cleaned generated meshes and a train-local world; shooting, shielding, reloading, jumping, checkpoints and restart.

Each example includes runnable source, runtime assets, original image, full development sheet, style contract, visual comparison and case notes. Full raw generation archives are intentionally excluded. The cases predate this packaged skill; they are worked examples, not a controlled with/without-skill benchmark. Read their remaining differences and historical validation reports rather than assuming pixel-perfect reconstruction.

Run any example locally; no fal key is needed:

git clone https://github.com/gokayfem/reference-to-game.git
cd reference-to-game/examples/petal-pals/app
npm ci
npm run dev

Each game has its own controls, tests and build scripts. Reference art/generated media are demonstration material with separate reuse considerations; credits and licensing.

Install

Claude Code plugin:

claude plugin marketplace add gokayfem/reference-to-game
claude plugin install reference-to-game@reference-to-game

Agents that support the skills CLI:

npx skills add gokayfem/reference-to-game

Choose the reference-to-game skill and your agent. Or copy skills/reference-to-game/ into the agent's supported skill directory. The skill is self-contained: the tools and supporting guides travel with it. For a chat assistant without local execution, use the handoff prompt.

The CLI requires Python 3.10+. Intake, prompts, validation and fal bookkeeping use the standard library. Image tools additionally need Pillow; audio/video inspection needs ffmpeg and ffprobe. Runtime helper tests use Node 20+; the example games recommend Node 22+.

python3 -m pip install -r skills/reference-to-game/scripts/requirements.txt

Use

Ask naturally:

“Make a playable Three.js game from this image and full development sheet. The style and colors are the most important part. You can create fal assets.”

“Use this ink illustration for appearance and this clip for movement. Build a small exploration game without changing the drawing style.”

“Here is an existing prototype and a new art reference. Keep the rules, replace the visual direction, and show comparisons.”

Or start a portable case explicitly:

python3 skills/reference-to-game/scripts/r2g.py init cases/my-game \
  --input /path/to/concept.png \
  --input /path/to/movement.mp4 \
  --brief "Make this playable while preserving its style and colors"

python3 skills/reference-to-game/scripts/r2g.py inspect cases/my-game
python3 skills/reference-to-game/scripts/r2g.py prompt cases/my-game \
  --out cases/my-game/IMPLEMENT.txt

Give the case and the prompt to your coding agent. It fills the style/game/asset contracts, implements the game, compares it against the reference, then plays and verifies it. The full reusable prompt is also available at prompts/reference-to-game.md.

Tools

Command examples and contracts →

The optional JavaScript helpers cover a bounded fixed-step clock, once-only reward IDs, swept-circle collision, frame-independent damping, input cleanup and seeded randomness. They contain no default palette, camera, character, level or genre.

fal asset generation

fal is optional. The game runs on local assets, not live generation calls. Agents can choose suitable current endpoints for image editing, textures, sprites, 3D meshes, audio, music or motion references, then review and