# weiqi-3d

**Repository Path**: tt-creation/weiqi-3d

## Basic Information

- **Project Name**: weiqi-3d
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D 围棋学堂 🏯

用 React + Three.js 从零做一个**能真正教会你下围棋的 3D 应用**——这也是一个公众号连载项目：每完成一个里程碑，就把背后的围棋知识和技术实现拆成一篇文章。

![当前效果](screenshots/ep13-review.png)

## 这是什么

- 🀫 **如果你是想学 Three.js / React Three Fiber 的开发者**：每篇文章都有可跟做的原理讲解和关键代码，代码仓库与文章一一对应（见下方「版本锚点」）
- ⚫ **如果你是围棋爱好者（或完全没下过棋）**：跟着课程从「认识棋盘」一路学到「下完一盘棋」，所有围棋知识都在真实的 3D 棋盘上边玩边学

围棋线是主纲，技术线为课程服务——不为炫技加功能。

## 快速开始

```bash
npm install
npm run dev      # 开发：http://localhost:5173
npm run build    # 生产构建
```

要求：Node.js 18+。无需任何 API Key、无需下载素材——木纹是代码画出来的，摄影棚灯光是代码搭的。

## 当前进度

**入门篇：从零到下完一盘棋**

| 进度 | 课程 | 技术关键词 |
|---|---|---|
| ✅ | 01 初见棋盘 | 程序化木纹纹理、PBR 云子（clearcoat）、Lightformer 摄影棚、相机运镜 |
| ✅ | 02 气 | raycasting 落子、幽灵棋子预览、规则引擎①：气计算（BFS）、气点亮能量场特效 |
| ✅ | 03 提子 | 规则引擎②：提子判定（先提子后判自杀）、退场动画、sprite 光尘粒子 |
| ✅ | 04 打吃、逃跑与连接 | 规则引擎③：打吃检测（整盘扫描）、心跳节律脉冲、最后一口气闪红、连接线可视化 |
| ✅ | 05 禁入点与打劫 | 打劫演示 ?ko=1、三层拒绝反馈（悬停警示/冲击环/讲人话 toast）、连接光珠、光效可见性整改 |
| ✅ | 06 眼、活棋与对杀 | 真眼检测算法、声明式关卡系统（4 关）、气数对比 HUD、通关徽章、闯关模式上线 |
| ✅ | 07 下完一盘棋 | 虚着与终局判定、数子法 scoreBoard（子空皆地+贴目）、地盘染色、结算面板、让子棋 ?handicap |

**入门篇 ✅ 完结（01–07）。**

**进阶篇：从会下到下得好**

| 进度 | 课程 | 技术关键词 |
|---|---|---|
| ✅ | 08 吃子技巧上 | 征子推演 ladderPath（递归强制序列模拟）、路径 3D 预演（LadderPath）、双打关卡（atari 目标类型） |
| ✅ | 09 吃子技巧下 | 演示回放系统（时间轴/跳帧/逐手解说）、强制追吃链求解器（例题 25 项断言）、倒扑关卡（第 6 关） |
| ✅ | 10 死活基础 | 眼形挖掘 eyeSpaces（flood-fill + 边界单色判定）、死活形分类与要点算法、死活辅助高亮（EyeSpaceViz）、形状画廊、vital 目标类型（第 7/8 关） |
| ✅ | 11 布局入门 | 棋盘线数参数化（9/13/19 路，N 活绑定）、InstancedMesh 棋子层（361 子 2 次 draw call，?naive=1 可对比旧实现）、布局演示四件套（金角银边草肚皮 / 布局四步 / 星小目三三 / 七子沿边）、性能实测基准 bench-ep11.mjs |
| ✅ | 12 官子入门 | 官子引擎 endgame.js（公气点提取 + 数子法 swing 价值 =「归谁差几目」）、目数数字牌可视化（EndgameViz canvas sprite）、收官逐手演示 + 实时分数 HUD、终局自动结算（?endgame=1&step=N&done=1） |
| ✅ | 13 复盘与结业 | 变化树 gametree.js（playAt 分叉 / 同点位复用旧分支 / 节点盘面快照）、SGF 导入导出（sgf.js round-trip 逐字节一致 + 逐手引擎试走拦截非法手）、VariationTree 面板（layoutTree 主线/分行布局）、Certificate 结业证书（canvas 本地生成 PNG）、vite base './' 静态部署（?review=1 / ?cert=1 摆拍） |

