# BubbleMasterGodot

**Repository Path**: ppppromise/bubble-master-godot

## Basic Information

- **Project Name**: BubbleMasterGodot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 奶茶大师（Godot）工程说明

## 项目简介
《奶茶大师》是一个面向移动端竖屏的轻度模拟经营游戏工程，当前使用 `Godot 4.6.2` 与 `GDScript` 开发。项目核心体验围绕接单、理解需求、制作奶茶、出餐与成长闭环展开，不追求复杂厨房管理，而是追求轻松、清晰、可持续扩展的经营节奏。

工程名在 `project.godot` 中暂为 `BubbleGodot`，游戏概念名使用《奶茶大师》。当前仓库的重点是把已有玩法稳定地放进手机竖屏结构中，并把 AI 协作所需的工程治理补齐。

## 当前阶段
当前阶段为 `P2：移动端结构收口后，优先级切回 MVP 补齐`。当前重点不是继续深挖单个 UI 模块，而是冻结 MVP 范围、收口存档/恢复边界、补齐验收与设计入口，并保持订单循环稳定。

当前不建议优先扩展装修、成就、大量新配料或复杂剧情，因为这些内容都依赖主界面结构稳定之后再做，过早扩展只会放大返工。

## 快速开始
1. 先阅读接手入口：[`doc/项目管理/接手开发入口.md`](./doc/项目管理/接手开发入口.md)
2. 再阅读项目索引：[`doc/项目管理/项目索引.md`](./doc/项目管理/项目索引.md)
3. 再阅读路线图：[`doc/项目管理/项目路线图与执行状态.md`](./doc/项目管理/项目路线图与执行状态.md)
4. 再阅读架构与规范：[`doc/架构/项目架构说明.md`](./doc/架构/项目架构说明.md)、[`doc/开发规范/Godot开发规范.md`](./doc/开发规范/Godot开发规范.md)、[`doc/开发规范/编码与文本资源规范.md`](./doc/开发规范/编码与文本资源规范.md)
5. 开始改中文文本前，先执行编码自检：[`doc/开发流程/编码自检说明.md`](./doc/开发流程/编码自检说明.md)
6. 如果是新 agent 接手，先执行标准接手流程：[`doc/项目管理/新Agent接手SOP.md`](./doc/项目管理/新Agent接手SOP.md)
7. 打开工程主场景：`scenes/main/main.tscn`
8. 核对主脚本与数据层：`scripts/main/main.gd`、`scripts/data/game_data.gd`、`scripts/autoload/game_state.gd`

## 目录结构
- `scenes/`：场景资源，当前主场景在 `scenes/main/main.tscn`
- `scripts/`：脚本资源，包含主逻辑、数据定义与全局状态
- `doc/`：项目文档，包含路线图、架构、规范与开发经验沉淀
- `.godot/`：Godot 编辑器缓存与本地状态，通常不手工编辑
- `project.godot`：工程配置文件，包括入口场景、分辨率、伸缩方式与自动加载

## 核心文档入口
- [`doc/项目管理/接手开发入口.md`](./doc/项目管理/接手开发入口.md)
- [`doc/项目管理/新Agent接手SOP.md`](./doc/项目管理/新Agent接手SOP.md)
- [`doc/项目管理/项目索引.md`](./doc/项目管理/项目索引.md)
- [`doc/项目管理/项目路线图与执行状态.md`](./doc/项目管理/项目路线图与执行状态.md)
- [`doc/项目管理/MVP范围与完成定义.md`](./doc/项目管理/MVP范围与完成定义.md)
- [`doc/项目管理/文档与代码落地差距清单.md`](./doc/项目管理/文档与代码落地差距清单.md)
- [`doc/架构/项目架构说明.md`](./doc/架构/项目架构说明.md)
- [`doc/架构/场景树说明.md`](./doc/架构/场景树说明.md)
- [`doc/架构/数据模型说明.md`](./doc/架构/数据模型说明.md)
- [`doc/开发规范/Godot开发规范.md`](./doc/开发规范/Godot开发规范.md)
- [`doc/开发规范/编码与文本资源规范.md`](./doc/开发规范/编码与文本资源规范.md)
- [`doc/设计/UI规范.md`](./doc/设计/UI规范.md)
- [`doc/设计/文案规范.md`](./doc/设计/文案规范.md)
- [`doc/开发流程/功能开发检查清单.md`](./doc/开发流程/功能开发检查清单.md)
- [`doc/开发流程/编码自检说明.md`](./doc/开发流程/编码自检说明.md)
- [`doc/测试/P2阶段回归执行记录.md`](./doc/测试/P2阶段回归执行记录.md)
- [`doc/测试/核心回归清单.md`](./doc/测试/核心回归清单.md)
- [`doc/测试/自动化回归说明.md`](./doc/测试/自动化回归说明.md)
- [`doc/测试/MVP验收清单.md`](./doc/测试/MVP验收清单.md)
- [`doc/AI协作/AI Agent 工作手册.md`](./doc/AI协作/AI%20Agent%20工作手册.md)
- [`doc/规划/P2进入P3判定标准.md`](./doc/规划/P2进入P3判定标准.md)
- [`doc/版本记录/变更日志.md`](./doc/版本记录/变更日志.md)
- [`doc/游戏设计/核心玩法说明文档.md`](./doc/游戏设计/核心玩法说明文档.md)
- [`doc/开发经验沉淀/本次Godot启动问题排查经验.md`](./doc/开发经验沉淀/本次Godot启动问题排查经验.md)

## Agent 补丁工具
- [`tools/agent-patch/README.md`](./tools/agent-patch/README.md)
- [`doc/开发文档/Agent安全补丁工具设计.md`](./doc/开发文档/Agent安全补丁工具设计.md)

## 开发原则
- 必须优先保持移动端竖屏产品方向，默认按手机操作习惯思考
- 必须优先保护已跑通的一整单流程，避免无必要重写底层逻辑
- 必须先解决结构性问题，再扩展内容性问题
- 必须在新增功能后同步更新项目状态与架构认知
- 禁止在 `.tscn` 中随意堆积大量中文文案，避免编码污染
- 禁止把可复用规则直接写死在 UI 脚本里
- 提交前必须确认主场景可打开、主流程可跑通、中文显示不乱码

## 文档维护
如果项目阶段、主入口脚本、目录结构或技术边界发生变化，优先同步更新本文件与项目索引，再更新其他专项文档。