t1k:playablelabs:web:instant-game-from-ref
| Field | Value |
|---|---|
| Module | web |
| Version | 1.18.2 |
| Effort | high |
| 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
How to invoke
Section titled “How to invoke”/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)”| Input | What | Passed 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/.
Layout (one tree, nothing cloned)
Section titled “Layout (one tree, nothing cloned)”<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).
Flow (each step has its own check)
Section titled “Flow (each step has its own check)”- 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.mdskeleton) and thenscripts/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 agithub.comURL it shallow-sparse-clones the repo over SSH and records its LICENSE and the README’s credit lines. The last line is the VERDICT; readSOURCE.md. Nothing downloaded is ever executed.Verdict Meaning Route 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, locked Screenshots route: Readevery 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 licence Code Art, audio, fonts, names, content --- --- --- open (MIT, Apache, CC0, CC-BY…) port the logic; keep the LICENSE notice and attribution in NOTES.md and README reuse 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.txtas<path substring> # <licence, author, attribution kept>and in ASSETS.md; anything else is redrawnstudio-owned, or the author’s written permission (link it) as open as 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 pasted NONE shipped: original art in a clearly different style, own item names/set/values, own synthesised audio (method below) Record source-licence:in NOTES.md. FillFIDELITY.md(process steps, scene, HUD functions, caption, feedback, result, item variety; presentsimplified missing - 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 imagesand the sourceVERDICT; folder did not exist. - 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. - Implement
game/*.jsagainstreferences/core-api.md, using the original-art method. Check:bun ../_tools/build.cjs --no-auditexits 0, no page errors. - 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 aret1k-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. - 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 3reports/param-audit/<Key>/before|after.pngand confirm a real change. - 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. - 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.
- 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. - 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. - 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).
- Audio: synthesise with WebAudio via
PLA.audio.ctxandsfxGain(oscillators + filtered noise from a seeded LCG, neverMath.random); keep effects short. Nothing audible has been listened to by an agent: say so (unverified). - Prove it: the build gate
check-reference-cleanmust 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
fallbackand the Feel preset arehidden: true(kept in code and audited, excluded fromplayable-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)”| Gate | Passes when | Fails when |
|---|---|---|
audit.cjs --full | every parameter is wired and shows a before/after change | a parameter is unwired or shows no change |
check-reference-clean.cjs | no 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.cjs | loading, win end card and lose end card are byte-identical to the core-only _hello game | the 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. |
Publish
Section titled “Publish”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.
Fan-out (several games)
Section titled “Fan-out (several games)”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.
Done when
Section titled “Done when”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);
Related skills (this one links, never restates)
Section titled “Related skills (this one links, never restates)”| Need | Skill |
|---|---|
| SPEC from an html/apk/video ref, clean-room rules, two-side discipline | t1k-playablelabs-base-clean-room |
Parameter publish format, playable-config.json, dashboard | t1k-playablelabs-base-params |
| What the parameter audit proves; incremental re-audit | t1k-playablelabs-base-params-audit, t1k-playablelabs-web-params-audit |
| Playthrough harness, profile, strips, invariants | t1k-playablelabs-base-playthrough |
Web host contract (__plaGame__, scene-up) the built dist/ must keep | t1k-playablelabs-web-host-contract |
| Pack, smoke, networks | t1k-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.
Executed by
Section titled “Executed by”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.
| Step | Agent |
|---|---|
Run new-game.cjs / fetch-*.cjs, bun ../_tools/build.cjs, tools/playthrough.cjs; tabulate PASS/FAIL and exit codes | t1k-tester |
Study the source, write game/*.js, fill FIDELITY.md, judge a RED | t1k-playablelabs-base-web-developer |