Skip to content

t1k:playablelabs:web:instant-game-from-ref

FieldValue
Moduleweb
Version1.18.2
Efforthigh
Tools—

Keywords: build instant game, count together instant game, instant game from ref, instant game params, instant playable from ref, instant-games-params, PLA core instant game, web instant game

/t1k:playablelabs:web:instant-game-from-ref
<G-id | game name> --root <instant-games-web dir> --params <params.json> --ideas <ideas.json>

Instant game from a ref (web host, PLA core)

Section titled “Instant game from a ref (web host, PLA core)”

Turn ONE ref into a playable web instant game whose dashboard parameters are (a) the basic set every instant playable ships and (b) the game’s own gameplay dials, and prove each parameter works before the build is allowed to finish.

Summoned by the keywords above (activation fragment t1k-activation-web.json), /t1k:find-skill instant game, or by name from a lane brief (references/game-brief-template.md, references/redo-brief-template.md). Runs inline in the session that holds the brief (or in one worker per game when fanned out, see “Fan-out”); it owns no agent of its own.

Inputs (nothing is defaulted: the layout is the consumer’s)

Section titled “Inputs (nothing is defaulted: the layout is the consumer’s)”
InputWhatPassed as
<root>the instant-games-web tree (layout below)--root on every script
<params.json>{games:[row...]}; a row = id, name, brandKit, skinSlots, gameplayDials (easy/normal/hard), feelPreset, quickStart, showcase, assumptions--params (new-game)
<ideas.json>idea text per game: reference_game/source_url/gallery/video/license/brief--ideas (all three scripts)

The row is only a SUMMARY of the original. If the idea has a reference_game/source_url/gallery/video, THAT game is the spec (process, scene, HUD, feedback); see Step 0. A ref HTML/APK/video has no row: run t1k-playablelabs-base-clean-room Phase 0 first to get a SPEC, then write the row by hand in the same shape.

Not for: Cocos instant games (theonekit-cocos), packing/CI (t1k-playablelabs-base-pack, t1k-playablelabs-ci-*), a full playable ad on the web engine (t1k-playablelabs-ref-pla-engine-from-ref). Host is web: the packer wraps dist/ later; this skill ends at a built, audited dist/.

