FiveInRow 五子棋 — 工程架构介绍

FiveInRow 五子棋 Android 单机 App 的工程架构说明：Compose 产品壳 + JNI 薄桥 + C11 棋规引擎，原型先行、UI 与引擎分离，支持人机对战与同屏双人。

FiveInRow 是一款 Android 单机五子棋：人机对战与同屏双人，完全离线。工程遵循 原型先行、UI 与引擎分离、C 做后端、文档与 ABI 对齐 的分层思路。

一、目录结构

FiveInRow 是 移动单机 App。Function/README.md 约定：移动产品放在 Function/ 下，第一层按平台划分。

FiveInRow/
├── ProtoType/        HTML 高保真原型（不参与构建）
├── Docs/             博文、说明（本目录）
└── Function/
    └── Android/
        ├── app/              Kotlin · Compose（产品壳）
        │   └── src/main/cpp/ JNI 薄层
        ├── engine/           C11 棋规引擎（Library 模块）
        │   └── src/main/cpp/
        └── docs/             API.md、JNI 约定

层级	路径	职责
设计	`ProtoType/*.html`	界面与交互参考，定 UI 后再落原生
产品壳	`app/`	Compose 界面、ViewModel、导航、DataStore
桥接	`app/.../cpp/` + `NativeBridge.kt`	JNI，上层不暴露原生指针
契约	`engine/include/fiveinrow/engine.h`	稳定 C ABI
实现	`engine/src/*.c`	棋规、Renju、AI，可独立演进
打包	Gradle `:engine` + NDK	引擎随 App 内置编译
文档	`Docs/Blogs/`（本文）	架构与功能说明

二、分层与数据流

整体可理解为 四层模型：

层级	技术	职责
UI	Jetpack Compose	页面、组件、主题
编排	ViewModel · StateFlow	状态机、持久化触发、AI 调度
桥接	JNI	Kotlin ↔ C 引擎
引擎	C11 · `:engine`	落子、胜负、禁手、AI、历史

数据流：

Compose UI → ViewModel → JNI → C 引擎 (fiveinrow_*)
                ↓
         DataStore（设置 / 战绩 / 存档）

引擎内部分两层：

头文件 engine.h：对外 C 函数，稳定、可绑定
源文件 *.c：棋盘、规则、Renju、AI 等实现，可随时重构

FiveInRow 首页

首页：人机 / 双人入口、战绩摘要、继续对局

三、为什么坚持「C 后端 + 薄桥接」？

3.1 逻辑只写一遍

胜负判定、Renju 禁手、AI 选点位于 engine/src/main/cpp/：

Android：JNI
未来 iOS：Bridging Header / XCFramework
测试：可直接针对 C 模块

棋规不写在 Kotlin 里，换平台不必重写规则。

3.2 前后端联调有章可循

契约头文件：Function/Android/engine/src/main/cpp/include/fiveinrow/engine.h
文档：Function/Android/docs/API.md

要点：

place_stone 返回 0~4（含 Renju FORBIDDEN = 4）
fiveinrow_set_rule_mode / fiveinrow_get_rule_mode
AI 难度、棋盘快照、历史步序

ViewModel 只认 GameEngine 接口；改 C 实现不必改 Compose 布局。

3.3 原型与实现不打架

ProtoType/ 不参与 Gradle 构建：产品与设计在 HTML 里跑通流程，开发对照原型做 Compose。

产品定位为 单机离线：人机 + 同屏双人，无联机、无账号；原型与实现均已移除「在线对战」类占位。

四、主要功能

4.1 产品壳（Compose）

界面	说明
首页	人机 / 双人、战绩卡片、继续对局（有存档时可用）
对局页	棋盘 Canvas、悔棋、认输、和棋提议、示例中盘
设置	棋盘 11/13/15、Standard/Renju、AI 难度、主题、音效
战绩	总览 + 人机 / 双人分项
帮助 / 关于	规则说明、Renju 简介、离线定位

对局页

对局页：棋盘、顶栏操作、行棋状态、结算层

4.2 C 引擎（`:engine`）

模块	源文件	能力
棋盘	`board.c`	重置、快照
规则	`rules.c`	落子、五连判定
Renju	`renju.c`	三三 / 四四 / 长连禁手
AI	`ai.c`	三档难度；Renju 下跳过黑棋禁手点
历史	`history.c`	悔棋
演示	`demo.c`	中盘棋谱

4.3 本地持久化（Kotlin DataStore）

仓库	职责
`SettingsRepository`	棋盘、规则、AI、主题、音效
`StatsRepository`	人机 / 双人战绩
`GameRepository`	对局存档与续局

GameViewModel 编排：落子后 persistIfPlaying()，终局或放弃时 clear()。

五、技术栈

层级	技术
UI	Kotlin · Jetpack Compose · Material 3
架构	ViewModel · StateFlow · Navigation Compose
桥接	JNI（`app/src/main/cpp/engine_jni.cpp`）
引擎	C11 · CMake · NDK · `:engine` 静态库
存储	DataStore Preferences
原型	HTML + Tailwind（`ProtoType/`）

六、构建与目录速查

环境

工具	说明
JDK	17+
Android SDK	API 24+
NDK	26.x（工程已配置）

编译

cd Function/Android
./gradlew :app:assembleDebug
# 真机：./gradlew :app:installDebug

引擎与 UI 分离

改 renju.c / rules.c：触发 NDK 重编，Compose 增量编译
改主题 / 文案：通常不涉及 JNI

七、新项目可复制的清单

根目录 / 模块 README：产品 + 栈 + 构建方式
原型目录（ProtoType/）：不参与构建
稳定 C ABI + Impl 分文件
薄桥接（JNI），上层不 spread 原生指针
API 文档与错误码表
产品壳轻薄：编排、导航、持久化；复杂逻辑下沉引擎
博文（Docs/Blogs/）：对外说明与 onboarding

八、结语

FiveInRow 聚焦 休闲棋类：单机、离线、Renju 禁手规则、本地存档与续局。

骨架可以概括为：

原型定体验 → UI 壳编排 → 稳定 C 契约 → 实现可替换 → 文档对齐前后端。

新同学上手时，先看 ProtoType/ 与本文，再对照 engine.h 与 Compose 页面——目录在说话，代码只是在填空。