**入门篇 + 进阶篇 ✅ 全部完结（01–13）。**

**进阶篇**（吃子技巧 / 死活 / 布局与 19 路 / 官子 / 复盘结业）详见 `articles/_3d围棋学堂-系列规划.md`。

## 版本锚点

代码只往前走，每发布一篇文章打一个 tag，锚定该篇写作时的代码状态：

```
git checkout ep01   # 回到第 01 篇《初见棋盘》发布时的代码
git checkout ep02   # 回到第 02 篇《气》发布时的代码
git checkout ep03   # 回到第 03 篇《提子》发布时的代码
git checkout ep04   # 回到第 04 篇《打吃、逃跑与连接》发布时的代码
git checkout ep05   # 回到第 05 篇《禁入点与打劫》发布时的代码
git checkout ep06   # 回到第 06 篇《眼、活棋与对杀》发布时的代码
git checkout ep07   # 回到第 07 篇《下完一盘棋》发布时的代码
git checkout ep08   # 回到第 08 篇《吃子技巧上》发布时的代码
git checkout ep09   # 回到第 09 篇《吃子技巧下》发布时的代码
git checkout ep10   # 回到第 10 篇《死活基础》发布时的代码
git checkout ep11   # 回到第 11 篇《布局入门》发布时的代码
git checkout ep12   # 回到第 12 篇《官子入门》发布时的代码
git checkout ep13   # 回到第 13 篇《复盘与结业》发布时的代码
git checkout main   # 跟最新进度
```

## 目录结构

```
src/
├── main.jsx                  # 入口
├── App.jsx                   # 场景编排 + 2D 覆盖层 + 加载时序
├── index.css                 # 分层样式（粒子层 / 3D 层 / UI 层 / 加载屏）
├── go/                       # 围棋规则引擎（纯函数，零 React 依赖，可 Node 单测）
│   ├── rules.js              # 邻接 / groupAndLiberties（BFS 算气）/ tryPlay 三步判定 / groupsInAtari 打吃扫描 / connectionEdges 连接边 / isRealEye 真眼 / scoreBoard 数子法 / ladderPath 征子推演
│   ├── lifedeath.js          # 死活：eyeSpaces 眼形挖掘（flood-fill + 边界单色）/ classifyShape 棋形分类与要点算法 / SHAPE_PRESETS 棋形摆拍题面
│   ├── endgame.js            # 官子：damePoints 单官提取（scoreBoard 公气）/ endgameValue 价值 swing 口径 / sweepDameSequence 交替收官手顺
│   ├── opening.js            # 布局：regionAt 围空实测（金角银边草肚皮）/ 布局四步 OPENING_SEQ / 七子沿边对照 / 星小目三三
│   ├── gametree.js           # 变化树（第 13 课）：playAt 分叉（同点位复用旧分支）/ passAt / 节点盘面快照 / layoutTree 主线-分行布局
│   ├── sgf.js                # SGF 棋谱（第 13 课）：toSGF 树压平（分支括号先于主线输出）/ parseSGF 逐手引擎试走 + 非法手拦截 / round-trip 硬指标
│   ├── useGoGame.js          # 对局状态 hook（ref 单一事实源：手番/劫点/提子/悔棋）
│   ├── levels.js             # 闯关关卡数据（声明式出题：stones + 引擎可判定 goal）
│   ├── replays.js            # 演示回放数据（强制序列 + 逐手解说，replayTo 不存快照逐手重放）
│   └── rules.test.js         # 43 项断言自测：node src/go/rules.test.js（N 参数化后 9/13/19 路通用）
├── three/
│   ├── constants.js          # 棋盘几何（随线数函数化：boardHalf / halfIndex / 星位表）与坐标系换算
│   ├── woodTexture.js        # 程序化木纹纹理（Canvas 三层画法，13/19 路自动升 2048px）
│   └── glowTextures.js       # 特效贴图工厂（辉光/能量束/光环，加法混合）
└── components/
    ├── GoBoard.jsx           # 3D 棋盘（六面材质数组）
    ├── Stones.jsx            # 云子（InstancedMesh 实例化：黑白各 1 次 draw call + 落子/提子动画；?naive=1 切旧实现做 A/B）
    ├── EndgameViz.jsx        # 官子价值牌（canvas 数字牌 sprite，同价值共用纹理）
    ├── VariationTree.jsx     # 变化树面板（SVG：主线实线/分支虚线、点击跳转任意盘面、注释展示）
    ├── Certificate.jsx       # 结业证书（canvas 本地绘制 + toDataURL 存 PNG，不上传任何信息）
    ├── OpeningViz.jsx        # 布局课可视化（实例化气点辉光 LibertyDots / 落点标记环 MarkRings / 围空铺色 ZoneFill）
    ├── StudioScene.jsx       # 灯光 / Lightformer 环境 / 微尘 / 接触阴影
    ├── CameraRig.jsx         # 相机入场运镜
    ├── GoParticleField.tsx   # 棋字符粒子场背景（Canvas 2D）
    ├── BootLoader.tsx        # 开机加载屏
    ├── BoardInput.jsx        # 落子交互（raycasting 拾取 + 吸附 + 幽灵棋子）
    ├── CaptureFx.jsx         # 提子光尘（sprite 公告牌粒子 + 加法混合）
    ├── LibertyMarkers.jsx    # 气点亮能量场（辉光/能量束/流动脉冲/冲击波）
    ├── TerritoryMap.jsx      # 终局地盘染色（数子法可视化：黑靛蓝紫/白暖白）
    ├── LadderPath.jsx        # 征子路径 3D 预演（跑方青绿/追方警报红虚子阶梯 + 提净点红环）
    ├── EyeSpaceViz.jsx       # 死活辅助高亮（眼形区域染色：死形红/活形青绿/未识别灰 + 要点脉冲环）
    ├── ReplayBar.jsx         # 演示回放时间轴（圆点=一手、红环=提子手、跳帧/自动播放）
    └── GroupViz.jsx          # 打吃预警（DangerPulse 心跳脉冲 / LastGasp 最后一口气闪红）+ ConnectionLines 连接光珠 + RejectFx 拒绝冲击环
scripts/                      # 例题验证与工具：verify-ep09/10/11/12.mjs（25 / 251 / 173 / 68 项断言）、bench-ep11.mjs（instancing 性能实测）、shot.mjs（CDP 条件就绪截图）、compose-ep10.py（拼图）
references/                   # 系列开发档案与精读笔记
screenshots/                  # 各里程碑截图
```

