hypercross
/
boardgame-core
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: update api

This commit is contained in:
hypercross 2026-04-02 12:48:29 +08:00
parent 846badc081
commit 004d49c36f
4 changed files with 128 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
src/core/game.ts
View File

@ -11,37 +11,53 @@ import {
} from "../utils/command";
import {AsyncQueue} from "../utils/async-queue";
export interface IGameContext {
export interface IGameContext<TState extends {} = {}> {
parts: ReturnType<typeof createEntityCollection<Part>>;
regions: ReturnType<typeof createEntityCollection<Region>>;
commands: CommandRunnerContextExport<IGameContext>;
commands: CommandRunnerContextExport<IGameContext<TState>>;
prompts: AsyncQueue<PromptEvent>;
}
/**
* creates a game context.
* expects a command registry already registered with commands.
* @param commandRegistry
*/
export function createGameContext(commandRegistry: CommandRegistry<IGameContext>) {
export function createGameContext<TState extends {} = {}>(
commandRegistry: CommandRegistry<IGameContext<TState>>,
initialState?: TState | (() => TState)
): IGameContext<TState> {
const parts = createEntityCollection<Part>();
const regions = createEntityCollection<Region>();
const ctx: IGameContext = {
const prompts = new AsyncQueue<PromptEvent>();
const state: TState = typeof initialState === 'function' ? (initialState as (() => TState))() : (initialState ?? {} as TState);
const ctx = {
parts,
regions,
prompts,
commands: null!,
prompts: new AsyncQueue(),
};
state,
} as IGameContext<TState>
ctx.commands = createCommandRunnerContext(commandRegistry, ctx);
ctx.commands.on('prompt', (prompt: PromptEvent) => ctx.prompts.push(prompt));
return ctx;
}
export function createGameCommand<TResult>(
/**
* so that we can do `import * as tictactoe from './tic-tac-toe.ts';\n\n createGameContextFromModule(tictactoe);`
* @param module
*/
export function createGameContextFromModule<TState extends {} = {}>(
module: {
registry: CommandRegistry<IGameContext<TState>>,
createInitialState: () => TState
},
): IGameContext<TState> {
return createGameContext(module.registry, module.createInitialState);
}
export function createGameCommand<TState extends {} = {}, TResult = unknown>(
schema: CommandSchema | string,
run: (this: CommandRunnerContext<IGameContext>, command: Command) => Promise<TResult>
): CommandRunner<IGameContext, TResult> {
run: (this: CommandRunnerContext<IGameContext<TState>>, command: Command) => Promise<TResult>
): CommandRunner<IGameContext<TState>, TResult> {
return {
schema: typeof schema === 'string' ? parseCommandSchema(schema) : schema,
run,

38
src/samples/tic-tac-toe.ts
View File

@ -1,7 +1,6 @@
import { IGameContext } from '../core/game';
import {CommandRegistry, CommandRunner, registerCommand} from '../utils/command';
import { IGameContext, createGameCommand } from '../core/game';
import { createCommandRegistry, type CommandRegistry, registerCommand } from '../utils/command';
import type { Part } from '../core/part';
import {createGameCommand} from "../core/game";
export type TicTacToeState = {
currentPlayer: 'X' | 'O';
@ -9,15 +8,25 @@ export type TicTacToeState = {
moveCount: number;
};
export type TicTacToeContext = IGameContext<TicTacToeState>;
type TurnResult = {
winner: 'X' | 'O' | 'draw' | null;
};
export function getBoardRegion(host: IGameContext) {
export function createInitialState(): TicTacToeState {
return {
currentPlayer: 'X',
winner: null,
moveCount: 0,
};
}
export function getBoardRegion(host: TicTacToeContext) {
return host.regions.get('board');
}
export function isCellOccupied(host: IGameContext, row: number, col: number): boolean {
export function isCellOccupied(host: TicTacToeContext, row: number, col: number): boolean {
const board = getBoardRegion(host);
return board.value.children.some(
(child: { value: { position: number[] } }) => child.value.position[0] === row && child.value.position[1] === col
@ -43,7 +52,7 @@ export function hasWinningLine(positions: number[][]): boolean {
);
}
export function checkWinner(host: IGameContext): 'X' | 'O' | 'draw' | null {
export function checkWinner(host: TicTacToeContext): 'X' | 'O' | 'draw' | null {
const parts = Object.values(host.parts.collection.value).map((s: { value: Part }) => s.value);
const xPositions = parts.filter((_: Part, i: number) => i % 2 === 0).map((p: Part) => p.position);
@ -55,7 +64,7 @@ export function checkWinner(host: IGameContext): 'X' | 'O' | 'draw' | null {
return null;
}
export function placePiece(host: IGameContext, row: number, col: number, moveCount: number) {
export function placePiece(host: TicTacToeContext, row: number, col: number, moveCount: number) {
const board = getBoardRegion(host);
const piece: Part = {
id: `piece-${moveCount}`,
@ -68,7 +77,7 @@ export function placePiece(host: IGameContext, row: number, col: number, moveCou
board.value.children.push(host.parts.get(piece.id));
}
const setup = createGameCommand(
const setup = createGameCommand<TicTacToeContext, { winner: 'X' | 'O' | 'draw' | null }>(
'setup',
async function() {
this.context.regions.add({
@ -81,23 +90,23 @@ const setup = createGameCommand(
});
let currentPlayer: 'X' | 'O' = 'X';
let turnResult: TurnResult | undefined;
let winner: 'X' | 'O' | 'draw' | null = null;
let turn = 1;
while (true) {
const turnOutput = await this.run<TurnResult>(`turn ${currentPlayer} ${turn++}`);
if (!turnOutput.success) throw new Error(turnOutput.error);
turnResult = turnOutput?.result.winner;
if (turnResult) break;
winner = turnOutput.result.winner;
if (winner) break;
currentPlayer = currentPlayer === 'X' ? 'O' : 'X';
}
return { winner: turnResult };
return { winner };
}
)
const turn = createGameCommand(
const turn = createGameCommand<TicTacToeContext, TurnResult>(
'turn <player> <turn:number>',
async function(cmd) {
const [turnPlayer, turnNumber] = cmd.params as [string, number];
@ -119,7 +128,6 @@ const turn = createGameCommand(
}
);
export function registerTicTacToeCommands(registry: CommandRegistry<IGameContext>) {
export const registry = createCommandRegistry<TicTacToeContext>();
registerCommand(registry, setup);
registerCommand(registry, turn);
}

58
tests/core/game.test.ts
View File

@ -1,7 +1,15 @@
import { describe, it, expect } from 'vitest';
import { createGameContext, createGameCommand } from '../../src/core/game';
import { createGameContext, createGameCommand, IGameContext } from '../../src/core/game';
import { createCommandRegistry, parseCommandSchema, type CommandRegistry } from '../../src/utils/command';
import type { IGameContext } from '../../src/core/game';
type MyState = {
score: number;
round: number;
};
type MyContext = IGameContext & {
state: MyState;
};
describe('createGameContext', () => {
it('should create a game context with empty parts and regions', () => {
@ -21,6 +29,26 @@ describe('createGameContext', () => {
expect(ctx.commands.context).toBe(ctx);
});
it('should accept initial state as an object', () => {
const registry = createCommandRegistry<MyContext>();
const ctx = createGameContext<MyContext>(registry, {
state: { score: 0, round: 1 },
});
expect(ctx.state.score).toBe(0);
expect(ctx.state.round).toBe(1);
});
it('should accept initial state as a factory function', () => {
const registry = createCommandRegistry<MyContext>();
const ctx = createGameContext<MyContext>(registry, () => ({
state: { score: 10, round: 3 },
}));
expect(ctx.state.score).toBe(10);
expect(ctx.state.round).toBe(3);
});
it('should forward prompt events to the prompts queue', async () => {
const registry = createCommandRegistry<IGameContext>();
const ctx = createGameContext(registry);
@ -123,4 +151,30 @@ describe('createGameCommand', () => {
}
expect(ctx.parts.get('piece-1')).not.toBeNull();
});
it('should run a typed command with extended context', async () => {
const registry = createCommandRegistry<MyContext>();
const addScore = createGameCommand<MyContext, number>(
'add-score <amount:number>',
async function (cmd) {
const amount = cmd.params[0] as number;
this.context.state.score += amount;
return this.context.state.score;
}
);
registry.set('add-score', addScore);
const ctx = createGameContext<MyContext>(registry, () => ({
state: { score: 0, round: 1 },
}));
const result = await ctx.commands.run('add-score 5');
expect(result.success).toBe(true);
if (result.success) {
expect(result.result).toBe(5);
}
expect(ctx.state.score).toBe(5);
});
});

50
tests/samples/tic-tac-toe.test.ts
View File

@ -1,18 +1,15 @@
import { describe, it, expect } from 'vitest';
import { createGameContext } from '../../src/core/game';
import { createCommandRegistry } from '../../src/utils/command';
import { registerTicTacToeCommands, checkWinner, isCellOccupied, placePiece } from '../../src/samples/tic-tac-toe';
import type { IGameContext } from '../../src/core/game';
import {registry, checkWinner, isCellOccupied, placePiece, createInitialState} from '../../src/samples/tic-tac-toe';
import type { TicTacToeContext } from '../../src/samples/tic-tac-toe';
import type { Part } from '../../src/core/part';
import {createGameContext} from "../../src";
function createTestContext() {
const registry = createCommandRegistry<IGameContext>();
registerTicTacToeCommands(registry);
const ctx = createGameContext(registry);
const ctx = createGameContext(registry, createInitialState);
return { registry, ctx };
}
function setupBoard(ctx: IGameContext) {
function setupBoard(ctx: TicTacToeContext) {
ctx.regions.add({
id: 'board',
axes: [
@ -23,7 +20,7 @@ function setupBoard(ctx: IGameContext) {
});
}
function addPiece(ctx: IGameContext, id: string, row: number, col: number) {
function addPiece(ctx: TicTacToeContext, id: string, row: number, col: number) {
const board = ctx.regions.get('board');
const part: Part = {
id,
@ -172,10 +169,10 @@ describe('TicTacToe - helper functions', () => {
describe('TicTacToe - game flow', () => {
it('should have setup and turn commands registered', () => {
const { registry } = createTestContext();
const { registry: reg } = createTestContext();
expect(registry.has('setup')).toBe(true);
expect(registry.has('turn')).toBe(true);
expect(reg.has('setup')).toBe(true);
expect(reg.has('turn')).toBe(true);
});
it('should setup board when setup command runs', async () => {
@ -205,7 +202,6 @@ describe('TicTacToe - game flow', () => {
promptEvent.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
// After valid non-winning move, turn command prompts again, reject to stop
const promptEvent2 = await ctx.prompts.pop();
promptEvent2.reject(new Error('done'));
@ -229,7 +225,6 @@ describe('TicTacToe - game flow', () => {
promptEvent2.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
// After valid non-winning move, reject next prompt
const promptEvent3 = await ctx.prompts.pop();
promptEvent3.reject(new Error('done'));
@ -253,7 +248,6 @@ describe('TicTacToe - game flow', () => {
promptEvent2.resolve({ name: 'play', params: ['X', 0, 0], options: {}, flags: {} });
// After valid non-winning move, reject next prompt
const promptEvent3 = await ctx.prompts.pop();
promptEvent3.reject(new Error('done'));
@ -265,7 +259,6 @@ describe('TicTacToe - game flow', () => {
const { ctx } = createTestContext();
setupBoard(ctx);
// X plays (0,0)
let runPromise = ctx.commands.run('turn X 1');
let prompt = await ctx.prompts.pop();
prompt.resolve({ name: 'play', params: ['X', 0, 0], options: {}, flags: {} });
@ -274,7 +267,6 @@ describe('TicTacToe - game flow', () => {
let result = await runPromise;
expect(result.success).toBe(false);
// O plays (0,1)
runPromise = ctx.commands.run('turn O 2');
prompt = await ctx.prompts.pop();
prompt.resolve({ name: 'play', params: ['O', 0, 1], options: {}, flags: {} });
@ -283,7 +275,6 @@ describe('TicTacToe - game flow', () => {
result = await runPromise;
expect(result.success).toBe(false);
// X plays (1,0)
runPromise = ctx.commands.run('turn X 3');
prompt = await ctx.prompts.pop();
prompt.resolve({ name: 'play', params: ['X', 1, 0], options: {}, flags: {} });
@ -292,7 +283,6 @@ describe('TicTacToe - game flow', () => {
result = await runPromise;
expect(result.success).toBe(false);
// O plays (0,2)
runPromise = ctx.commands.run('turn O 4');
prompt = await ctx.prompts.pop();
prompt.resolve({ name: 'play', params: ['O', 0, 2], options: {}, flags: {} });
@ -301,7 +291,6 @@ describe('TicTacToe - game flow', () => {
result = await runPromise;
expect(result.success).toBe(false);
// X plays (2,0) - wins with vertical line
runPromise = ctx.commands.run('turn X 5');
prompt = await ctx.prompts.pop();
prompt.resolve({ name: 'play', params: ['X', 2, 0], options: {}, flags: {} });
@ -314,28 +303,23 @@ describe('TicTacToe - game flow', () => {
const { ctx } = createTestContext();
setupBoard(ctx);
// Pre-place 8 pieces that don't form any winning line for either player
// Using positions that clearly don't form lines
// X pieces at even indices, O pieces at odd indices
const pieces = [
{ id: 'p1', pos: [0, 0] }, // X
{ id: 'p2', pos: [2, 2] }, // O
{ id: 'p3', pos: [0, 2] }, // X
{ id: 'p4', pos: [2, 0] }, // O
{ id: 'p5', pos: [1, 0] }, // X
{ id: 'p6', pos: [0, 1] }, // O
{ id: 'p7', pos: [2, 1] }, // X
{ id: 'p8', pos: [1, 2] }, // O
{ id: 'p1', pos: [0, 0] },
{ id: 'p2', pos: [2, 2] },
{ id: 'p3', pos: [0, 2] },
{ id: 'p4', pos: [2, 0] },
{ id: 'p5', pos: [1, 0] },
{ id: 'p6', pos: [0, 1] },
{ id: 'p7', pos: [2, 1] },
{ id: 'p8', pos: [1, 2] },
];
for (const { id, pos } of pieces) {
addPiece(ctx, id, pos[0], pos[1]);
}
// Verify no winner before 9th move
expect(checkWinner(ctx)).toBeNull();
// Now X plays (1,1) for the 9th move -> draw
const runPromise = ctx.commands.run('turn X 9');
const prompt = await ctx.prompts.pop();
prompt.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });