# API 参考

本文档记录游戏模组开发者需要使用的公共 API。

## 核心接口

### `IGameContext<TState>`

游戏运行的核心上下文，提供状态访问、随机数、命令执行和提示系统。

```typescript
interface IGameContext<TState extends Record<string, unknown> = {}> {
    readonly value: TState;                           // 当前游戏状态（只读）
    readonly rng: ReadonlyRNG;                        // 随机数生成器（只读）

    // 状态更新
    produce(fn: (draft: TState) => void): void;       // 同步变更状态（基于 mutative）
    produceAsync(fn: (draft: TState) => void): Promise<void>;  // 异步变更状态（等待中断）

    // 命令执行
    run<T>(input: string): Promise<CommandResult<T>>;           // 执行命令字符串
    runParsed<T>(command: Command): Promise<CommandResult<T>>; // 执行已解析的命令

    // 提示系统
    prompt<TResult, TArgs>(
        def: PromptDef<TArgs>,
        validator: PromptValidator<TResult, TArgs>,
        currentPlayer?: string | null
    ): Promise<TResult>;
}
```

**使用示例：**

```typescript
// 读取状态
const currentPlayer = game.value.currentPlayer;

// 同步更新状态
game.produce((state) => {
    state.score += 10;
});

// 异步更新状态（等待动画完成）
await game.produceAsync((state) => {
    state.phase = 'next';
});

// 等待玩家输入
const result = await game.prompt(
    prompts.move,
    (from, to) => {
        if (!isValidMove(from, to)) {
            throw '无效移动';
        }
        return { from, to };
    }
);
```

---

### `GameModule<TState, TResult>`

游戏模块的类型定义，这是开发者创建游戏时需要导出的核心结构。

```typescript
type GameModule<TState extends Record<string, unknown>, TResult = unknown> = {
    registry?: CommandRegistry<IGameContext<TState>>;  // 可选的命令注册表
    createInitialState: () => TState;                   // 创建初始状态
    start: (ctx: IGameContext<TState>) => Promise<TResult>;  // 游戏主循环
}
```

---

### `createGameCommandRegistry<TState>()`

创建游戏命令注册表，游戏模组用它来注册自定义命令。

```typescript
function createGameCommandRegistry<TState extends Record<string, unknown> = {}>(): CommandRegistry<IGameContext<TState>>
```

**使用示例：**

```typescript
import { createGameCommandRegistry, IGameContext } from '@/index';

export type GameState = { score: number };
export const registry = createGameCommandRegistry<GameState>();

// 注册命令
registry.register('addScore <amount:number>', async function(ctx, amount) {
    ctx.produce((state) => {
        state.score += amount;
    });
    return { success: true, result: undefined };
});
```

---

## 提示系统

### `createPromptDef<TArgs>(schema, hintText?)`

从字符串模式创建 `PromptDef`。

```typescript
function createPromptDef<TArgs>(
    schema: CommandSchema | string,
    hintText?: string
): PromptDef<TArgs>
```

**使用示例：**

```typescript
import { createPromptDef } from '@/index';

export const prompts = {
    // 必需参数
    play: createPromptDef<[PlayerType, number, number]>(
        'play <player> <row:number> <col:number>',
        '选择下子位置'
    ),

    // 可选参数
    draw: createPromptDef<[number?]>(
        'draw [count:number]',
        '抽牌'
    ),

    // 带选项
    trade: createPromptDef<[string, string]>(
        'trade <give> <receive> [--force]',
        '交易'
    ),
};
```

---

### `PromptDef<TArgs>`

提示定义，用于 `context.prompt()` 方法。

```typescript
type PromptDef<TArgs extends any[] = any[]> = {
    schema: CommandSchema;    // 命令模式定义
    hintText?: string;        // 可选的提示文本
}
```

---

### `PromptValidator<TResult, TArgs>`

提示验证函数类型。验证器函数接收解析后的参数，应返回结果或抛出字符串错误。

```typescript
type PromptValidator<TResult, TArgs extends any[] = any[]> = (...params: TArgs) => TResult;
```

**验证器规则：**
- 返回任意值表示验证成功，该值将作为 `prompt()` 的返回值
- 抛出字符串错误表示验证失败，错误消息会返回给玩家，玩家可重新输入
- 玩家取消输入时，`prompt()` 会抛出异常

---

### `PromptEvent`

