Bobby Carrot 是一个纯 Vite + TypeScript 实现的网格解谜游戏。玩家控制兔子在 50px 网格地图中移动，收集每关要求的胡萝卜，理解机关规则，最终抵达出口。
终端版已发布到 npm：
npm install -g bobbygame
bobby-carrot每一关都是一个小型机关谜题：
- 收集当前关卡要求数量的胡萝卜。
- 避开或利用陷阱、方向石、传送带、锁和按钮。
- 找到可行路径，到达终点或打开出口。
- 在移动端可以使用底部方向舵，桌面端使用方向键或 WASD。
- 网页游戏和
/editor都支持中文 / English 切换。
项目目前包含 30 个关卡，关卡数据按文件拆分在 src/content/levels/。每关由 tilemap、实体实例和机关变量组成，运行时统一转换为游戏状态。
核心设计元素：
- 胡萝卜目标：每关有独立的收集目标，HUD 中的
Remain会显示剩余数量。 - 钥匙与锁：钥匙按颜色匹配锁，开锁后钥匙会被消耗，已持有钥匙会显示在右上角。
- 方向石：只能从开口方向进出。兔子踩过后离开格子时，方向石顺时针旋转一次。
- 石块：按当前方向限制通行。红色按钮会影响地图内石块方向。
- 传送带：按单向方向传送兔子，不能逆向进入。黄色按钮会反转传送带方向。
- 按钮组：踩下当前按钮后，同类型其他按钮会反转状态，并触发对应机关变化。
- 陷阱：第一次踩下会进入待触发状态，离开后重新变危险；再次踩中会失败。
- 出口：满足胡萝卜数量后出口打开，进入后完成关卡。
关卡设计鼓励“先观察，再行动”：很多路线不是靠连续移动完成，而是通过改变机关状态、规划踩踏顺序和利用单向移动完成。
/editor 提供一个网页关卡编辑器，面向社区共建关卡的本地创作流程：
- 从空白关卡开始，或加载内置
map1到map30作为参考。 - 使用真实素材预览的 tile 和 entity 工具在 50px 网格上摆放地形、胡萝卜、机关、出口和玩家。
- 实体工具覆盖素材图集里的主要关卡对象：栅栏/墙体、陷阱状态、方向石、传送带方向、按钮状态、三色钥匙锁和装饰素材。
- 右侧 Asset Animation 面板可以查看和调整素材对象的动画定义，包括动作、帧序列、速度、循环状态和单帧 atlas 坐标，并可导出修改后的 asset manifest JSON。
- 通过右侧属性面板编辑方向石、传送带、钥匙锁、按钮和陷阱状态。
- 实时复用运行时关卡校验，提示缺玩家、缺出口、目标胡萝卜数量不合理、实体出界等问题。
- 使用 Playtest 在当前浏览器页内直接试玩正在编辑的关卡。
- 导出
.bobby-level.json，里面包含标题、作者、难度、标签和LevelDefinition。 - 使用 Save Local 保存到浏览器本地关卡库，再用 Open Game 直接以游戏模式打开。
- 支持 Undo / Redo，选择工具下可以拖拽移动实体。
第一版编辑器是本地文件流，不依赖账号或服务器。社区投稿可以先以 .bobby-level.json 附件、issue 或 PR 的方式提交；正式收录前应运行：
npm run validate:levels保存到本地关卡库后，也可以用 URL 直接试玩：
http://localhost:5173/?community=<local-level-id>npm install
npm run dev默认地址：http://localhost:5173/
指定关卡可以加查询参数：
http://localhost:5173/?map=map20社区关卡编辑器：
http://localhost:5173/editor构建：
npm run typecheck
npm run validate:levels
npm run build项目同时提供一个 TUI 版本，可以在终端里直接玩同一套关卡数据：
npm install -g bobbygame
bobby-carrot安装后会提供两个命令入口，bobby-carrot 是完整命令，bobbyc 是短命令：
bobby-carrot --map map1
bobbyc --map map20 --ascii也可以不全局安装，直接临时运行 npm 包：
npx --package bobbygame bobbyc --map map1本地开发时可以先构建再运行：
npm run build:tui
node dist-tui/cli.js --map map1TUI 默认使用 emoji / symbol 渲染，地砖、障碍、玩家、目标、钥匙、锁、按钮和传送带都会用终端字符展示。部分终端对 emoji 宽度处理不一致时，可以切换到 ASCII 模式：
bobby-carrot --map map1 --ascii终端控制：
- 方向键 / WASD：移动兔子
- R：重开当前关
- N：通关后进入下一关
- Q / Ctrl+C：退出
本地生成 npm 安装包：
npm pack
npm install -g ./bobbygame-*.tgz
bobby-carrot完整架构说明见 docs/architecture.md。
src/main.ts 浏览器启动入口
src/game/runtime.ts 浏览器运行时生命周期、输入、渲染调度
src/game/simulation.ts 纯游戏状态更新入口
src/game/levelAdapter.ts Construct 导出布局到内部关卡定义的适配层
src/game/levelValidation.ts 关卡结构和数据质量校验
src/game/movement.ts 网格移动、碰撞、锁、传送带移动
src/game/interactions.ts 胡萝卜、钥匙、陷阱、出口等到达格处理
src/game/buttons.ts 红色/黄色按钮和机关联动
src/game/render.ts Canvas 渲染、HUD、胜利/失败提示
src/game/touchControls.ts 移动端方向舵
src/tools/validate-levels.ts 关卡校验 CLI
src/tui/cli.ts 终端版本入口和字符渲染
src/content/levels/ 关卡数据，每关一个文件
src/content/assets.ts 精灵图坐标和动画配置
public/assets/ 图片、音频、字体素材欢迎围绕“关卡设计”和“机关表现”参与贡献。比较适合的贡献方向：
- 新增关卡：基于现有关卡格式提交新的
mapXX.ts，说明目标胡萝卜数量、机关组合和推荐通关思路。 - 优化关卡：修复不可达路径、错误机关方向、误导性摆放、过难或过简单的路线。
- 补齐机制：如果发现和预期规则不一致，可以提交最小复现场景或直接修复运行时逻辑。
- 改进素材：在保持原版像素风的前提下，提升精灵、音效、HUD 和移动端控制体验。
- 测试与验收：补充关键关卡的通关路径说明、截图或自动化回归检查。
提交建议：
- 一个 PR 聚焦一个主题，例如“修复第 4 关传送带方向”或“新增第 31 关”。
- 关卡改动请说明变更前后的可通关路径。
- 机制改动请说明影响到哪些实体类型，并尽量附带测试关卡或截图。
- 提交前运行
npm run typecheck、npm run validate:levels和npm run build。
当前项目是纯 Vite + TypeScript 工程。地图、精灵、机关和状态机都由仓库内代码和数据驱动，方便社区继续维护和扩展。