feat: 建立项目基础设施
- 添加 CLAUDE.md（项目上下文，AI 自动加载） - 添加三角色 Agent 体系（策划/程序/美术） - 添加 /zqstart /plan /design /dev /art 命令 - 创建 docs/ 目录结构（design/art/technical/plans） - 创建 config/ 数值配置目录 - 添加美术风格指南（3D Lowpoly 温暖怀旧） - 添加进度追踪文件（current.md + roadmap.md） - 精简 Git 规范（GIT-GUIDE-LITE.md） - 更新 README.md 项目简介
This commit is contained in:
@@ -0,0 +1,75 @@
|
||||
# Git 快速参考（AI 用）
|
||||
|
||||
> 从 [GIT-GUIDE.md](GIT-GUIDE.md) 精简。完整规范见原文。
|
||||
|
||||
---
|
||||
|
||||
## 分支策略
|
||||
|
||||
**轻量 Feature Branch** — 单人开发，`main` 永远可玩可编译。
|
||||
|
||||
| 分支 | 前缀 | 生命期 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 主线 | `main` | 永久 | 稳定版本，不直接在上面开发 |
|
||||
| 功能 | `feature/` | 合并后删 | 新系统、新功能 |
|
||||
| 修复 | `fix/` | 合并后删 | Bug 修复 |
|
||||
| 原型 | `prototype/` | 实验完即删 | 技术验证，随便写 |
|
||||
| 发布 | `release/` | 永久 | 从 main 切出，版本标记 |
|
||||
|
||||
**命名规则：** `<类型>/<小写连字符描述>`
|
||||
```
|
||||
feature/player-movement fix/camera-clipping release/v0.1
|
||||
```
|
||||
|
||||
**流程：**
|
||||
1. 从 `main` 拉分支 → 2. 开发并提交 → 3. 测试通过后合并回 `main` → 4. 删除分支
|
||||
|
||||
---
|
||||
|
||||
## 提交规范
|
||||
|
||||
**格式：** `<type>(<scope>): <中文描述>`
|
||||
|
||||
- subject ≤ 50 字符，中文描述，技术术语保留英文
|
||||
- body 可选，每行 ≤ 72 字符
|
||||
|
||||
**Type（必选）：**
|
||||
|
||||
| Type | 用途 |
|
||||
|---|---|
|
||||
| `feat` | 新功能 |
|
||||
| `fix` | Bug 修复 |
|
||||
| `art` | 美术资源 |
|
||||
| `level` | 关卡/场景 |
|
||||
| `audio` | 音效/音乐 |
|
||||
| `bp` | 蓝图逻辑 |
|
||||
| `refactor` | 重构（不改功能） |
|
||||
| `config` | 项目/引擎配置 |
|
||||
| `docs` | 文档 |
|
||||
| `wip` | 进行中（未完成） |
|
||||
|
||||
**Scope（可选，常用）：**
|
||||
`player` `enemy` `combat` `ui` `camera` `inventory` `dialogue` `quest` `save` `audio` `animation` `ai` `level` `vfx`
|
||||
|
||||
**示例：**
|
||||
```
|
||||
feat(player): 实现角色跳跃和二段跳
|
||||
fix(camera): 修复穿墙时摄像机卡顿问题
|
||||
bp(enemy): 实现巡逻-追击-攻击状态机
|
||||
wip(crafting): 合成系统UI初步框架
|
||||
config: 启用Nanite和Lumen
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UE5 注意事项
|
||||
|
||||
- 蓝图与 C++ 分开提交
|
||||
- `.uasset` / `.umap` 无法 diff → commit message 必须写清改了什么
|
||||
- 不提交 `Binaries/` `Intermediate/` `Saved/` `.vs/`
|
||||
|
||||
---
|
||||
|
||||
## 版本号
|
||||
|
||||
`v主版本.次版本.修订号` — 主版本=里程碑，次版本=新系统，修订号=小修
|
||||
@@ -0,0 +1,17 @@
|
||||
# docs/art/ — 美术文档
|
||||
|
||||
美术 Agent 的输出目录。包含风格指南、资产规格、参考图等。
|
||||
|
||||
## 文件组织
|
||||
|
||||
```
|
||||
docs/art/
|
||||
style-guide.md # 风格指南（所有美术产出的锚点）
|
||||
asset-specs/ # 各资产的规格文档
|
||||
references/ # 参考图、情绪板（图片文件）
|
||||
```
|
||||
|
||||
## 核心文件
|
||||
|
||||
- **style-guide.md** — 视觉风格锚点，所有美术产出必须符合此指南
|
||||
- 每个资产一个规格文档，说明尺寸、面数、贴图要求等
|
||||
@@ -0,0 +1,60 @@
|
||||
# 美术风格指南 — ChildHood（我的童年）
|
||||
|
||||
> 本文档为所有美术产出的视觉锚点。任何资产制作前必须先参考此指南。
|
||||
|
||||
---
|
||||
|
||||
## 总体风格
|
||||
|
||||
**3D Lowpoly — 温暖怀旧的80年代中国乡村**
|
||||
|
||||
低多边形建模风格，强调形状的简洁与色彩的温暖感。不追求写实，而是通过精简的几何体和柔和的色彩唤起童年记忆中的那份纯真与温暖。
|
||||
|
||||
---
|
||||
|
||||
## 色彩方向
|
||||
|
||||
- **主色调**: 暖黄、土褐、草绿 — 对应乡村的自然环境
|
||||
- **辅助色**: 天蓝、夕阳橙、烟囱灰 — 营造时间流逝感
|
||||
- **避免**: 高饱和度荧光色、冷硬的工业色系
|
||||
- **整体氛围**: 阳光洒在泥土路上的温暖感，而非阴暗或压抑
|
||||
|
||||
---
|
||||
|
||||
## 建模规范
|
||||
|
||||
- **面数控制**: 低多边形，单个道具 < 500 面，角色 < 3000 面
|
||||
- **轮廓优先**: 物体的剪影要一眼可辨（弹珠是圆的，毽子有羽毛）
|
||||
- **不做**: 细节雕刻、高精度法线贴图、写实材质
|
||||
- **比例**: 略带卡通化，角色头部偏大，四肢圆润
|
||||
|
||||
---
|
||||
|
||||
## 贴图与材质
|
||||
|
||||
- **贴图风格**: 手绘感，色块分明，像素边缘不过度抗锯齿
|
||||
- **材质类型**: 主要是 Unlit 或简单的 Lambert，不做复杂 PBR
|
||||
- **贴图尺寸**: 道具 128×128 或 256×256，角色 512×512
|
||||
- **色调映射**: 保持色彩明亮温暖，避免过暗的阴影
|
||||
|
||||
---
|
||||
|
||||
## 参考关键词
|
||||
|
||||
- 低多边形乡村 / Lowpoly countryside
|
||||
- 怀旧游戏美术 / Nostalgic game art
|
||||
- 80年代中国农村 / 1980s rural China
|
||||
- 温暖色调低模 / Warm tone lowpoly
|
||||
- 《纪念碑谷》色彩感（参考方向，非照搬）
|
||||
|
||||
---
|
||||
|
||||
## 典型场景元素
|
||||
|
||||
| 类别 | 示例 |
|
||||
|---|---|
|
||||
| 地形 | 泥土路、田埂、小溪、山坡 |
|
||||
| 建筑 | 砖瓦房、土墙院落、小卖部、祠堂 |
|
||||
| 植被 | 草地、稻田、大树、竹丛、菜地 |
|
||||
| 道具 | 弹珠、毽子、竹蜻蜓、纸飞机、橡皮筋 |
|
||||
| 角色 | 男孩、女孩、小伙伴、邻居爷爷/奶奶 |
|
||||
@@ -0,0 +1,24 @@
|
||||
# docs/design/ — 策划文档
|
||||
|
||||
策划 Agent 的输出目录。所有玩法设计、系统机制、剧情叙事文档存放于此。
|
||||
|
||||
## 文件组织
|
||||
|
||||
```
|
||||
docs/design/
|
||||
activities/ # 各活动/小游戏的设计文档
|
||||
systems/ # 系统机制设计（时间系统、NPC 关系等）
|
||||
narrative/ # 剧情/叙事设计
|
||||
```
|
||||
|
||||
## 格式约定
|
||||
|
||||
- Markdown 格式
|
||||
- 每个活动/系统一个独立文件
|
||||
- 文件名使用小写英文 + 连字符：`marble-game.md`、`time-system.md`
|
||||
|
||||
## 与其他 Agent 的关系
|
||||
|
||||
- 程序 Agent 读取此目录的设计文档作为开发需求
|
||||
- 美术 Agent 读取设计文档中的美术需求部分
|
||||
- 数值参数抽到 `config/` 目录下的 CSV/JSON 文件中
|
||||
@@ -0,0 +1,19 @@
|
||||
# 当前进度
|
||||
|
||||
> 最后更新：2026-05-31
|
||||
> 代理完成工作后汇报结果，由开发者确认后才勾选 ✔
|
||||
|
||||
## 当前里程碑：v0.1 第一个可玩原型
|
||||
|
||||
### 进行中
|
||||
|
||||
- [ ] 建立项目基础设施（目录结构、规范文档）
|
||||
|
||||
### 待开始
|
||||
|
||||
（待策划定义 v0.1 的具体功能范围）
|
||||
|
||||
### 已完成
|
||||
|
||||
- [x] Git 分支策略与提交规范
|
||||
- [x] 项目目录结构与协作体系设计
|
||||
@@ -0,0 +1,18 @@
|
||||
# 项目路线图
|
||||
|
||||
## v0.1 — 第一个可玩原型
|
||||
|
||||
**目标**: 跑通核心玩法循环，验证"童年体验"的乐趣点
|
||||
|
||||
- [ ] 定义 v0.1 包含的活动（弹珠？捉虫？跳绳？）
|
||||
- [ ] 核心系统：玩家移动与交互
|
||||
- [ ] 场景：乡村环境白盒
|
||||
- [ ] 至少一个完整可玩的小游戏
|
||||
|
||||
## v0.2 — 核心玩法成型
|
||||
|
||||
（待 v0.1 完成后规划）
|
||||
|
||||
## v1.0 — 正式发布
|
||||
|
||||
（远期目标）
|
||||
@@ -0,0 +1,17 @@
|
||||
# docs/technical/ — 技术文档
|
||||
|
||||
程序 Agent 的文档输出目录。包含技术架构、实现笔记、技术决策记录。
|
||||
|
||||
## 文件组织
|
||||
|
||||
```
|
||||
docs/technical/
|
||||
architecture.md # 项目技术架构总览
|
||||
implementation-notes/ # 各系统的实现笔记
|
||||
```
|
||||
|
||||
## 格式约定
|
||||
|
||||
- Markdown 格式
|
||||
- 记录"为什么这么做"而非仅"做了什么"
|
||||
- 实现笔记与 `docs/design/` 中的设计文档一一对应
|
||||
Reference in New Issue
Block a user