提示事件对象，通过 `commandRunnerContext.on('prompt', handler)` 监听。

```typescript
type PromptEvent = {
    schema: CommandSchema;
    hintText?: string;
    currentPlayer: string | null;
    tryCommit: (commandOrInput: Command | string) => string | null;  // null=成功，string=错误消息
    cancel: (reason?: string) => void;
}
```

---

## 零件系统 (Part)

### `Part<TMeta>`

游戏中的可操作物件（棋子、卡牌、骰子等）。

```typescript
type Part<TMeta = {}> = {
    id: string;                    // 唯一标识
    sides?: number;                // 总面数（用于骰子/多面牌）
    side?: number;                 // 当前面
    alignments?: string[];         // 可用对齐方式
    alignment?: string;            // 当前对齐方式
    regionId: string;              // 所属区域 ID
    position: number[];            // 在区域中的位置坐标
} & Immutable<TMeta>;             // 自定义元数据（不可变）
```

**使用示例：**

```typescript
import { Part } from '@/index';

export type PieceMeta = {
    owner: 'X' | 'O';
    type: 'pawn' | 'king';
};

export type Piece = Part<PieceMeta>;

// 访问元数据
const piece: Piece = ...;
console.log(piece.owner);  // 'X'
console.log(piece.type);   // 'pawn'
```

---

### 零件操作函数

#### `flip<TMeta>(part)`

翻转到下一面（循环）。

```typescript
function flip<TMeta>(part: Part<TMeta>): void
```

#### `flipTo<TMeta>(part, side)`

翻转到指定面。

```typescript
function flipTo<TMeta>(part: Part<TMeta>, side: number): void
```

#### `roll<TMeta>(part, rng)`

用 RNG 随机掷骰子。

```typescript
function roll<TMeta>(part: Part<TMeta>, rng: RNG): void
```

---

## 零件工厂 (Part Factory)

### `createParts<T>(item, getId, count?)`

创建多个相同类型的零件。

```typescript
function createParts<T>(
    item: T,
    getId: (index: number) => string,
    count?: number
): Record<string, Part<T>>
```

**使用示例：**

```typescript
import { createParts } from '@/index';

const pieces = createParts(
    { owner: 'X', type: 'pawn' },
    (i) => `piece-x-${i}`,
    5  // 创建 5 个
);
```

---

### `createPartsFromTable<T>(items, getId, getCount?)`

从配置表批量创建零件。

```typescript
function createPartsFromTable<T>(
    items: readonly T[],
    getId: (item: T, index: number) => string,
    getCount?: ((item: T) => number) | number
): Record<string, Part<T>>
```

**使用示例：**

```typescript
import { createPartsFromTable } from '@/index';

const cardTable = [
    { name: 'fireball', damage: 3 },
    { name: 'shield', defense: 2 },
];

const cards = createPartsFromTable(
    cardTable,
    (item) => item.name,
    (item) => item.name === 'fireball' ? 4 : 2  // 每种卡牌的数量
);
```

---

## 区域系统 (Region)

### `Region`

游戏区域（棋盘、手牌区等）。

```typescript
type Region = {
    id: string;                     // 区域 ID
    axes: RegionAxis[];             // 坐标轴定义
    childIds: string[];             // 包含的零件 ID 列表
    partMap: Record<string, string>; // 位置 -> 零件 ID 映射
}
```

---

### `RegionAxis`

区域的一个坐标轴。

```typescript
type RegionAxis = {
    name: string;
    min?: number;
    max?: number;
    align?: 'start' | 'end' | 'center';  // 对齐方式
}
```

---

### `createRegion(id, axes)`

创建区域。

```typescript
function createRegion(id: string, axes: RegionAxis[]): Region
```

**使用示例：**

```typescript
import { createRegion, createRegionAxis } from '@/index';

// 创建 3x3 棋盘
const board = createRegion('board', [
    createRegionAxis('row', 0, 2),
    createRegionAxis('col', 0, 2),
]);

// 或简写
const board = createRegion('board', [
    { name: 'row', min: 0, max: 2 },
    { name: 'col', min: 0, max: 2 },
]);
```

---

### `createRegionAxis(name, min?, max?, align?)`

创建坐标轴。

```typescript
function createRegionAxis(
    name: string,
    min?: number,
    max?: number,
    align?: 'start' | 'end' | 'center'
): RegionAxis
```

