# Vibesmith

> Public docs for the Vibesmith framework — AI-augmented WebGL game
> development on Vite + React + R3F + Three.js. Guides, cookbook,
> anti-patterns, reference.

This file is the agent-discoverable manifest of the site, following
the emerging [llms.txt](https://llmstxt.org/) convention.

## Getting started

- [Introduction](https://tombee.github.io/vibesmith-docs/introduction/): friendly intro — what Vibesmith gives you, who it's for, what it deliberately isn't
- [Comparisons FAQ](https://tombee.github.io/vibesmith-docs/faq/): vs Three.js, React Three Fiber, Babylon.js, web-export engines, web-native competitors — and when to pick one of those instead
- [Positioning](https://tombee.github.io/vibesmith-docs/positioning/): the strategic bet — narrow runtime (TS+R3F web target) + durable intelligence layer (canon, providers, MCP, recipes — engine-portable in principle); portability through architecture, not abstraction; Bevy as the canonical future-engine proving-ground; what success and falsification look like
- [Principled non-features](https://tombee.github.io/vibesmith-docs/principled-non-features/): authoring affordances Vibesmith deliberately refuses — no JSX rewrite, no visual scripting, no drag-reference-onto-field, no shadow scene file, no name-registry indirection — with what the framework provides instead. The AI-fluency bet in operation.
- [Quick start](https://tombee.github.io/vibesmith-docs/getting-started/quick-start/): `vibesmith init` + project layout

## Concepts

- [Concepts index](https://tombee.github.io/vibesmith-docs/concepts/): first-principles explainers for the words vibesmith uses; for complete newcomers + as a glossary
- [Scene](https://tombee.github.io/vibesmith-docs/concepts/scene/): what your game looks like at one moment; no `Scene` class — scenes are mounted React component trees inside the editor's `<Canvas>`
- [Script](https://tombee.github.io/vibesmith-docs/concepts/script/): code that runs every frame on a part of the scene; `defineGameScript` + `onMount` / `onTick` / `onIntent` / `onUnmount`; bound to scene nodes by `script="<id>"`
- [Prefab](https://tombee.github.io/vibesmith-docs/concepts/prefab/): a generative content unit (recipe + generator + critic + AI brief + preview); not a Unity-style serialised template — produces fresh compositions each run
- [Snapshot](https://tombee.github.io/vibesmith-docs/concepts/snapshot/): captured launchable + replayable game state; the unit of UX iteration, AI authoring, and bug repro; preserved across HMR
- [Recipe](https://tombee.github.io/vibesmith-docs/concepts/recipe/): a curated AI-readable pattern for something hard to generate from scratch — VFX, shaders, cutscenes, mixes; framework's retrieve-adapt-validate substrate
- [Capability](https://tombee.github.io/vibesmith-docs/concepts/capability/): a thing the framework can do (image.generate, llm.call) abstracted over providers; the framework's moat layer
- [Provider](https://tombee.github.io/vibesmith-docs/concepts/provider/): the concrete service that implements a capability; four-tier priority (local → free → pay-per-use → subscription)
- [Extension](https://tombee.github.io/vibesmith-docs/concepts/extension/): a panel or feature that plugs into the editor; everything in the editor is one; opt-in by default post Track UX-2
- [Intent](https://tombee.github.io/vibesmith-docs/concepts/intent/): a player action as data; `ctx.dispatch` / `onIntent`; multiplayer + replay come along for free
- [Signal](https://tombee.github.io/vibesmith-docs/concepts/signal/): a one-way "X happened" notification; `ctx.signal` / `ctx.onSignal`; complement to intent

## Cookbook

- [Cookbook index](https://tombee.github.io/vibesmith-docs/cookbook/): conventions, recipe roadmap
- [Instancing](https://tombee.github.io/vibesmith-docs/cookbook/instancing/): rendering 50+ identical objects in one draw call
- [Animations](https://tombee.github.io/vibesmith-docs/cookbook/animations/): GLTF skeletal animations + procedural lerp / spring transforms
- [Positional footsteps](https://tombee.github.io/vibesmith-docs/cookbook/positional-footsteps/): wire 3D footsteps from animation events through the audio runtime, with seeded pitch jitter for scenario-deterministic replay
- [Performance debugging](https://tombee.github.io/vibesmith-docs/cookbook/perf-debugging/): `gl.info`, attribution checklist, perf tools
- [Writing a game script](https://tombee.github.io/vibesmith-docs/cookbook/writing-game-scripts/): `defineGameScript` lifecycle (mount → tick → unmount), `GameScriptContext` surface, what you can / shouldn't do inside a script
- [Inspectable parameters (data-shape coaching)](https://tombee.github.io/vibesmith-docs/cookbook/inspectable-parameters/): declare `defineGameScript` parameters as a Zod object; one schema feeds the runtime, the inspector panel, and your AI assistant — without decorating your code
- [Install Vibesmith MCP into your coding assistant](https://tombee.github.io/vibesmith-docs/cookbook/install-mcp/): `vibesmith mcp install claude-code | codex | copilot` — idempotent install + diagnose + uninstall per host; auth + scope guidance; capability-tier matrix

## Anti-patterns

- [R3F anti-patterns](https://tombee.github.io/vibesmith-docs/anti-patterns/): 12 numbered entries covering recurring R3F mistakes

## Reference

- [Engine patterns](https://tombee.github.io/vibesmith-docs/reference/engine-patterns/): Unity-isms ↔ Three.js + R3F translation
- [Audio runtime](https://tombee.github.io/vibesmith-docs/reference/audio-runtime/): WebAudio wrapper, `<AudioEmitter>` on `Object3D`, fixed five-bus mixer, recipe-canon adapter, scenario capture + replay, deferred-init autoplay gate
- [Scene construction](https://tombee.github.io/vibesmith-docs/reference/scene-construction/): Recipe → Generator → Composition pipeline
- [Prefab system](https://tombee.github.io/vibesmith-docs/reference/prefab-system/): content units (recipe + generator + director + AI brief + preview)
- [Material system](https://tombee.github.io/vibesmith-docs/reference/material-system/): material roles, tier capability, shader policy
- [Performance budgets](https://tombee.github.io/vibesmith-docs/reference/performance-budgets/): Tier 0 budget table
- [WebGL constraints](https://tombee.github.io/vibesmith-docs/reference/webgl-constraints/): WebGL 2 / WebGPU hard limits
- [Adaptive rendering](https://tombee.github.io/vibesmith-docs/reference/adaptive-rendering/): LOW / MEDIUM / HIGH / ULTRA tier auto-scaling
- [Renderer configuration](https://tombee.github.io/vibesmith-docs/reference/renderer-configuration/): backend preference, context options, DPR, detection hooks, custom-shader policy
- [Renderer feature matrix](https://tombee.github.io/vibesmith-docs/reference/renderer-feature-matrix/): per-feature WebGL 2 / WebGPU support + graceful-degrade / feature-gate / backend-required patterns
- [Physics](https://tombee.github.io/vibesmith-docs/reference/physics/): `definePhysics({ id, world, step, raycast, query })` adapter contract; `<RigidBody>` + `<PhysicsScene>` R3F components; entity-id-keyed `ctx.physics` queries + mutations; scenario capture + replay; Rapier as the default adapter
- [Animation runtime](https://tombee.github.io/vibesmith-docs/reference/animation-runtime/): state machine + blend tree + curve evaluator over Three's `AnimationMixer`; `<Animator>` scene-node component; JSON / TS graph authoring; `ctx.animator(id)` parameter bindings; scenario serializer for deterministic replay
- [Asset catalogue](https://tombee.github.io/vibesmith-docs/reference/asset-catalogue/): first capability extension instance — SQLite-shaped store + ingest pipeline (scan → render → classify → embed) + query layer (`find` / `similar_to` / `pairs` / `gaps` / `dedup`); R3F consumer API (`<PackAsset>` + `useCatalogueQuery`); cmd+P + MCP entry points
- [Asset packs](https://tombee.github.io/vibesmith-docs/reference/asset-packs/): third-party vendor packs as canon-substrate seeds — pack manifest, vendor-adapter pattern, texture dedup, style-profile extraction, R3F consumer API, in-pack-style AI generation
- [QA strategy](https://tombee.github.io/vibesmith-docs/reference/qa-strategy/): four-tier QA + text telemetry
- [Scenario-driven dev](https://tombee.github.io/vibesmith-docs/reference/scenario-driven-dev/): deterministic-state UX iteration substrate
- [Director pattern](https://tombee.github.io/vibesmith-docs/reference/director-pattern/): AI-assisted content director
- [AI assistant](https://tombee.github.io/vibesmith-docs/reference/ai-assistant/): context-aware in-browser assistant
- [First-party chat panel](https://tombee.github.io/vibesmith-docs/reference/first-party-chat-panel/): BYOK chat panel inside the dev tooling for users with an LLM API key but no Claude Max / Copilot Pro / Codex Plus sub; threaded conversations + per-thread provider selector + streaming token meter (no dollar conversion) + inline `↳ tip:` rendering + JSONL persistence; explicitly lighter than a full coding-assistant harness — the on-ramp
- [Task context](https://tombee.github.io/vibesmith-docs/reference/task-context/): `context_assemble(task_id, state_ref)` contract every AI surface in Vibesmith calls through; v0 ~15-task taxonomy; `TaskContextBundle` wire format; consumer-contributed tasks under `.vibesmith/tasks/manifests/`; `task-context-preview` standard extension as the cmd+P canary
- [MCP tiered surface](https://tombee.github.io/vibesmith-docs/reference/mcp-tiered-surface/): the Tier-1 always-loaded router (≤ 4k schema tokens) + Tier-2 deferred catalog (schemas fetched via `tools_find`) + `vibesmith://` Resources for read data + `vibesmith.toml [project].type / [capabilities] / [mcp]` project-shape gating; `vibesmith doctor --mcp` inspection; CI per-namespace budget
- [Project upgrade model](https://tombee.github.io/vibesmith-docs/reference/project-upgrade-model/): customer-owned vs framework-managed split, `[deps]` install flow, `vibesmith doctor` checks (incl. `--upgrade-project`), unified `vibesmith upgrade` across `vibesmith.toml` + SHA-pinned project shapes, opt-in starter-diff, semver upgrade ceremony

## For agents

- [Agent context](https://tombee.github.io/vibesmith-docs/agents/): intent-to-doc mapping, discovery surfaces, style conventions

## Source

This site is generated from
[tombee/vibesmith-docs](https://github.com/tombee/vibesmith-docs).
Framework source (private) lives at `tombee/vibesmith`. Cookbook and
reference docs are the canonical home for consumer-facing knowledge;
the framework repo's `docs/` holds internal architecture artifacts
(ADRs, roadmap, methodology, proactive-ledger).