<root>/
_core/ PLA runtime: 00-params 10-runtime 15-shared-assets(GENERATED) 20-ui 30-audio 40-basic-params 50-flow (shared, DO NOT edit from a game lane)
_tools/ build.cjs (bundle + playable-config.json + audit gate) · audit.cjs (+lib/) · gen-config.cjs · lib/browser.cjs · sync-shared-assets.cjs · check-reference-clean.cjs · check-shared-screens.cjs · serve.cjs · publish.cjs
<Game>/ game/*.js · README.md · NOTES.md · tools/playthrough.cjs · dist/ · reports/{param-audit,playthrough}/ · playable-config.json

_core/ and _tools/ belong to the tree, not to this skill; the scripts here only scaffold into it. Local test host: bun <root>/_tools/serve.cjs --port <free port> (background; lists every game with a dist/, binds 127.0.0.1 unless --host).

  1. Obtain and study the reference (mandatory, before any code). Source first, screenshots second. The scaffolder runs scripts/fetch-reference.cjs (screenshots to <Game>/reference/, SOURCES.md, FIDELITY.md skeleton) and then scripts/fetch-source.cjs (<Game>/reference/source/): for an itch.io page it finds the playable web build (an embed exists even without a download button), downloads it, detects the engine and extracts what is extractable; for a github.com URL it shallow-sparse-clones the repo over SSH and records its LICENSE and the README’s credit lines. The last line is the VERDICT; read SOURCE.md. Nothing downloaded is ever executed.
    VerdictMeaningRoute
    readable-sourcetext source: plain/Phaser/Pixi/Three/Construct JS, Godot .gd, Swift, Java, an open-source GitHub repoPort the LOGIC: read constants, timings, state machine and layout and adapt to the PLA API (PLA.now/rng/on, regions, params). Rewrite, do not paste.
    assets-and-datacompiled or minified (Godot .gdc, Unity IL2CPP, GameMaker) but assets/scenes/data extractable (`extracted/texturesaudio
    unreadable / not-obtainableno web build, native-only, lockedScreenshots route: Read every image. A video cannot be watched: say so and use the page text.
    fetch-failedtransient (itch rate-limits quick repeats: HTTP 429; no SSH access)NOT a verdict: wait ~20 s and rerun; never conclude “no source” from it.
    Licence decides what may be REUSED (studio decision 2026-11-19; the process and HUD functions may always be matched, the expression may not):
    Reference licenceCodeArt, audio, fonts, names, content
    ---------
    open (MIT, Apache, CC0, CC-BY…)port the logic; keep the LICENSE notice and attribution in NOTES.md and READMEreuse a file ONLY if ITS licence allows (read the repo README credits: code MIT does not make its art MIT); list each reused file in reference/ALLOW.txt as <path substring> # <licence, author, attribution kept> and in ASSETS.md; anything else is redrawn
    studio-owned, or the author’s written permission (link it)as openas open; record the permission in NOTES.md
    unknown / all rights reserved (what an itch page with no stated licence is)reimplement; the source is a spec, never pastedNONE shipped: original art in a clearly different style, own item names/set/values, own synthesised audio (method below)
    Record source-licence: in NOTES.md. Fill FIDELITY.md (process steps, scene, HUD functions, caption, feedback, result, item variety; presentsimplifiedmissing
  2. Scaffold bun scripts/new-game.cjs <G-id> --root <root> --params <params.json> --ideas <ideas.json>. Check: it prints the TODO list, reference: n/n images and the source VERDICT; folder did not exist.
  3. Read the row + idea text (after Step 0, never instead of it). Row wins over the idea on any number; record every conflict in NOTES.md. Check: NOTES lists the judgement calls.
  4. Implement game/*.js against references/core-api.md, using the original-art method. Check: bun ../_tools/build.cjs --no-audit exits 0, no page errors.
  5. Playthrough tools/playthrough.cjs (copy the pilot game’s): WIN, LOSE, IDLE (never taps => must lose or time out), Easy, Hard, 390x844 and 430x932. The harness, profile and report format are t1k-playablelabs-base-playthrough (link, not restated here). Check: printed phase/outcome per run; READ the screenshots (overlaps, clipping, hand covering targets, nothing hidden behind Play Now). Re-run after the LAST edit.
  6. Build gate bun ../_tools/build.cjs (no flag) runs three automatic gates; the build fails if any fails (see “Build gates”). Check: PASS n / FAIL 0, CLEAN, IDENTICAL; then open 3 reports/param-audit/<Key>/before|after.png and confirm a real change.
  7. Compare the PROCESS to the reference. reports/compare.png: reference images beside your screenshots of the same steps; READ it. Process, steps, HUD functions and feedback must read as the same game; for an unlicensed reference the visuals must NOT look the same (that is the art rule, not a defect). Fix bare areas and missing feedback. Update FIDELITY.md.
  8. Report README param table + NOTES friction + what is still simpler than the reference. Check: every dial row names the code that consumes it.

Original-art method (when the reference licence does not allow reuse)

Section titled “Original-art method (when the reference licence does not allow reuse)”

This is the instant-games licence ladder; t1k-playablelabs-base-clean-room rule 3 (assets) is the stricter default for ad playables, and wins when both apply.

  1. Decide a distinct visual identity BEFORE drawing and write it into FIDELITY.md (visual identity: ... ; differs from the reference by ...): palette (not the reference’s), shape language (smooth vector vs pixel/outlined), setting (pegboard instead of brick), HUD form (ticket instead of clipboard), prop designs, item set. Keep the FUNCTIONS (time, profit, step label, gauge, caption, floating numbers) so the process stays readable.
  2. Draw in code: canvas paths/gradients, small offscreen sprites cached once at setup for heavy shapes, procedural icons; no downloaded files, no tracing screenshots 1:1. Skin slots (PackImage…) still accept client images.
  3. Content: invent your own item names, tiers and values; mark invented numbers as such in NOTES.md (compiled references only leave field NAMES, never the numbers).
  4. Audio: synthesise with WebAudio via PLA.audio.ctx and sfxGain (oscillators + filtered noise from a seeded LCG, never Math.random); keep effects short. Nothing audible has been listened to by an agent: say so (unverified).
  5. Prove it: the build gate check-reference-clean must print CLEAN. It finds verbatim embedding only, so the method above, not the check, is what keeps redrawn derivatives out.

Parameters (web host facts: InstantGamesWeb _core + _tools)

Section titled “Parameters (web host facts: InstantGamesWeb _core + _tools)”
  • Exposed dashboard categories are exactly StoreOptions, EndCard, Loading, Audio, Brand, Gameplay. StoreLink exists only in the dashboard and is never declared.
  • One control per value: a param with a fallback and the Feel preset are hidden: true (kept in code and audited, excluded from playable-config.json).
  • A param with a missing or other category throws at declaration.
  • The audit has 5 shape:* rows: categories, defaults, fallback, duplicate-source, duplicate-key.

Build gates (automatic, in _tools/build.cjs; each needs a negative control when changed)

Section titled “Build gates (automatic, in _tools/build.cjs; each needs a negative control when changed)”
GatePasses whenFails when
audit.cjs --fullevery parameter is wired and shows a before/after changea parameter is unwired or shows no change
check-reference-clean.cjsno reference art/audio/font/video is embedded in dist/game.js (allow-listed files excepted; an ALLOW.txt line without # reason is an error)a reference file slice is found in the bundle
check-shared-screens.cjsloading, win end card and lose end card are byte-identical to the core-only _hello gamethe game changed or drew on a shared screen
Automatic, never called by hand. _tools/lib/gate-state.cjs fingerprints a game’s sources (game/*.js, the shared _core, reference/ file names and sizes) and an optional project hook (the reference tree wires .claude/hooks/playable-gate.cjs on Stop and SubagentStop; the kit ships no hooks) runs build.cjs --changed for every game whose sources changed in the last 90 minutes and whose fingerprint has no passing stamp; a failure BLOCKS the turn with the failing lines, so the agent fixes it without the user asking. The build is atomic: a failing build restores the previous good dist/ (the failed one stays in dist.failed/), only a passing build writes dist/gate-stamp.json, and reports/gate-last.json records a failure. The local host marks each game gates passed / STALE / FAILED. One gated build per game at a time (reports/gate.lock, exit 75 = already running). Lane agents still run bun ../_tools/build.cjs themselves before reporting (the hook is the safety net, and --changed re-audits only the parameters whose related files changed).
_hello is the baseline: rebuild it (cd _hello && bun ../_tools/build.cjs) after ANY core change, before building games, or check-shared-screens compares against a stale baseline.

A built, gated game goes to the Instant Template organization with <root>/_tools/publish.cjs <Game> --env dev|prod (idempotent steps, --dry-run calls nothing, first upload always lists). After the upload the tool writes <Game>/reports/publish/notify.json; the session posts it as the #instant notice with discord-mcp messages_send (new game or update, DEV or PROD, one message per game). Steps, flags, tokens, approval click and troubleshooting: references/publish.md.

Independent games share nothing mutable except _core/ and _tools/: one agent per game, one folder each, no worktree needed (not a git repo; if it becomes one, one worktree per game). Smoke ONE game first, surface the result, then fan out. Brief = pointer, not payload: references/game-brief-template.md + the G-id. Lanes never edit _core/ or _tools/: they report needs; the orchestrator changes the core, reruns --selftest and the full audit on a finished game, then lets the next lane start.

bun ../_tools/build.cjs exits 0 with FAIL 0; playthrough output for win/lose/idle/Easy/Hard/two viewports pasted; screenshots read; README param table complete; NOTES lists conflicts and friction and carries source-licence:; FIDELITY.md has no unexplained missing row (visual rows may read waived: original art by design); reports/compare.png was read; the build printed PASS n / FAIL 0, CLEAN (no reference art, audio, fonts or names shipped, except allow-listed licensed files) and IDENTICAL (loading and end cards are the core’s); the report states what is still simpler than the reference and what is unverified (audio nobody listened to, invented numbers);

Section titled “Related skills (this one links, never restates)”
NeedSkill
SPEC from an html/apk/video ref, clean-room rules, two-side disciplinet1k-playablelabs-base-clean-room
Parameter publish format, playable-config.json, dashboardt1k-playablelabs-base-params
What the parameter audit proves; incremental re-auditt1k-playablelabs-base-params-audit, t1k-playablelabs-web-params-audit
Playthrough harness, profile, strips, invariantst1k-playablelabs-base-playthrough
Web host contract (__plaGame__, scene-up) the built dist/ must keept1k-playablelabs-web-host-contract
Pack, smoke, networkst1k-playablelabs-base-pack, -smoke, -networks
Platform MCP facts for publishing (limits, approval handles, errors)t1k-playablelabs-base-mcp (references/instant.md); the tool-specific steps are references/publish.md

Other references: references/core-api.md (PLA API, shared studio art, parameter rules, audit, gotchas, lessons), references/publish.md, references/game-brief-template.md, references/redo-brief-template.md.

Scaffolding and fetching (scripts/*.cjs), running the build gate and the playthrough, and tabulating results are mechanical; reading the reference, porting its logic and judging fidelity are not.

StepAgent
Run new-game.cjs / fetch-*.cjs, bun ../_tools/build.cjs, tools/playthrough.cjs; tabulate PASS/FAIL and exit codest1k-tester
Study the source, write game/*.js, fill FIDELITY.md, judge a REDt1k-playablelabs-base-web-developer