---

### 区域操作函数

#### `applyAlign<TMeta>(region, parts)`

根据轴的 `align` 配置重新排列零件位置。

```typescript
function applyAlign<TMeta>(region: Region, parts: Record<string, Part<TMeta>>): void
```

#### `shuffle<TMeta>(region, parts, rng)`

在区域内随机打乱零件位置。

```typescript
function shuffle<TMeta>(region: Region, parts: Record<string, Part<TMeta>>, rng: RNG): void
```

#### `moveToRegion<TMeta>(part, sourceRegion, targetRegion, position?)`

将零件从一个区域移动到另一个区域。

```typescript
function moveToRegion<TMeta>(
    part: Part<TMeta>,
    sourceRegion: Region | null,
    targetRegion: Region | null,
    position?: number[]
): void
```

---

## 命令系统 (Command System)

### `Command`

解析后的命令对象。

```typescript
type Command = {
    name: string;                                    // 命令名
    flags: Record<string, true>;                     // 标志（如 --verbose）
    options: Record<string, unknown>;                // 选项（如 --player X）
    params: unknown[];                               // 位置参数
}
```

---

### `CommandSchema`

命令模式定义，用于验证和解析。

```typescript
type CommandSchema = {
    name: string;
    params: CommandParamSchema[];
    options: Record<string, CommandOptionSchema>;
    flags: Record<string, CommandFlagSchema>;
}
```

---

### `CommandResult<T>`

命令执行结果（判别联合类型）。

```typescript
type CommandResult<T = unknown> =
    | { success: true; result: T }
    | { success: false; error: string }
```

**使用示例：**

```typescript
const result = await game.run('move piece1 piece2');

if (result.success) {
    console.log('命令执行成功', result.result);
} else {
    console.error('命令执行失败', result.error);
}
```

---

### `CommandDef<TContext, TFunc>`

命令定义对象，用于 `registry.register()`。

```typescript
type CommandDef<TContext, TFunc extends CommandFunction<TContext>> = {
    schema: string | CommandSchema;
    run: TFunc;
}

type CommandFunction<TContext> = (ctx: TContext, ...args: any[]) => Promise<unknown>;
```

---

### `CommandRegistry<TContext>`

命令注册表。

```typescript
class CommandRegistry<TContext> extends Map<string, CommandRunner<TContext>> {
    register<TFunc>(
        ...args: [schema: CommandSchema | string, run: TFunc] | [CommandDef<TContext, TFunc>]
    ): (ctx, ...args) => Promise<TResult>
}
```

**注册命令的两种方式：**

```typescript
// 方式 1：直接传入 schema 和函数
registry.register('move <from> <to>', async function(ctx, from, to) {
    ctx.produce((state) => { /* 修改状态 */ });
    return { success: true, result: undefined };
});

// 方式 2：使用 CommandDef 对象
registry.register({
    schema: 'move <from> <to>',
    run: async function(ctx, from, to) {
        ctx.produce((state) => { /* 修改状态 */ });
        return { success: true, result: undefined };
    }
});
```

---

### `parseCommand(input, schema?)`

解析命令字符串为 `Command` 对象。

```typescript
function parseCommand(input: string, schema?: CommandSchema): Command
```

---

### `parseCommandSchema(schemaStr, name?)`

从字符串模式解析命令模式。

```typescript
function parseCommandSchema(schemaStr: string, name?: string): CommandSchema
```

**Schema 语法：**
- `<param>` - 必需参数
- `[param]` - 可选参数
- `[param:type]` - 带类型验证的参数（如 `[count:number]`）
- `--option:value` - 必需选项
- `[-o value]` - 可选选项
- `[--flag]` - 可选标志

---

## 随机数生成器 (RNG)

### `ReadonlyRNG`

只读 RNG 接口（`IGameContext.rng` 返回此类型）。

```typescript
interface ReadonlyRNG {
    next(max?: number): number;     // [0,1) 随机数，或 [0,max)
    nextInt(max: number): number;   // [0,max) 随机整数
}
```

---

### `RNG`

可设置种子的 RNG 接口。

```typescript
interface RNG extends ReadonlyRNG {
    setSeed(seed: number): void;
    getSeed(): number;
}
```

**使用示例：**

```typescript
// 在 IGameContext 中使用
const roll = game.rng.nextInt(6) + 1;  // 1-6 的随机数

// 在区域操作中使用时
shuffle(region, parts, rng);  // 需要传入 RNG
```

