boardgame-core/README.md

boardgame-core

基于 Preact Signals 的桌游状态管理库。

特性

• 响应式状态管理: 使用 @preact/signals-core 实现细粒度响应式
• 类型安全: 完整的 TypeScript 支持
• 核心概念:
  • Part: 游戏组件（棋子、卡牌、板块）
  • Region: 容器区域（支持 keyed/unkeyed 两种模式）
  • Placement: Part 在 Region 中的引用

安装

npm install

快速开始

1. 创建游戏状态

import { createGameState } from 'boardgame-core';

const gameState = createGameState({
  id: 'game-1',
  name: 'My Board Game',
});

2. 创建 Parts（游戏组件）

import { createMeepleAction, createCardAction, createTileAction } from 'boardgame-core';

// 创建棋子
const meeple = createMeepleAction(gameState, 'meeple-1', 'red', {
  name: 'Player 1',
});

// 创建卡牌
const card = createCardAction(gameState, 'card-1', {
  suit: 'hearts',
  value: 10,
});

// 创建板块
const tile = createTileAction(gameState, 'tile-1', {
  pattern: 'forest',
  rotation: 90,
});

3. 创建 Regions（区域）

import { createRegionAction, RegionType } from 'boardgame-core';

// Unkeyed Region - 适用于牌库、弃牌堆等
const deck = createRegionAction(gameState, {
  id: 'deck',
  type: RegionType.Unkeyed,
  name: 'Draw Deck',
});

// Keyed Region - 适用于版图、玩家区域等有固定位置的区域
const board = createRegionAction(gameState, {
  id: 'board',
  type: RegionType.Keyed,
  name: 'Game Board',
});

// 带容量的区域（如手牌限制）
const hand = createRegionAction(gameState, {
  id: 'hand',
  type: RegionType.Unkeyed,
  capacity: 5,
});

4. 创建 Placements（放置）

import { createPlacementAction } from 'boardgame-core';

// 将棋子放置在版图上
const placement = createPlacementAction(gameState, {
  id: 'placement-1',
  partId: 'meeple-1',
  regionId: 'board',
  position: { x: 3, y: 4 },
});

5. 使用 Actions 操作状态

import {
  movePlacementAction,
  flipPlacementAction,
  setSlotAction,
  updatePartAction,
} from 'boardgame-core';

// 移动 Placement 到另一个区域
movePlacementAction(gameState, 'placement-1', 'hand');

// 翻转卡牌（面朝上/面朝下）
flipPlacementAction(gameState, 'placement-1');

// 在 Keyed Region 中设置槽位
setSlotAction(gameState, 'board', 'A1', 'placement-1');

// 更新 Part 属性
updatePartAction(gameState, 'meeple-1', { metadata: { score: 10 } });

API 参考

Part Actions

Action	描述
createPartAction	创建通用 Part
createMeepleAction	创建棋子
createCardAction	创建卡牌
createTileAction	创建板块
updatePartAction	更新 Part 属性
removePartAction	移除 Part
getPartAction	获取 Part

Region Actions

Action	描述
createRegionAction	创建 Region
getRegionAction	获取 Region
removeRegionAction	移除 Region
addPlacementToRegionAction	添加 Placement 到 Unkeyed Region
removePlacementFromRegionAction	从 Region 移除 Placement
setSlotAction	设置 Keyed Region 的槽位
getSlotAction	获取 Keyed Region 的槽位
clearRegionAction	清空 Region
getRegionPlacementCountAction	获取 Region 中 Placement 数量
isRegionEmptyAction	检查 Region 是否为空
isRegionFullAction	检查 Region 是否已满

Placement Actions

Action	描述
createPlacementAction	创建 Placement
getPlacementAction	获取 Placement
removePlacementAction	移除 Placement
movePlacementAction	移动 Placement 到另一个 Region
updatePlacementPositionAction	更新 Placement 位置
updatePlacementRotationAction	更新 Placement 旋转角度
flipPlacementAction	翻转 Placement
updatePlacementPartAction	更新 Placement 的 Part 引用
swapPlacementsAction	交换两个 Placement 的位置
setPlacementFaceAction	设置 Placement 面朝上/下
getPlacementsInRegionAction	获取 Region 中的所有 Placements
getPlacementsOfPartAction	获取 Part 的所有 Placements

运行测试

npm test          # 监视模式
npm run test:run  # 运行一次

构建

npm run build

许可证

MIT