Skip to content

t1k:playable-start

FieldValue
Modulet1k-onboarding
Version2.7.51
Effortlow
Tools—

Keywords: build a playable, cocos playable, create a playable, create playable using playable engine, create playable using playable engines, i want to build a playable, i want to create a playable, make a playable, new playable, playable engine, playable engine game, playable engines, playable from brief, start a playable, use playable engine, using playable engines

/t1k:playable-start
<cocos|playable engine> [engine host: web|cocos-3.8|none] client: <name> project: <name> brief: <text> [--dry-run]

A thin router. Core decides which kits to install and who to hand off to. Everything after the handoff (repo, implementation, tracking, Discord, build) is owned by the installed kit, never by core.

The dev says once “I want to build/create a playable”, states the kit, and gives a brief.

Existing project that only needs services linked: /t1k:setup-project.

1 Parse node scripts/playable-start.cjs parse --prompt "<user text>"
-> {kit, kits, handoff, engineHost, preset, client, project, brief}.
Exit 2 `missing: kit` -> step 1a. Exit 2 `missing: engineHost` -> step 1b.
1a Ask ONE AskUserQuestion: "cocos" or "playable engine". Nothing else is asked here.
1b Ask ONE AskUserQuestion: the engine host — "web", "cocos-3.8" or "none". Never defaulted (see below).
2 Install project scope, into <dir> = the directory this session runs from (never --global):
cocos -> t1k init --kit cocos -y --modules playable --dir <dir>
t1k init --kit playablelabs -y --preset cocos --dir <dir>
playable engine -> t1k init --kit playablelabs -y --preset <host preset> --dir <dir>
then node scripts/playable-start.cjs check-preset --dir <dir> --preset <preset>
(exit 1 -> the installed kit predates the preset: stop, report, do NOT fall back)
3 Handoff invoke the kit's entry skill with {client, project, brief}

The kit is stated by the dev, never inferred from the brief. “cocos” selects the cocos kit plus playablelabs; “playable engine” selects playablelabs only.

A playable engine project is created from the kit alone. t1k init installs the playablelabs kit into the project’s own .claude/, and the kit ships the engine-host skills; there is no engine repository step, no git clone, no engine constant and no <dir>/PlaybleEngine. Never copy, symlink or clone an engine checkout from GitHub or from a local directory — the kit is the whole source, with or without a network to the engine repo.

Step 1b — the engine host is the dev’s choice, never defaulted

Section titled “Step 1b — the engine host is the dev’s choice, never defaulted”

The engine host (web, cocos-3.8 or none) is a per-project choice that must be stated. The script never assumes one: with no host stated, parse/plan leaves engineHost null and plan exits 2 missing: engineHost. Ask ONE AskUserQuestion (web / cocos-3.8 / none) and pass the answer on (--engine-host <host>, or engine host: <host> in the prompt). The host selects the playablelabs preset:

Engine hostPresetInstalls
webwebbase + web
cocos-3.8cocosbase + cocos
noneminimalbase only (no engine host; pack, smoke, params still ship)

The cocos kit path always builds a Cocos project, so its playablelabs preset is fixed at cocos and no host question is asked there.

t1k init is idempotent: re-running updates an installed kit and does not duplicate it. Both kits are multi-module, so -y needs a selector: cocos takes --modules playable (the module that owns the handoff skill; no preset resolves to it), playablelabs takes --preset <web|cocos|minimal>. Without one, t1k init -y exits 1 with --yes requires one of: --preset / --modules / --reuse-modules. Verify with t1k --version: each kit must show a badge. A failed install stops the flow and reports the failing command; never continue to the handoff on a partial install.

web and cocos are opt-in presets of theonekit-playablelabs (base+web and base+cocos). On a release that predates them the install fails, and this flow does not fall back to another preset — a plain standard install would silently miss the engine host. check-preset reads the installed registry (<dir>/.claude/t1k-modules.json) and, when the preset is absent, exits 1 with a message naming the preset and the minimum kit version that ships it. On exit 1: stop, update the kit (t1k modules update), re-run — never substitute a different preset.

<dir> is the directory the Claude session runs from, so the kit lands where the session looks. Never install into a sibling workspace folder or into one of the generated game repos instead.

Step 3 — handoff (a pointer, not a procedure)

Section titled “Step 3 — handoff (a pointer, not a procedure)”
KitEntry skill
cocost1k:cocos:playable:pipeline
playable enginet1k:playablelabs:ci:deliver

Pass {client, project, brief} verbatim as given. Core says nothing about repos; the entry skill owns them. The entry skill may not be visible until the session reloads skills: if it is absent after install, tell the dev to restart the session and re-run with the same prompt.

bun scripts/playable-start.cjs plan --prompt "<user text>" [--dir <path>] prints the kit choice, the engine host and its preset, the exact install commands and the handoff target. Nothing is executed.

Runs inline in the main session: the kit question and the engine-host question (AskUserQuestion), the installs and the handoff all need the conversation. scripts/playable-start.cjs parse|plan|check-preset is deterministic and run by the same session.

StepAgent
Parse the prompt, ask for a missing kit or engine host, run the installs, hand offmain session (inline)
Everything after the handoffthe installed kit’s entry skill