diff --git a/AGENTS.md b/AGENTS.md index b9f5157..e51392b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,92 +2,71 @@ ## Commands -Prefer `bash.exe`(C:\Users\Administrator\AppData\Local\Microsoft\WindowsApps\bash.exe) over Powershell. +Shell environment: git bash (bash.exe) on Windows. ```bash -npm run build # Build ESM bundle + declarations to dist/ (via tsup) -npm run test # Run vitest in watch mode -npm run test:run # Run vitest once (no watch) -npm run typecheck # Type-check without emitting (tsc --noEmit) +npm run build # ESM bundle + declarations to dist/ (tsup) +npm run build:samples # Build samples separately (tsup.samples.config.ts) +npm run test # vitest in watch mode +npm run test:run # vitest once (no watch) +npm run typecheck # tsc --noEmit ``` -### Running a single test file -```bash -npx vitest run tests/samples/tic-tac-toe.test.ts -``` +Run a single test file: `npx vitest run tests/core/game.test.ts` +Run tests matching a name: `npx vitest run -t "should create"` -### Running a single test by name -```bash -npx vitest run -t "should detect horizontal win for X" -``` +`npm run prepare` runs `npm run build` on install — if `inline-schema` isn't available, installs will fail. + +## Local Dependency + +`inline-schema` is a **local peer dependency** at `file:../inline-schema` — must exist as a sibling directory before `npm install`. Both vitest and tsup load custom plugins from it (`inline-schema/csv-loader/rollup` and `inline-schema/csv-loader/esbuild`). `yarn-spinner-loader` is also a local dependency at `file:../yarn-spinner-loader` — it can be changed and published if needed. It provides vitest and tsup/esbuild plugins for `.yarnproject` dialogue files. + +## Architecture + +- **MutableSignal\**: extends Preact Signal — `.value` to read, `.produce(draft => ...)` to mutate (uses `mutative`). `.produceAsync()` awaits interruption promises first, then mutates. +- **GameHost**: lifecycle manager — `start(seed?)`, `tryInput(string)`, `tryAnswerPrompt(def, ...args)`, `dispose()`. Reactive signals: `state`, `status`, `activePromptSchema`, `activePromptPlayer`, `activePromptHint`. +- **GameModule**: `{ registry?, createInitialState, start }`. `registry` defaults to `createGameCommandRegistry()` if omitted. +- **Command system**: CLI-style parsing with schema validation via `inline-schema`. `CommandRunner.run()` uses `this` bound to a `CommandRunnerContext`. +- **Prompt system**: `game.prompt(def, validator, currentPlayer?)` — validator **throws a string** to reject, **returns a value** to accept. `PromptEvent.tryCommit(Command | string)` returns `null` on success, error string on failure. `promptEnd` event fires after resolve or cancel. +- **Part collections**: `Record>` keyed by ID. `Object.values()` for iteration, `Object.keys()` for count/IDs. +- **Region system**: `createRegion()` factory; `partMap` maps position keys to part IDs. +- **Barrel exports**: `src/index.ts` is the single public API surface. ## Project Structure ``` src/ - core/ # Core game primitives (game, part, region) - samples/ # Example games (tic-tac-toe, boop) - utils/ # Shared utilities (mutable-signal, command, rng, async-queue) - index.ts # Single public API barrel export -tests/ # Mirrors src/ structure with *.test.ts files + core/ # game.ts, game-host.ts, part.ts, part-factory.ts, region.ts + samples/ # tic-tac-toe.ts, boop/, onitama/, regicide/, slay-the-spire-like/ + utils/ # mutable-signal.ts, rng.ts, async-queue.ts, command/ (8 files) + index.ts # barrel export + global.d.ts # *.yarnproject module declaration +tests/ # mirrors src/ with *.test.ts ``` +`src/utils/command/` is a directory: types.ts, command-parse.ts, command-registry.ts, command-runner.ts, command-validate.ts, command-apply.ts, schema-parse.ts, index.ts. + +## Samples Build + +`tsup.samples.config.ts` auto-discovers entries from `src/samples/` (directories → `index.ts`, files → direct `.ts`). It rewrites `@/core/*`, `@/utils/*`, and `@/index` imports to external `boardgame-core`. + ## Code Style -### Imports -- Use **double quotes** for local imports, **single quotes** for npm packages -- Use `@/**/*` for `./src/**/*` import alias (configured in tsconfig.json) -- Use `@/index` when importing from the public API surface in samples +- Double quotes for local imports, single quotes for npm packages +- `@/*` alias maps to `src/*` (configured in tsconfig, vitest, and tsup) - Group imports: npm packages first, then local `@/` imports, separated by blank line - -### Formatting -- **4-space indentation** (no tabs) -- **Semicolons** at statement ends -- **Arrow functions** for callbacks; `function` keyword for methods needing `this` (e.g. command handlers) -- No trailing whitespace -- Trailing commas in multi-line objects/arrays - -### Naming Conventions -- **Types/Interfaces**: `PascalCase` — `Part`, `Region`, `Command`, `IGameContext`, `GameHost` -- **Classes**: `PascalCase` — `MutableSignal`, `AsyncQueue`, `Mulberry32RNG`, `GameHost` -- **Functions**: `camelCase`, verb-first — `createGameContext`, `createGameHost`, `parseCommand`, `isValidMove` -- **Variables**: `camelCase` -- **Constants**: `UPPER_SNAKE_CASE` — `BOARD_SIZE`, `WINNING_LINES` -- **Test files**: `*.test.ts` mirroring `src/` structure under `tests/` -- **Factory functions**: prefix with `create` or `mutable` — `createGameContext`, `createGameHost`, `mutableSignal` - -### Types -- **Strict TypeScript** is enabled — no `any` -- Use **generics** heavily: `MutableSignal`, `CommandRunner` -- Use **type aliases** for object shapes (not interfaces) -- Use **discriminated unions** for results: `{ success: true; result: T } | { success: false; error: string }` -- Use `unknown` for untyped values, narrow with type guards or `as` +- 4-space indentation, semicolons, trailing commas in multi-line +- Arrow functions for callbacks; `function` keyword for methods needing `this` (e.g. command handlers) +- Strict TypeScript — no `any`; type aliases for object shapes (not interfaces) +- Discriminated unions for results: `{ success: true; result: T } | { success: false; error: string }` - Derive state types via `ReturnType` +- Factory function prefix: `create` or `mutable` — `createGameHost`, `mutableSignal` +- Validation error messages in Chinese (e.g. `"参数不足"`) -### Error Handling -- Prefer **result objects** over throwing: return `{ success, result/error }` -- When catching: `const error = e as Error;` then use `error.message` -- Use `throw new Error(...)` only for truly exceptional cases -- Validation error messages are in Chinese (e.g. `"参数不足"`) -- Prompt validators return `null` for valid input, `string` error message for invalid +## Testing -### Testing -- **Vitest** with globals enabled (`describe`, `it`, `expect` available without import) -- Use `async/await` for async tests -- Narrow result types with `if (result.success)` before accessing `result.result` -- Define inline helper functions in test files when needed (e.g. `createTestContext()`) -- No mocking — use real implementations -- For command tests: use `waitForPrompt()` + `promptEvent.tryCommit()` pattern -- Test helpers: `createTestContext()`, `createTestRegion()` - -## Architecture Notes - -- **Reactivity**: `MutableSignal` extends Preact Signal — access state via `.value`, mutate via `.produce(draft => ...)` -- **Command system**: CLI-style parsing with schema validation via `inline-schema` -- **Prompt system**: Commands prompt for input via `PromptEvent` with `resolve`/`reject`; `tryCommit` accepts `Command | string` and validates against schema before custom validator; `promptEnd` event fires when prompt completes (success or cancel) -- **GameHost**: Lifecycle manager for game sessions — provides `setup()`, `onInput()`, `dispose()`, reactive `state`/`status`/`activePromptSchema` signals -- **Barrel exports**: `src/index.ts` is the single public API surface -- **Game modules**: export `registry` and `createInitialState` for use with `createGameContextFromModule` or `createGameHost` -- **Region system**: plain `Region` type with `createRegion()` factory; `parts` are stored as `Record` keyed by ID, with `partMap` in regions mapping position keys to part IDs -- **Part collections**: Game state uses `Record>` (not arrays) for O(1) lookup by ID. Use `Object.values(parts)` when iteration is needed, `Object.keys(parts)` for count/IDs -- **Mutative**: used for immutable state updates inside `MutableSignal.produce()` +- Vitest with globals enabled, but **test files import explicitly**: `import { describe, it, expect } from 'vitest'` +- Use `@/` imports in test files (vitest resolve alias) +- Command/prompt test pattern: `waitForPrompt(ctx)` → `promptEvent.tryCommit(Command)` → returns `null` | error string +- No mocking — real implementations. Define inline helpers (`createTestContext()`, `waitForPrompt()`) per file. +- Narrow result types: `if (result.success)` before accessing `result.result` \ No newline at end of file diff --git a/src/samples/slay-the-spire-like/AGENTS.md b/src/samples/slay-the-spire-like/AGENTS.md new file mode 100644 index 0000000..f878bf5 --- /dev/null +++ b/src/samples/slay-the-spire-like/AGENTS.md @@ -0,0 +1,102 @@ +# slay-the-spire-like + +A Slay the Spire + Backpack Heroes hybrid roguelike sample. Players explore a point-crawl map, manage a tetris-style grid inventory, and fight enemies using cards generated from their equipment. + +## Game Design Docs + +Design docs are in the markdown files at this level: +- `01-overview.md` — core game concept, zones, encounter structure, combat rules, buff/debuff system +- `02-fighter.md` — Fighter class items (weapons, armor, tools, consumables, relics) +- `03-desert.md` — Desert zone enemies (minions, elites, boss) +- `data/rules.md` — combat state machine, turn order, effect timing rules + +## Module Structure + +This is **not** a `GameModule` yet — there is no `createInitialState`/`start`/`registry` wired up to `createGameHost`. The code is a library of subsystems that can be composed into a game module. + +### Subsystems + +| Directory | Purpose | Key exports | +|-----------|---------|-------------| +| `progress/` | Run state, player HP/gold, inventory management, map progression | `createRunState`, `moveToNode`, `resolveEncounter`, `damagePlayer`, `healPlayer`, `addItemFromCsv`, `removeItem`, `getReachableChildren` | +| `map/` | Point-crawl map generation and traversal | `generatePointCrawlMap`, `getNode`, `getChildren`, `getParents`, `hasPath`, `findAllPaths` | +| `grid-inventory/` | Tetris-style grid placement (place, move, rotate, flip items) | `createGridInventory`, `placeItem`, `removeItem`, `moveItem`, `rotateItem`, `flipItem`, `validatePlacement`, `getAdjacentItems` | +| `deck/` | Card/deck system (draw pile, hand, discard, exhaust) | `generateDeckFromInventory`, `createStatusCard`, `createDeckRegions`, `createPlayerDeck` | +| `data/` | CSV game data loaded via `inline-schema/csv-loader`. `.d.ts` files are auto-generated by the csv-loader plugin — do not edit by hand. | `heroItemFighter1Data`, `encounterDesertData`, `enemyDesertData`, `enemyIntentDesertData`, `effectDesertData`, `statusCardDesertData` | +| `dialogue/` | Yarn Spinner dialogue files (placeholder). Loaded via `yarn-spinner-loader`, a local peer dependency at `../yarn-spinner-loader` (like `inline-schema`, it can be changed and published if needed). | `encounters` yarnproject | +| `utils/` | Shape parsing and collision math | `parseShapeString`, `checkCollision`, `checkBounds`, `transformShape`, `rotateTransform`, `flipXTransform`, `flipYTransform` | + +### Data flow + +``` +CSV files (data/) + → inline-schema/csv-loader → typed JS objects (e.g. HeroItemFighter1) + → parseShapeString() converts shape strings → ParsedShape + → GridInventory holds placed items + → generateDeckFromInventory() generates cards per occupied cell +``` + +### Key types + +- **`RunState`** — top-level state: seed, map, player, inventory, currentNodeId, encounter state, resolved set. Designed for `MutableSignal.produce()` mutation. +- **`GridInventory`** — `items: Map>` + `occupiedCells: Set` for O(1) collision. Mutated directly inside `.produce()`. +- **`InventoryItem`** — id, shape (ParsedShape), transform (Transform2D), meta. Shape + transform determines which cells are occupied. +- **`GameCard`** — a `Part` bridging inventory items to the deck system. `sourceItemId` links back to the inventory item; `null` for status cards. +- **`PointCrawlMap`** — layered DAG: 10 layers (start → wild×2 → settlement → wild×2 → settlement → wild×2 → end). Wild = 3 nodes, Settlement = 4 nodes. +- **`MapNode`** — id, type (MapNodeType enum), childIds, optional encounter data from CSV. + +### Map generation + +`generatePointCrawlMap(seed?)` produces a deterministic map: +- 10 layers: Start → Wild(3) → Wild(3) → Settlement(4) → Wild(3) → Wild(3) → Settlement(4) → Wild(3) → Wild(3) → End +- Settlement layers guarantee ≥1 camp, ≥1 shop, ≥1 curio (4th slot random) +- Wild pair types are optimized to minimize same-type repetition +- Edge patterns avoid crossings: Start→all wild, Wild→Wild 1:1, Wild↔Settlement 3:4 or 4:3, Wild→all End + +### Shape system + +Items have shapes defined as movement strings parsed by `parseShapeString`: +- `o` = origin cell, `n/s/e/w` = move + fill, `r` = return to previous position +- Example: `"oesw"` = 2×2 block (origin, east, south, west = full square) +- Example: `"oe"` = 1×2 horizontal +- Example: `"onrersrw"` = cross/X shape + +Shapes are positioned via `Transform2D` (offset, rotation, flipX, flipY) and validated against the 6×4 grid. + +### Grid inventory + +All mutation functions (`placeItem`, `removeItem`, `moveItem`, `rotateItem`, `flipItem`) mutate the `GridInventory` **directly** — they must be called inside `produce()` callbacks. `validatePlacement` checks bounds + collisions before placement. + +### Card generation + +`generateDeckFromInventory(inventory)` creates one card per occupied cell in each item's shape. Cards carry `GameCardMeta` linking back to the source item and cell position. Status cards (wound, venom, etc.) are created separately via `createStatusCard`. + +## CSV data format + +All CSVs use `inline-schema` typed headers. The first row is a comment header, the second row is the schema row with types and references: +- `'energy'|'uses'` — union type +- `@enemyDesert` — foreign key reference to another CSV +- `[effect: @effectDesert; number][]` — array of structured references + +### heroItemFighter1.csv columns + +| Column | Type | Notes | +|--------|------|-------| +| type | `'weapon'|'armor'|'consumable'|'tool'` | | +| name | string | Display name (Chinese) | +| shape | string | Movement string for `parseShapeString` | +| costType | `'energy'|'uses'` | Energy = per-turn cost; Uses = limited uses | +| costCount | int | Cost amount | +| targetType | `'single'|'none'` | | +| price | int | Shop price | +| desc | string | Ability description (Chinese) | +| effects | `['self'|'target'|'all'|'random'; @effectDesert; number][]` | Effect references | + +## Conventions + +- Chinese is used for all user-facing strings (item names, error messages, effect descriptions) +- Discriminated union result types: `{ success: true } | { success: false, reason: string }` +- Mutation functions mutate state directly (inside `produce()`); validation is separate +- `Map` and `Set` are used in `GridInventory` and `PointCrawlMap` (not plain objects) — requires careful handling with `mutative` since it drafts Maps/Sets differently than plain objects +- Starter items defined in `progress/index.ts`: `['治疗药剂', '绷带', '水袋', '短刀', '剑']` +- Default player stats: 50 HP, 50 gold, 6×4 inventory \ No newline at end of file