---

## 可变信号 (MutableSignal)

### `MutableSignal<T>`

扩展自 Preact Signal 的可变信号类，支持 mutative-style 的 `produce` 方法。

```typescript
class MutableSignal<T> extends Signal<T> {
    produce(fn: (draft: T) => void): void;
    addInterruption(promise: Promise<void>): void;    // 添加中断 Promise（用于动画等待）
    clearInterruptions(): void;                        // 清除所有中断
    produceAsync(fn: (draft: T) => void): Promise<void>;  // 等待中断后更新状态
}
```

---

### `mutableSignal<T>(initial?, options?)`

创建可变信号。

```typescript
function mutableSignal<T>(initial?: T, options?: SignalOptions<T>): MutableSignal<T>
```

---

## 游戏主机 (GameHost)

### `GameHost<TState, TResult>`

游戏会话的生命周期管理器。

```typescript
class GameHost<TState, TResult> {
    readonly state: ReadonlySignal<TState>;                    // 游戏状态（响应式）
    readonly status: ReadonlySignal<GameHostStatus>;           // 运行状态
    readonly activePromptSchema: ReadonlySignal<CommandSchema | null>;   // 当前活动提示的模式
    readonly activePromptPlayer: ReadonlySignal<string | null>;          // 当前等待输入的玩家
    readonly activePromptHint: ReadonlySignal<string | null>;            // 当前提示文本

    tryInput(input: string): string | null;                    // 尝试提交输入，返回错误信息或 null
    tryAnswerPrompt<TArgs>(def: PromptDef<TArgs>, ...args: TArgs): void;  // 尝试回答提示
    addInterruption(promise: Promise<void>): void;             // 注册中断 Promise（用于动画）
    clearInterruptions(): void;                                // 清除所有中断
    start(seed?: number): Promise<TResult>;                    // 启动游戏
    dispose(): void;                                           // 销毁游戏
    on(event: 'start' | 'dispose', listener: () => void): () => void;  // 注册事件监听
}
```

---

### `GameHostStatus`

```typescript
type GameHostStatus = 'created' | 'running' | 'disposed';
```

---

### `createGameHost<TState>(gameModule)`

从游戏模块创建 `GameHost` 实例。

```typescript
function createGameHost<TState extends Record<string, unknown>>(
    gameModule: GameModule<TState>
): GameHost<TState>
```

**使用示例：**

```typescript
import { createGameHost } from '@/index';
import { gameModule } from './my-game';

const host = createGameHost(gameModule);

// 启动游戏
const result = await host.start(42);  // 传入种子

// 提交玩家输入
const error = host.tryInput('play X 0 0');
if (error) {
    console.error('输入错误:', error);
}

// 监听事件
host.on('start', () => console.log('游戏开始'));
host.on('dispose', () => console.log('游戏结束'));

// 销毁游戏
host.dispose();
```

---

## Preact Signals 重新导出

```typescript
export * from '@preact/signals-core';
```

开发者可直接使用 `@preact/signals-core` 的所有导出，包括：
- `Signal<T>` - 基础信号类
- `ReadonlySignal<T>` - 只读信号类型
- `signal<T>(value)` - 创建信号
- `computed<T>(fn)` - 创建计算信号
- `effect(fn)` - 创建副作用
- `batch(fn)` - 批量更新
- `untracked(fn)` - 非追踪读取

---

## 测试辅助函数

以下函数主要用于测试代码：

### `createGameContext(options)`

创建游戏上下文实例。

```typescript
function createGameContext<TState>(options: {
    initialState: TState;
    registry?: CommandRegistry<IGameContext<TState>>;
    rng?: RNG;
}): IGameContext<TState>
```

**使用示例：**

```typescript
import { createGameContext } from '@/core/game';
import { createInitialState, registry } from './my-game';

const ctx = createGameContext({
    initialState: createInitialState(),
    registry,
});

// 执行命令
await ctx.run('move piece1 piece2');

// 断言状态
expect(ctx.value.score).toBe(10);
```

---

### `createTestContext()`

创建用于测试的游戏上下文（简化版）。

```typescript
function createTestContext<TState>(initialState: TState): IGameContext<TState>
```

---

### `createTestRegion()`

创建用于测试的区域。

```typescript
function createTestRegion(): Region
```