@drawcall/create

@drawcall/create is the project creator for the Drawcall 3D app/game stack. It does more than create files: it starts a new repo, installs the local agent toolkit, runs a harness to survey the available Drawcall assets and technologies, turns the user's prompt into a fixed goal, writes a plan, and then runs build turns until the plan is closed or the turn budget is reached.

The package is a local-orchestration layer over the rest of the Drawcall workspace. The sibling projects provide the actual capabilities:

• ../skills routes an agent from a topic in the user's goal to the right technology, pattern, and quality bar.
• ../market provides access to semantically searchable templates and assets.
• ../acta provides 3D character behavior and animation logic.
• ../uikitml provides spatial/XR UI authoring and conversion.
• ../vitexec provides runtime proof from inside a running Vite app.
• ../speech provides text-to-speech for apps that need voice output.
• ../flipbook allows to render flipbook animations.

create is the glue that installs those capabilities into a generated project and gives the selected harness a staged way to use them without shrinking the user's goal into a nominal prototype.

Why This Exists

The hard part of AI-generated 3D apps is not making the first canvas appear. It is keeping each harness turn grounded in what is real:

• what the user actually asked for,
• what the current product actually does,
• which assets and technologies actually fit,
• what still remains,
• and what has been proven in the running product.

@drawcall/create turns that into a small set of records and stages. A turn either thinks and writes context, or builds and proves a slice. The harness is never supposed to silently replace the goal with a smaller demo just because a part is hard or no fitting tool exists.

Pipeline

The full pipeline is:

scaffold -> (template || survey-assets || survey-technology) -> goal -> plan -> build...

The middle group runs concurrently during a full run because those stages write disjoint outputs:

• template may apply a fitting Market starter into the product.
• survey-assets writes a scratch survey of fitting Market assets.
• survey-technology writes a scratch survey of fitting installed skills and packages.

After that barrier, the goal stage writes the goal record and the plan stage writes the plan into plan/ — one numbered step file per step, with frontmatter (name, description, complexity: high | middle | low) that create verifies mechanically, reporting structural problems back into the planning session until every file parses. Each build turn is then handed exactly one step file; when the turn really changed the product, create deletes the consumed step file itself, and an empty plan/ is the done signal.

Every turn of the run carries a complexity, and --complexity-args routes all of them: the stages have fixed ratings (goal and plan high; template and the surveys low), a build turn takes its plan step's frontmatter rating (default middle), and fast mode rates its own turns (the canon goal turn high, per-file edits low, the repair turn middle). With no mapping given, the ratings change nothing.

Records

Generated projects use three committed records:

| File | Role | | ----------- | --------------------------------------------------------------------------- | | README.md | State record: what the product actually is right now. | | GOAL.md | Goal record: the fixed finished product and what real-done means. | | plan/ | Plan record: one numbered step file per remaining step, from state to goal. |

They also use scratch files that should not be committed:

| File | Role | | ----------------------- | ------------------------------------------------------------------------------ | | surveys/ASSETS.md | Asset survey: fitting Market templates/assets and named fit-gaps. | | surveys/TECHNOLOGY.md | Technology survey: fitting installed skills/packages and the APIs that matter. | | proof/ | Screenshots, clips, traces, and other proof files. | | drawcall-create.log | Full subprocess session log. |

The surveys are deliberately scratch. They ground the goal and plan stages, but the lasting truth of the project lives in README.md, GOAL.md, and plan/.

Stages

drawcall-create exposes the pipeline as stages:

| Stage | What it does | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | scaffold | Creates a new repo, base folders, .gitignore, package file, installed skills, and npm dependencies. No harness turn and no README. | | template | Runs one harness turn to search @drawcall/market for a fitting starter and apply it into the existing repo. Ensures a state-record README exists. | | survey-assets | Runs one survey turn and writes surveys/ASSETS.md. | | survey-technology | Runs one survey turn and writes surveys/TECHNOLOGY.md. | | goal | Writes GOAL.md from the user's prompt, current state, and surveys. | | plan | Writes one plan/ step file per step from the fixed goal, current state, and surveys, then updates README.md. Verified until it parses. | | build | Runs one build turn against the first remaining plan/ step file, then consumes that file. | | full | Runs the whole chain, then loops build turns up to the configured turn budget. |

Stages after scaffold operate on an existing git repo in the current directory. full and scaffold create a new project directory.

CLI

npm run dev -- --name my-game "make a third-person island adventure"

After publishing/building, the binary is:

drawcall-create --name my-game "make a third-person island adventure"

Useful options:

drawcall-create --stage scaffold --name my-game "make a marble maze"
drawcall-create --stage template "make a marble maze"
drawcall-create --stage survey-assets "make a marble maze"
drawcall-create --stage survey-technology "make a marble maze"
drawcall-create --stage goal "make a marble maze"
drawcall-create --stage plan "make a marble maze"
drawcall-create --stage build "make a marble maze"

drawcall-create --harness codex "make a marble maze"
drawcall-create --harness-timeout-minutes 30 "make a marble maze"
drawcall-create --max-turns 5 "make a marble maze"
drawcall-create --skip-template "make a marble maze"
drawcall-create --complexity-args '{"high":["--model","sota"],"low":["--model","cheap"]}' "make a marble maze"
drawcall-create --template [email protected] "make a marble maze"
drawcall-create --template none "make a marble maze"
drawcall-create "make a marble maze" -- --model gpt-5

Supported harnesses are opencode, codex, claude, pi, and gemini. If no harness is specified, create picks the first supported command available on PATH.

Use an exact name@version template reference for a reproducible run. A bare template name remains convenient for an exploratory local run, but resolves the Market's current latest version and must not be used for a benchmark or cloud family rerun.

