tts-like

TTS-like tabletop simulator. Rule-engine: boardgame.io. Desktop shell: Tauri.

Status

🚧 Early scaffold. 已落地 5 个游戏：DragTest / War / Mill（九子棋）/ Holdem（德州扑克，2-9 人）/ DoubleUp（双升，固定 4 人）。详见 docs/。

Workspace

packages/
  engine/      # boardgame.io re-exports + game-authoring helpers + 各游戏定义
  ui/          # React UI primitives (<Board>, <Card>, <Zone>, <LobbyRoomList>, ...)
  protocol/    # Shared TS types (UI schema, state shapes)
  server/      # Relay server (wraps boardgame.io master, /api 前缀 + 静态 serve)
apps/
  web/         # Vite + React SPA (含各游戏 Board 组件 + e2e)
  desktop/     # Tauri wrapper around apps/web build（待启动）
docs/
  impl.md            # High-level implementation plan
  ui-primitives.md   # UI API design
  dev-log/           # 按主题切的开发过程记录（做什么 → 问题 → 怎么解决）

环境要求

• Node.js ≥ 22.12（推荐通过 nvm 装 22.x）
• pnpm ≥ 10.16（通过 corepack 启用，见下）
• 端口：dev 默认 5173（web）+ 8000（server），生产可合并为单端口

启动整个系统

1. 准备环境（每台机器只需一次）

# 用 nvm 装 Node 22（已装可跳过）
nvm install 22 && nvm use 22

# 启用 pnpm（corepack 是 Node 自带的包管理器入口）
corepack enable

2. 安装依赖

pnpm install

3a. 开发模式（dev，两个进程）

# 终端 1：启动 boardgame.io relay server（:8000）
pnpm --filter @tts-like/server dev

# 终端 2：启动 vite dev server（:5173）
pnpm dev

打开 http://localhost:5173 → 选游戏 → "本地" 单机调试，或 "联机" 创建/加入房间。 vite proxy 自动把 /api 和 /socket.io 转发到 :8000，同源无 CORS。

3b. 一键 dev（单进程，server 顺带 serve 静态）

pnpm --filter @tts-like/server dev    # :8000
# 另一个终端：
pnpm --filter @tts-like/web build      # 构建到 apps/web/dist
# server 检测到 dist 后自动 serve → http://localhost:8000 直接可用（无需 vite）

3c. 一键单端口启动（推荐，含双升等全部游戏）

根目录 start.sh：以 PORT=5173 启动 Koa，单进程同时 serve 前端页面 + /api + /socket.io，浏览器直连 :5173，无需 Vite 代理。dist 缺失会自动 build；启动前自动清理 5173/8000 残留。

./start.sh
# 打开 http://localhost:5173

该模式与「统一端口」设计一致：Koa 在 5173 上即完整应用。公网暴露时直接映射 5173 端口即可（如 Cloudflare Tunnel / 反向代理），客户端零配置。详见 docs/dev-log/14-double-up-game.md「部署」一节（frp 配置不在本仓库范围内）。

4. 验证（可选）

pnpm -r ts         # 全包类型检查
pnpm -r test       # 单元测试（engine + server）
pnpm test:e2e      # Playwright E2E（自动起 server + web）

5. 局域网联机

dev 模式 vite 默认监听 0.0.0.0:5173，server 的 origins 默认覆盖 LAN 网段（192.168 / 10 / 172.16-31 / 100.x Tailscale）。 其它设备访问 http://<本机内网IP>:5173/ 即可加入同一房间。

迁移到其它机器

把整个项目目录拷到新机器后，按顺序执行：

# 1. 装 Node 22（nvm 方式）
nvm install 22 && nvm use 22

# 2. 启用 pnpm
corepack enable

# 3. 清掉旧机器的依赖产物（不同 Node 版本 / 不同 OS 架构的 node_modules 不要跨机器拷）
rm -rf node_modules packages/*/node_modules apps/*/node_modules

# 4. 重装依赖
pnpm install

# 5. 验证
pnpm -r ts && pnpm -r test && pnpm test:e2e

# 6. 启动
pnpm --filter @tts-like/server dev   # 终端 1
pnpm dev                              # 终端 2

注意事项：

• 不要跨机器拷 node_modules：原生依赖（如 esbuild / playwright 浏览器二进制）按 OS / 架构编译，跨机器会 ABI 不匹配。新机器重新 pnpm install。
• Playwright 浏览器：首次跑 e2e 要 npx playwright install（下载 Chromium）。
• 房间数据是 InMemory：server 重启会丢所有进行中的房间（boardgame.io 默认 InMemory）。要持久化需接 DB（v2 规划）。
• 生产部署：用 docker compose up --build（见 docker-compose.yml），把 ALLOWED_ORIGINS 改成你的真实域名。反代（Nginx/Caddy）终止 TLS 后转发到 :8000。也可用单端口模式：构建后 PORT=5173 ALLOWED_ORIGINS=https://你的域名 pnpm --filter @tts-like/server start，直接映射 5173。
• CORS：dev 默认覆盖 LAN；生产必须用 ALLOWED_ORIGINS 环境变量设具体 origin 列表。

设计参考

• docs/impl.md — overall architecture and phases
• docs/ui-primitives.md — UI component API
• docs/dev-log/README.md — 开发日志索引（做什么 → 问题 → 怎么解决）

License

MIT