项目地址: https://github.com/znlgis/BambooBuddy
在线试玩: https://znlgis.github.io/bamboobuddy/
官方文档: 17 章中文教程:https://znlgis.github.io/others/BambooBuddy/
包管理器: pnpm 11.22.0(根
package.json的packageManager字段锁版本)+ Node.js 24(截至 2026-11)版本:
v1.0.0(2026-11-10,GitHub Releases;首个正式版,附 Windows 便携 exe 与 Android APK;仓库根package.json的 version 仍为 0.1.0,以 Release tag 为准)许可证: MIT
概述
BambooBuddy(《熊猫宝宝的一天》,副标题 A Panda's Day)是面向 4–8 岁儿童的习惯养成 H5 游戏:孩子照顾一只叫「竹竹」的大熊猫,在刷牙、洗手、吃饭、穿衣、洗澡、睡觉、整理、运动、情绪、学习这十件小事里一件件帮它做好。产品指标只有一句「孩子今天愿意把某个好习惯真的做一遍」,由此定下所有技术取舍——没有失败、没有倒计时、没有体力、没有广告、没有账号,进度只存在本机。
架构是「Phaser 管游戏 + Vue 管外壳」的双栈,pnpm workspace 分成三层:apps/*(壳)、packages/*(库)、games/*(玩法包)。核心能力:
- 契约隔离:
packages/game-kit只放类型(GameModule/GameContext/ 事件表 / 存档形状),游戏包与外壳互不认识 - 内容驱动:一条任务 = 一份 JSON(摘要 + 详情),由 zod 在构建期与
content:check双重校验,换任务不改代码 - 模板复用:8 个交互模板撑 10 个任务,差异化全部落在关卡数据上
- 零美术资源:所有角色、房间、食物由代码绘制,12 个音效由 WebAudio 合成
- 可测:逻辑层不 import Phaser,单测(Vitest)全在 Node 环境跑;真实的按住/拖拽/连点交给 Playwright
- 多端:同一份
apps/site/dist喂 Web 静态站、Tauri 2 桌面壳与 Capacitor 8 安卓壳
环境准备
前置条件
| 依赖 | 版本 | 何时需要 |
|---|---|---|
| Node.js | 24 | 必需(Vite 8 与 Playwright 1.64 要求 20+,仓库以 24 为基线) |
| pnpm | 11.22.0 | 必需,版本由 packageManager 字段锁定 |
| Chromium | Playwright 自带 | 仅跑 pnpm e2e 时需要 |
| Rust 工具链 | — | 仅 pnpm dist:win(Tauri 2) |
| JDK + Android SDK | — | 仅 pnpm dist:apk(Capacitor 8);pack:check 不装也能跑 |
安装(两种方式)
# 方式一:Corepack(读 packageManager 字段,自动选到 11.22.0)
corepack enable
corepack prepare pnpm@11.22.0 --activate
# 方式二:全局安装指定版本
npm install -g pnpm@11.22.0
git clone https://github.com/znlgis/BambooBuddy.git
cd BambooBuddy
pnpm install # 本地开发:允许更新 lockfile
# pnpm install --frozen-lockfile # CI/发布:lockfile 与 package.json 不一致直接失败
验证
node -v # v24.x
pnpm -v # 11.22.0
pnpm typecheck && pnpm test
pnpm dev # http://127.0.0.1:5190(strictPort,端口被占用会直接退出)
打开 http://127.0.0.1:5190 能看到小屋(米白底色、程序化绘制的竹竹、五条状态条、底部三个大入口)即环境就绪。
常用命令
| 命令 | 作用 |
|---|---|
pnpm dev |
Vite 开发服务器 127.0.0.1:5190,改 packages/* 即时热更新 |
pnpm build |
生产构建,产物 apps/site/dist(base: './',可放任意子目录) |
pnpm preview |
预览构建产物 127.0.0.1:5191 |
pnpm test |
Vitest(environment: 'node',不碰 DOM/WebGL) |
pnpm content:check |
任务 JSON + 模板关卡脚本 + 双语完整性校验 |
pnpm pack:check |
Tauri/Capacitor 配置体检(不装 Rust/JDK 也能跑) |
pnpm size |
体积预算(读 dist,必须先 build) |
pnpm verify |
七阶段总门禁(见下节) |
pnpm dist:win / pnpm dist:apk |
桌面 exe / 安卓 apk(v1.0.0 起官方 Release 也直接提供这两类产物) |
核心 API
契约层(packages/game-kit/src/contract.ts)
契约文件只有类型与几个常量,没有运行时代码——它必须能被所有包引用而不引入副作用,也必须能在 Node 单测里直接 import。
export interface GameModule {
manifest: GameManifest;
mount(ctx: GameContext): Promise<void>; // 内部 new Phaser.Game(...)
unmount(): Promise<void>; // 必须 game.destroy(true),零全局残留
pause(): void; // game.loop.sleep()
resume(): void; // game.loop.wake()
}
export interface GameContext {
container: HTMLElement;
manifest: GameManifest;
content: TaskDetail; // 已是目标语言的翻译结果,游戏内不存在语言分支
services: PlatformServices; // storage / audio / lifecycle / telemetry / now()
locale: 'zh-CN' | 'en';
reducedMotion: boolean;
emit<K extends keyof GameEventMap>(type: K, payload: GameEventMap[K]): void;
requestExit(): void;
}
PlatformServices 是唯一的环境出口:场景不许直接 localStorage / fetch / Date.now()。这不是洁癖——时钟可注入,才让「连续 3 天得贴纸」这类规则能在单测里复现。
事件协议
一局只允许发五个事件,扩展要先改契约再改调试桥与 e2e:
| 事件 | 触发点 | 外壳拿它做什么 |
|---|---|---|
session:start |
模板 create(),紧跟 scene:enter |
不处理,进调试桥与遥测 |
scene:enter |
场景创建的第一件事 | 标记进入了哪个场景 |
task:retry |
BaseScene.noteMistake() |
不改存档,只做观测 |
task:complete |
BaseScene.finishTask(),一局唯一收尾 |
写存档、发奖励、弹完成卡 |
session:exit |
BaseScene.exit()(complete / quit / replay) |
replay 时原地卸载再挂载 |
「一局只有一个完成信号」是这套契约最硬的约束:模板不许自己拼奖励、不许自己写存档、不许绕过 finishTask() 退出。十个玩法的结算路径因此完全一致。
defineGame():三段式装配
十个玩法入口加起来不到 250 行,因为共用同一个工厂:
export interface GameDefinition {
manifest: GameManifest;
drawBeat?: (g, index, rect) => void; // 分幕插图:每条任务自己画
gameplay: (ctx: GameContext, session: SessionState) => GameplayStage;
}
export function defineGame(definition: GameDefinition): GameModule;
mount() 内部按「分幕故事 + 玩法场景 + 完成卡」组装场景列表并启动 Phaser。一个真实例子(刷牙,省略 import):
export default defineGame({
manifest,
drawBeat,
gameplay: (ctx, session) => ({
entry: SCENE_KEYS.scrub,
scenes: [
createScrubScene(ctx, {
level: scrubLevel(ctx.content), // 关卡数据从内容 JSON 取,不写死数字
session,
nextSceneKey: SCENE_KEYS.reward,
titleKey: 'scene.scrub',
drawWorld: (g, state) => drawBathroom(g, state),
reveal: ctx.content.extra.reveal,
}),
],
}),
});
内容模型(packages/content)
一条任务切成两份 JSON,切分依据是「谁在什么时候读它」:tasks/<id>.json 是摘要(首屏同步需要),details/<id>.game.json 是详情(含关卡脚本与三句语音文案,进入玩法时异步加载)。
关键设计:主入口只导出类型 export type { TaskSummary, TaskDetail },不导出 schema.ts 的运行时对象——z.object(...) 是真实副作用,一旦被主入口引用,zod 就会进入首屏(大约等于首屏三分之一的体积)。需要校验的地方走 @bamboo/content/full。
{
"id": "brush",
"title": "刷牙",
"timeSlots": ["morning", "evening"],
"template": "scrub",
"durationHintSec": 45,
"ageRange": [4, 8],
"unlockLevel": 1,
"stats": { "clean": 16, "mood": 5 },
"reward": { "shoots": 2, "xp": 12 },
"habit": "早晚都要刷牙",
"diary": "今天帮竹竹刷了牙,牙齿亮晶晶。",
"tip": "上面、下面、里面,都要刷到哦"
}
id 这个字符串同时出现在七处(内容 JSON、TASK_IDS、registry 键、games/daily 的 exports 子路径、manifest.id、存档键 save.tasks.brush、e2e 的 data-testid)。前四处有类型关联(Record<TaskId, ...> 少一个就编译失败),后三处靠 content:check 与 e2e 兜底。
八个模板
模板 = 交互原语 + 循环 + 纯逻辑判定(*.logic.ts)+ 外置绘制回调。同一模板被多条内容复用时,差异全部由关卡数据承担:
| 模板 | 交互原语 | 判定要点 |
|---|---|---|
scrub |
按住工具在目标区来回刷,刷干净后冲水/擦干 | 最近点位 + 半径命中、每点蹭够 rubs 次、finishTaps 次收尾 |
feed |
把食物拖到嘴边,一口一口吃完 | 每口递减、总口数、needKinds 类别均衡 |
dress |
把衣物拖到身上正确部位 | 槽位匹配、全部穿上 |
order |
按顺序完成睡前步骤 | 当前步骤 id,点错不清进度 |
tidy |
按类别把玩具拖进对应箱子 | 类别匹配、全部归位 |
rhythm |
竹竿开合,窗口内点按 | 墙钟三角波、zone、连点门 |
pick |
认出情绪再做安慰动作 | 目标情绪、轮次推进 |
learn |
颜色/形状/数字点选 | 答案下标、可无限重试 |
三条贯穿所有模板的行为规则:逐帧重画(游戏包在一个 drawXxx 回调里画整个世界);autoplay 走与真实操作相同的内部方法;零失败(放错弹回,不判错、不扣分,只有刻意体验的动作计 mistakes)。
存档与进度(packages/progress)
export const SAVE_SCHEMA_VERSION = 3;
export interface SaveData {
schemaVersion: number;
updatedAt: number;
pet: PetState; // 13 个字段:xp / stats / shoots / stickers / equipped ...
tasks: Record<TaskId, TaskProgress>;
arcade: Record<ArcadeGameId, ArcadeProgress>;
days: Record<string, DayRecord>; // 只保留最近 30 天
}
ProgressStore只有load()/save(data)两个方法——换一个存储实现是件小事(现在有 IndexedDB 与内存实现)- 星星口径写死为正向:失误 ≤1 给 3 颗、≤3 给 2 颗、其余 1 颗,没有 0 颗(类型里的
0只是取值域,不是产品口径) - 成长值四阶段:0 / 60 / 160 / 300;状态跨天才衰减,绝不半天掉状态
典型工作流:从零新增一个日常任务
输入:一条新习惯(定性、一句话提示、时段、收益、玩法骨架)。输出:大厅多一张任务卡、构建产物多一个几 KB 的懒加载 chunk、图鉴可收集。
以下以「整理书包」复用 tidy 模板为例。
步骤 1:写内容摘要 + 详情
新建 packages/content/src/tasks/packbag.json 与 details/packbag.game.json,再在 entries/index.ts 注册:
import rawPackbag from './packbag.json';
// 在 entries 数组里追加:
TaskSummarySchema.parse(rawPackbag),
步骤 2:写英文补丁
新建 i18n/en/packbag.json(结构镜像,数组按索引对齐),在 i18n/index.ts 的 patches.en 注册。面向孩子的关卡文案(如 orbs[].speak)同样要翻,漏翻会被 CJK 扫描抓住。
步骤 3:跑内容校验(内容先立住)
pnpm content:check
# · 整理书包 (packbag)
# · 信史 / 2 幕故事 / 2 道复习题 / 1 段玩法:tidy
关卡脚本不合法(光球数与槽位数不一致等)在这一步就会报错——内容通过后再写游戏代码。
步骤 4:写游戏包 games/packbag/
六个文件:package.json(@bamboo/game-packbag,workspace:* 依赖,exports 直连 src/index.ts)、src/manifest.ts、src/logic.ts、src/art.ts、src/index.ts、src/logic.test.ts;然后 pnpm install 建立 workspace 链接。
// src/logic.ts —— 纯逻辑:不碰 Phaser,可以直接单测
export function tidyLevel(content: TaskDetail): TidyLevel {
return TidyLevelSchema.parse(stageScript(content, 'tidy'));
}
步骤 5:外壳注册两处
apps/site/src/registry.ts 加一行 packbag: () => import('@bamboo/game-packbag');apps/site/package.json 加依赖。registry.test.ts 会强制「内容目录、注册表、懒加载入口」三方一致。
步骤 6:补端到端用例
在 e2e/ 加一条真实操作通关用例(拖拽坐标直接从内容 JSON 读,不手抄);双语载入与 autoplay 用例会枚举内容目录,自动覆盖新任务。
步骤 7:收尾验证
pnpm verify # 七阶段全绿
pnpm e2e # 真实鼠标操作 + autoplay 都过
pnpm audit:i18n # 文案/版面有改动时,人工看两种语言下的每个画面
质量门禁
pnpm verify 由 scripts/verify.mjs 编排:六个互不依赖的阶段并行跑,第七个(体积)必须等构建结束。
| 阶段 | 命令 | 拦下的问题 |
|---|---|---|
| typecheck | vue-tsc --noEmit |
契约改动漏改调用方、内容形状不符 |
| lint | eslint . --cache |
外壳误 import 完整内容;逻辑层用了 Math.random / Date.now |
| test | vitest run |
奖励口径、状态衰减、推荐确定性、模板判定、存档迁移、街机规则 |
| content:check | tsx packages/templates/src/cli/check-content.ts |
zod schema、关卡语义、时段覆盖、双语漏翻、伤害性文案 |
| pack:check | node scripts/check-packaging.mjs |
Tauri/Capacitor 配置(frontendDist/webDir、appId、图标) |
| build | vite build |
构建期错误、chunk 命名规则失效 |
| size | node scripts/check-size.mjs |
首屏、单 chunk、dist 总量等预算 |
为什么体积必须串行:它读的是构建产物。若与 build 并行,可能读到上一轮的 dist——那是最坏的一种假绿(旧产物不超标,新产物已经超了)。
六层门禁各自能证明什么、不能证明什么,值得记牢:类型证明形状自洽,不证明手感;单测证明判定,不证明画面;e2e 证明真浏览器里点得通,不证明低端机帧率。用错误的工具测,比不测更危险。
调试直达:三个 URL 开关
| 参数 | 作用 |
|---|---|
autoplay=1 |
场景自己模拟输入,把这一局走完 |
instant=1 |
跳过过场、语音等待与完成卡停留(不改判定、不改奖励) |
lang=en |
强制英文(en / en-US / zh / zh-CN 都认) |
http://127.0.0.1:5190/#/play/brush?autoplay=1
http://127.0.0.1:5190/?lang=en#/play/feed
http://127.0.0.1:5190/#/play/sleep?autoplay=1&instant=1
生产环境里 ?autoplay=1 默认无效,除非浏览器由自动化驱动(navigator.webdriver === true)——否则拿到分享链接就能自动通关刷星,对儿童产品是信任问题。
此外控制台里可以读 window.__bamboo.events(事件序列)、window.__bamboo.save(当前存档)与 window.__bamboo.lastError(最近一次载入失败详情)。
最佳实践
- Phaser 实例用
shallowRef/markRaw持有:ref会深度代理整个 Phaser 对象图(场景、纹理、WebGL 上下文)。 - 离场必须
await unmount()(内部game.destroy(true));不要套<KeepAlive>/<Transition>,否则 canvas 会叠。 - 逻辑层禁用
Math.random与Date.now(eslint 强制):时钟从services.now()或构造注入。 - 长按/等待类进度按墙钟计时,不累加帧间隔:Phaser 低帧率时会钳制 delta,慢手机上「按住 6 秒」会攒不够。
- 先内容后代码:JSON 过
content:check再写游戏包,避免边写边改 schema。 - 三处对账:内容 JSON /
entries/index.ts/registry.ts(+ apps/site 依赖),registry.test.ts兜底。 - 屏幕文字按英文长度设限(
story.text ≤ 90 字符),长内容交给narration走 TTS。 - 不要手删
node_modules/.pnpm:里面是真实文件,各包只有符号链接;清理后重装往往比修复更快。
常见问题
| 问题 | 原因与解决 |
|---|---|
pnpm install 报找不到 workspace 依赖 / workspace:* 无法解析 |
用错包管理器:删 node_modules 后用 pnpm 重装,全仓统一 pnpm |
vue-tsc 报 ERR_PACKAGE_PATH_NOT_EXPORTED: './lib/tsc' |
TypeScript 被升到 7.x 了;仓库刻意锁 ~5.9.3(vue-tsc 依赖该子路径),恢复锁定版本,勿 pnpm add typescript@latest |
| 端口 5190 被占用 | strictPort: true 会直接退出;停掉占用进程(改端口需同步 e2e baseURL,更推荐前者) |
pnpm e2e 报没找到浏览器 |
先 pnpm exec playwright install chromium(CI 用 --with-deps chromium) |
pnpm size 报 ENOENT ... apps/site/dist/index.html |
size 读构建产物,先 pnpm build;pnpm verify 内部顺序已排好 |
pnpm dist:apk 报 Unsupported class file major version 69 |
JDK 25 超出 Gradle 8.14 支持范围;装 JDK 17–24(Temurin 21 即可),或用 BAMBOO_JDK 指定 JDK 目录(scripts/build-apk.mjs 会按此顺序找 JDK) |
首屏出现了 vendor-phaser chunk |
有代码静态 import 了 Phaser;检查外壳是否 import 了 @bamboo/templates(外壳依赖里不该有它) |
| 游戏打不开,界面只有一句「这个任务暂时打不开」 | 技术详情在 window.__bamboo.lastError 与控制台;多为内容/关卡校验失败,跑 pnpm content:check 定位 |
| 进度会丢吗 | 本机 IndexedDB(无账号、不同步);刷新/重开都在,清浏览器数据或换设备会丢;云存档只需替换 ProgressStore 实现 |
AI 使用建议
- 执行环境:用
pnpm(根package.json的packageManager锁版本)与 Node.js 24;命令在终端 / shell 中执行(Windows 用 PowerShell)。 - 先探测版本:
pnpm -v、node -v与仓库package.json比对;玩法包与外壳各自是独立 workspace 包,新增依赖要写进对应包的package.json。 - 验证产物:改完跑
pnpm verify(类型 / 单测 / 内容校验 / 打包体积四道门禁),再pnpm dev打开页面确认任务可玩;类型检查通过不代表玩法正确,window.__bamboo调试桥可用于快速跳任务。 - 常见误操:任务 JSON 由 zod 校验,字段缺失可能静默不回显,改内容后先看 verify 的内容阶段;长任务放后台运行并落盘日志。
- 安全与权限:新增依赖、改
packageManager版本、执行pnpm install前先征得用户同意;打包产物与node_modules不要提交。
相关技能
- chags — 同一作者的姐妹项目:印证同一套「内容与代码分离 + 模板库」结构能撑起几十个小游戏:../chags/SKILL.md
- vue3-map-dashboard — Vue 3 + Vite + TypeScript 前端工程(外壳侧的技术栈对照):../../demos/vue3-map-dashboard/SKILL.md
- photo-sphere-viewer — 同为 TypeScript + Vite 构建的浏览器 WebGL 应用(打包与体积门禁思路可复用):../../3d/photo-sphere-viewer/SKILL.md
- docker-compose — 静态站点的容器化部署方式:../docker-compose/SKILL.md
参考资源
- 仓库:https://github.com/znlgis/BambooBuddy
- 在线试玩:https://znlgis.github.io/bamboobuddy/
- 17 章中文教程:https://znlgis.github.io/others/BambooBuddy/
- Phaser:https://phaser.io/ | Vue:https://vuejs.org/ | Pinia:https://pinia.vuejs.org/
- Vitest:https://vitest.dev/ | Playwright:https://playwright.dev/
- Tauri:https://tauri.app/ | Capacitor:https://capacitorjs.com/