72 lines
4.4 KiB
Markdown
72 lines
4.4 KiB
Markdown
# AGENTS.md - boardgame-core
|
|
|
|
## Commands
|
|
|
|
Shell environment: git bash (bash.exe) on Windows.
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
Run a single test file: `npx vitest run tests/core/game.test.ts`
|
|
Run tests matching a name: `npx vitest run -t "should create"`
|
|
|
|
`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\<T\>**: 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<string, Part<TMeta>>` 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/ # 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
|
|
|
|
- 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
|
|
- 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<typeof createInitialState>`
|
|
- Factory function prefix: `create` or `mutable` — `createGameHost`, `mutableSignal`
|
|
- Validation error messages in Chinese (e.g. `"参数不足"`)
|
|
|
|
## Testing
|
|
|
|
- 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` |