diff --git a/AGENTS.md b/AGENTS.md index 98c51bb..931a6e5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,11 +45,13 @@ Must pass. Fix root causes; do not skip hooks. ## tsforge -[tsforge](https://tsforge.dev) is the org TypeScript harness. Point it at a fork of this repo; the gate is `bun run check`. +[tsforge](https://tsforge.dev) is the org TypeScript harness. The gate is `bun run check`. -The **`phaser` rule pack** auto-applies when `phaser` is in package.json: scene SHUTDOWN ownership, no global emitter leaks, no Phaser factories in `update`/`tick`, branded scene/texture keys, no `ignoreDestroy`. This repo's `eslint.config.js` covers a syntactic subset of that pack so `bun run check` stays honest without depending on unpublished tsforge. +**New game:** `/scaffold` → Phaser (or `tsforge scaffold --archetype phaser --dest ./my-game`). First prompt in that folder plans with a Phaser view-intent schema (scene / feature / content), not SaaS screens. Requires a tsforge with the Phaser adapter (tsforge `main`; next npm release after 0.51.1). -A Phaser **stack adapter** (planner schema, conventions, greenfield clone) is still planned, not shipped. Do **not** add `.tsforge/scaffold-manifest.json` — that file is how tsforge detects the fullstack BoringStack template. +**This tree:** the **`phaser` rule pack** auto-applies when `phaser` is in package.json (scene SHUTDOWN, no global emitter leaks, no Phaser factories in `update`/`tick`, branded keys, no `ignoreDestroy`). `eslint.config.js` covers a syntactic subset of that pack so `bun run check` stays honest without depending on a published tsforge. + +Do **not** add `.tsforge/scaffold-manifest.json` — that file is the fullstack BoringStack env surface. A Phaser scaffold writes `.tsforge/scaffold.json` (receipt); leave it. ## Deviations diff --git a/BUILD_THE_GAME.md b/BUILD_THE_GAME.md index 09dd6b3..ab1cec6 100644 --- a/BUILD_THE_GAME.md +++ b/BUILD_THE_GAME.md @@ -1,6 +1,6 @@ # Build the Game — the AI-First Guide -This document is the end-to-end walkthrough for building a game using this template. It's written for two audiences at once: a human who just clicked **"Use this template"**, and an AI agent that has joined the project mid-flight. Read it front-to-back once; come back for the sections you need. +This document is the end-to-end walkthrough for building a game using this template. It's written for two audiences at once: a human who just ran tsforge `/scaffold` → Phaser (or clicked **"Use this template"**), and an AI agent that has joined the project mid-flight. Read it front-to-back once; come back for the sections you need. > **First time making a game?** Read [`docs/learn/`](./docs/learn/README.md) **before** this document. It covers the mental-model shift, AI asset generation, game-design fundamentals, and the solo-dev workflow. This document assumes you already know what a sprite, tilemap, and core loop are. The `learn/` primer will teach you all three in 2.5 hours. @@ -62,9 +62,18 @@ Every non-trivial change walks the same pipeline: specify → clarify → plan ## 3. Zero to first commit -### Step 1 — Fork from the template +### Step 1 — Start from the template -Click **"Use this template"** on the GitHub page. Give your new repo a name. Clone locally. +**Preferred if you already use tsforge** — same wizard as BoringStack: + +```sh +tsforge scaffold --archetype phaser --dest ./my-game +cd my-game +``` + +Or, in a tsforge session: `/scaffold` → **Phaser** → folder name. That clones this repo, stamps `package.json` `name`, and writes `.tsforge/scaffold.json`. Requires a tsforge with the Phaser adapter (tsforge `main`; next npm release after 0.51.1). + +**Otherwise** — click **"Use this template"** on GitHub: ```sh gh repo create my-game --template boringstack-xyz/Phaser-TypeScript-AI-First-Starter --public --clone @@ -73,6 +82,8 @@ cd my-game ### Step 2 — Rename +Skip if you used tsforge scaffold (it already set the package name from the folder). + ```sh # Update the package name sed -i '' 's/"name": "phaser-ts-starter"/"name": "my-game"/' package.json @@ -334,16 +345,17 @@ Two faster inner loops: ## 9.5 Using tsforge -[tsforge](https://tsforge.dev) is the BoringStack TypeScript build harness. After forking: +[tsforge](https://tsforge.dev) is the BoringStack TypeScript build harness. + +To **create** the game, use Step 1 (`/scaffold` → Phaser). Then, from the project folder: ```sh -# from the fork tsforge ``` -Point it at this tree. The gate it should run is `bun run check`. The **`phaser` rule pack** auto-applies from the `phaser` dependency (scene shutdown, no factories in `update`, branded keys). This template's ESLint already covers a syntactic subset of that pack. +The first prompt plans with Phaser view intents (scene / feature / content), not list/detail/form screens. The gate is `bun run check`. The **`phaser` rule pack** auto-applies from the `phaser` dependency (scene shutdown, no factories in `update`, branded keys). This template's ESLint already covers a syntactic subset of that pack. -A dedicated Phaser **adapter** (greenfield clone, planner schema, Phaser conventions instead of React/Elysia) is planned in tsforge and **not shipped**. Do not add `.tsforge/scaffold-manifest.json` here — that file is how tsforge detects the fullstack BoringStack template. +Do not add `.tsforge/scaffold-manifest.json` here — that file is how tsforge configures the fullstack BoringStack template. After a Phaser scaffold, `.tsforge/scaffold.json` is the receipt that makes tsforge treat this tree as Phaser. --- diff --git a/README.md b/README.md index c76ba7d..7221e03 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ This repo is part of **[boringstack-xyz](https://github.com/boringstack-xyz)**. Backend engineer, tech lead, web developer who always wanted to make games? Start with [`docs/learn/`](./docs/learn/README.md) — a 2.5-hour primer that bridges "I can write code" to "I can generate art, design a core loop, and ship on itch.io." -> **Use this as a GitHub template.** Click **"Use this template"** on the repo page, then read [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md). +> Start a new game with [tsforge](https://tsforge.dev) (`/scaffold` → **Phaser**, or `tsforge scaffold --archetype phaser --dest ./my-game`), or click **"Use this template"** on GitHub. Then read [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md). ### After forking: one-time repo setup @@ -62,7 +62,7 @@ Everything else (CI, Scorecard, CodeQL, Dependabot) works out of the box. Desire | If you are... | Read next | | ----------------------------------------- | ------------------------------------------------------------------------------------------------- | | **A programmer who never shipped a game** | [`docs/learn/`](./docs/learn/README.md) | -| **A human forking this to build a game** | [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md) | +| **A human starting a game (tsforge or GitHub template)** | [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md) | | **An AI agent in a fresh session** | [`AGENTS.md`](./AGENTS.md) + [`docs/ai/catalog.md`](./docs/ai/catalog.md) | | **Just evaluating the architecture** | [`docs/ai/architecture.md`](./docs/ai/architecture.md) | | **Looking for the rules** | [`docs/ai/contribution-contract.md`](./docs/ai/contribution-contract.md) + [`.specify/memory/constitution.md`](./.specify/memory/constitution.md) | @@ -80,9 +80,22 @@ Arrow keys or WASD to move. Walk onto a yellow circle to score. Press **S** to s ## Using tsforge -[tsforge](https://tsforge.dev) is the BoringStack TypeScript build harness. Point it at a fork of this template; the gate is `bun run check`. +[tsforge](https://tsforge.dev) is the BoringStack TypeScript build harness. -The **`phaser` rule pack** auto-applies from the `phaser` dependency (scene shutdown, no factories in `update`, branded keys). A dedicated Phaser **stack adapter** (planner schema, conventions, greenfield clone) is planned and **not shipped yet**. Do not add a `.tsforge/scaffold-manifest.json` here; that file is how tsforge detects the fullstack template. +**New game** — same wizard as BoringStack: + +```sh +tsforge scaffold --archetype phaser --dest ./my-game +# or, in a tsforge session: /scaffold → Phaser → folder name +cd my-game +tsforge # first prompt plans the game (scene / feature / content slices) +``` + +No Docker, no `.env`. The clone keeps this template's WASD demo; new work extends it. The gate is `bun run check`. Requires a tsforge build that includes the Phaser adapter (tsforge `main`; the next npm release after 0.51.1). + +**Existing clone** — point tsforge at this tree. The **`phaser` rule pack** auto-applies from the `phaser` dependency (scene shutdown, no factories in `update`, branded keys). This repo's `eslint.config.js` covers a syntactic subset of that pack so `bun run check` stays honest without depending on a published tsforge. + +Do not add `.tsforge/scaffold-manifest.json` here. That file is how tsforge configures the fullstack BoringStack template. tsforge writes `.tsforge/scaffold.json` (a receipt) after a Phaser scaffold; that is expected. ## Architecture in 30 seconds diff --git a/docs/ai/architecture.md b/docs/ai/architecture.md index 2c0dace..d1b6ce5 100644 --- a/docs/ai/architecture.md +++ b/docs/ai/architecture.md @@ -55,7 +55,7 @@ Violations are lint errors (eslint-plugin-boundaries) and dep-cruiser errors in - **Scene keys are branded constants** (`asSceneKey` in `src/runtime/phaser/scenes/sceneKeys.ts`), never string literals in `scene.start` / `super()`. - **Scenes hook `Phaser.Scenes.Events.SHUTDOWN`** and dispose run-lifetime resources there. Do not set `ignoreDestroy`. Do not construct GameObjects in `update()`. -tsforge's `phaser` pack enforces the engine-API subset of these rules when pointed at a fork. +tsforge's `phaser` pack enforces the engine-API subset of these rules when pointed at this tree. `/scaffold` → Phaser clones this template; do not add `.tsforge/scaffold-manifest.json`. ## When the rules feel wrong