Each harness invocation defaults to a 20 minute timeout. A full run defaults to 10 build turns. Use --skip-template on a full run to skip starter-template search and build from scratch while still surveying assets and technology.

Installed Toolkit

Fresh projects get agent skills from:

• drawcall-ai/vitexec
• drawcall-ai/uikitml
• drawcall-ai/acta
• drawcall-ai/market
• drawcall-ai/speech
• drawcall-ai/flipbook
• drawcall-ai/skills

Fresh projects also install the runtime packages that those skills commonly route to:

• vitexec
• @drawcall/uikitml
• @drawcall/acta
• @drawcall/market
• @drawcall/flipbook
• @pmndrs/uikit
• @pmndrs/pointer-events
• @pmndrs/viverse
• navcat
• three
• vite
• typescript
• elics
• postprocessing

create also patches local CLI shims for @drawcall/acta and @drawcall/market after installation so their CLIs resolve correctly inside a fresh generated project.

Related Projects

../skills

../skills is the general Drawcall skill pack. It is not one runtime library; it is the routing layer that teaches a harness which technology and pattern to use for a need in a 3D app.

Its skills cover:

• actions and input mapping through @pmndrs/viverse,
• audio coverage for feedback moments,
• camera behavior and camera math,
• ECS structure with elics,
• lighting and cascaded shadows,
• materials, textures, and color space,
• navigation meshes with navcat,
• performance profiling and optimization,
• BVH character physics through @pmndrs/viverse,
• pointer events through @pmndrs/pointer-events,
• postprocessing,
• spatial vs. 2D user interface routing,
• VFX and particles,
• world scale, terrain, fog, horizon, and density.

This repository installs drawcall-ai/skills so the technology-survey can map a user goal like "open-world shooter" to the specific skills and packages that carry world scale, input, camera, navigation, character motion, effects, UI, proof, and performance.

../market

../market is the asset marketplace. It defines versioned asset types such as model, humanoid-model, texture, humanoid-animation, template, sound-effect, background-music, environment, and flipbook.

create uses it in two places:

• the template stage searches for a fitting starter template and applies it into the generated repo;
• the asset-survey searches and previews assets so the later goal and plan can choose real content instead of vague placeholders.

Generated projects get the @drawcall/market package and the market skill so harnesses can search, preview, install, and reason about assets with the real CLI and API.

../acta

../acta is the character-behavior system. Acta behavior JSON describes locomotion, actions, animation states, timed effects, movement output, and jump output for Three.js characters. It supports playable characters, NPCs, enemies, companions, and crowds.

In generated projects, Acta is the preferred fit when the user asks for an embodied thing that moves, acts, aims, jumps, attacks, or reacts. The harness can validate behavior JSON, test animation/effect timelines, or convert behavior JSON into TypeScript character classes.

../uikitml

../uikitml is an HTML-like markup format and CLI for spatial UI. Harnesses can write .uikitml, validate it, render a preview, and convert it into Three.js, React Three Fiber, IWSDK, or pmndrs/uikit code.

The general ../skills UI skill routes UI work:

• spatial or XR panels use drawcall-ai/uikitml;
• ordinary non-XR HUDs and menus can stay as HTML/CSS over the canvas.

../vitexec

../vitexec lets a harness run scripts inside a live Vite app with Playwright. It can drive input, inspect runtime state, collect logs, take screenshots, record video, and capture traces.

create treats this as the default proof tool for generated Vite/Three.js apps. A build turn is not done just because TypeScript compiles; it needs a proof-run that demonstrates the product behavior in the running app.

../speech

../speech is a production REST API for text-to-speech. It is installed as an agent skill so goals involving voice, narration, NPC speech, or accessibility can route to a real service instead of hand-waving audio output.

../flipbook

../flipbook provides @drawcall/flipbook, a tiny Three.js runtime for KTX2 flipbook billboards such as explosions, flames, and particles. Market flipbook assets are meant to render through this package.

Design Contract

The prompts in src/prompts.ts enforce the same principles across all stages:

• Real, not nominal: a step is done only when the product actually does the thing when run.
• Fit the tools: use the installed Drawcall skills, packages, and Market assets where they genuinely fit.
• Name fit-gaps honestly instead of silently substituting fake stand-ins.
• Present feedback where the player perceives it, without debug UI leaking into the default product.
• See and judge each step against the goal's look and feel by observing the real running product from the player's seat, iterating until it reads right — not by checking mere presence.
• Treat moving or acting things as embodied: motion, animation, behavior, and feedback belong to the feature, not to a later polish pass.

The vocabulary behind those rules lives in LANGUAGE.md.

Development

npm install
npm test
npm run typecheck
npm run build

Important source files:

• src/command.ts defines the CLI surface and argument parsing (the create-command).
• src/create.ts runs the create-session: it orchestrates the pipeline of stages and the build-turn loop.
• src/scaffold.ts creates the repo, installs skills/packages, commits records, and patches local CLI shims.
• src/harness.ts builds the harness-command for each supported harness and bundles it as the harness-runner that runs one harness-turn.
• src/subprocess.ts defines the command-runner interface and the built-in subprocess-runner (spawns the process, writes the session-log, forwards signals, enforces the timeout).
• src/progress-log.ts writes progress-notes and mirrors them into the session-log.
• src/prompts.ts defines the harness prompts for each stage.
• src/constants.ts defines stage names, installed skills/packages, record paths, scratch paths, timeouts, and the build-turn-budget.

The vocabulary used throughout (records, surveys, turns, stages, runners) is defined in LANGUAGE.md.

The tests in test/index.test.ts encode the expected stage order, stage isolation, harness selection, generated files, commits, and prompt contracts.