## 技术栈

Vite · React 18 · three · @react-three/fiber · @react-three/drei · TypeScript（渐进采用）

## 致谢

- [ThreeUI](https://github.com/MengTo/threeui)（MIT）——粒子背景与加载屏参考/移植自其开源实现，源码存档见 `references/threeui-sources/`
- [three.js](https://github.com/mrdoob/three.js) 及 R3F / drei 社区

## 系列文章

公众号连载中（作者：旺仔）。

- 第 01 篇《Three.js 教程跟完就忘？我干脆用它手搓了一块 3D 围棋棋盘》→ tag `ep01`
- 第 02 篇《10 手棋下去棋盘上只剩 1 颗子：一个 React 闭包坑，和 20 行算清围棋「气」的 BFS》→ tag `ep02`
- 第 03 篇《为什么"能提子的自杀点"是围棋里合法的好棋？我用 Three.js 把这条规则讲透了》→ tag `ep03`
- 第 04 篇《你的棋子只剩最后一口气时，棋盘上响起了心跳警报》→ tag `ep04`
- 第 05 篇《围棋最"记仇"的规则：刚提走的子，为什么不能马上拿回来？》→ tag `ep05`
- 第 06 篇《围棋最"温柔"的规则：有了两只真眼，谁也动不了你》→ tag `ep06`
- 第 07 篇《入门篇收官：你按下"虚着"，棋盘把地盘染成两种颜色》→ tag `ep07`
- 第 08 篇《高手扫一眼就知道的"征子不利"，我让 3D 棋盘提前 24 手画了出来》→ tag `ep08`
- 第 09 篇《送 1 颗吃 7 颗：围棋最反直觉的吃法，我用 Three.js 做成了逐手回放》→ tag `ep09`
- 第 10 篇《一块棋的生死只隔一格：我把围棋 8 种棋形的「命门」全标了出来》→ tag `ep10`
- 第 11 篇《布局入门》→ tag `ep11`
- 第 12 篇《官子入门》→ tag `ep12`
- 第 13 篇《围棋软件里按悔棋，不是作弊——是复盘的开始》→ tag `ep13`（系列完结）