diff --git a/.agents/skills/source-command-split-commit/SKILL.md b/.agents/skills/source-command-split-commit/SKILL.md new file mode 100644 index 000000000..c80917d6f --- /dev/null +++ b/.agents/skills/source-command-split-commit/SKILL.md @@ -0,0 +1,140 @@ +--- +name: "source-command-split-commit" +description: "将当前未提交改动拆分为多个符合规范的原子提交" +--- + +# source-command-split-commit + +Use this skill when the user asks to run the migrated source command `split-commit`. + +## Command Template + +将当前未提交改动拆分为多个原子提交。执行前会分析变更、生成分组方案，经用户确认后逐组提交。 + +## 执行流程 + +### Step 1: 前置检查 + +1. **清理残留文件**：若存在 `msg.txt`，先 `rm -f msg.txt` +2. **读取规范**：确认 `COMMIT_CONVENTION.md` 存在且可读 + +### Step 2: 保护分支检查 + +保护分支列表（按优先级）：`AGENTS.md` > `.cursor/rules/` > `.git/config branch.protected` > 默认(`master|main|develop`) + +若当前在保护分支，询问用户： +- **A** - 创建 feature 分支后继续拆分（推荐） +- **B** - 转移到新分支后压成单提交 +- **C** - 取消 + +### Step 3: 盘点变更 + +执行以下命令分析： +- `git status` - 整体状态 +- `git diff --stat` - 文件统计 +- `git diff` - 详细改动 +- `git diff --cached` - 已暂存改动 + +### Step 4: 规则化分组 + +按"意图一致"原则分组，**优先按 type 分，再按 scope 分**。 + +**必须拆分的情况**： +- 同一组可归属多个 type +- 同文件包含多个独立目的（如功能+重构） +- 资源替换与代码逻辑混合 + +**可以合并的情况**（最小拆分原则）： +- 同一功能的多文件改动（脚本+Prefab） +- 同一模块的多个相关 Bug 修复 + +### Step 5: 生成方案表格 + +以表格形式展示拆分方案： + +| 顺序 | 文件 | 变更目的 | 提交头 | 依据 | 方式 | +|------|------|----------|--------|------|------| +| 1 | `路径` | 描述 | `type(scope): subject` | 原因 | `git add`/`git add -p` | + +**Type 选择优先级**：`fix` > `feat` > `art` > `audio` > `scene` > `yarn` > `perf|refactor|...` + +**Scope 规则**：单模块用模块名（如 `blockpuzzle`），跨模块省略。 + +### Step 6: 用户确认 + +询问：`[Y 执行 / n 取消 / 提出调整]` + +- 若调整：根据反馈修改方案，再次确认 +- 若执行：进入 Step 7 +- 若取消：清理并退出 + +### Step 7: 逐组提交 + +对每组执行： +1. `git add ` 或 `git add -p ` +2. 复查：`git diff --cached --stat` 和 `git diff --cached` +3. 写入 `msg.txt` 并提交：`git commit -F msg.txt` +4. 检查状态：`git status` + +**失败处理**： +- `git add -p` 跳过关键 hunk → 暂停，提示处理方案 +- pre-commit hook 失败 → 询问 [R]重试 [S]跳过 [A]中止 + +### Step 8: 结果校验 + +输出： +1. `git log --oneline -` +2. 回放清单（验证 type/scope/subject 合规性） +3. 若不合规，询问是否修正 + +### Step 9: 清理 + +`rm -f msg.txt` + +--- + +## Unity 改动速查表 + +| 改动类型 | type | scope 示例 | +|----------|------|-----------| +| 脚本逻辑修复 | `fix` | `blockpuzzle`, `dialog` | +| 脚本新功能 | `feat` | `huoshan`, `clue` | +| 美术资源（贴图/模型/动画） | `art` | 对应模块或省略 | +| 音频资源 | `audio` | `audio-kit` 或省略 | +| 场景配置（灯光/镜头） | `scene` | 对应模块或省略 | +| Yarn 对话 | `yarn` | `dialog` | +| 测试代码 | `test` | 对应模块 | + +--- + +## 规范校验清单（执行前检查） + +- [ ] 格式：`(): ` 或 `: ` +- [ ] type ∈ {`feat`,`fix`,`art`,`audio`,`scene`,`yarn`,`perf`,`refactor`,`style`,`docs`,`build`,`chore`,`test`} +- [ ] subject：中文、动词开头、≤50字、无句号 +- [ ] 一次提交只做一件事 + +--- + +## 中文提交方法 + +由于 PowerShell 中文乱码问题，统一使用文件方式： + +```bash +echo "type(scope): 描述" > msg.txt +git commit -F msg.txt +rm -f msg.txt +``` + +--- + +## 关于 Pre-commit Hooks + +若配置了 husky/lint-staged： +- 每次提交都会触发检查 +- 如需跳过（**不推荐**）：`git commit -F msg.txt --no-verify` +- 跳过可能导致 CI 失败 + +--- + +开始执行请回复 **"开始"**，或告知需要的调整。 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..a478c5699 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,152 @@ +# AGENTS.md + +This file provides guidance to Codex (Codex.ai/code) when working with code in this repository. + +## Project Overview + +AIBIS Dream (also known as "AllOurBrokenParts") is a Unity-based narrative adventure game with investigative elements. The project uses Yarn Spinner for dialogue, features a custom framework with modular systems, and includes multiple mini-games and a modular repair/fix system. + +**Unity Version:** 2022.3.7f1c1 (Universal Render Pipeline) + +## Architecture + +### Core Framework (Assets/Scripts/Framework/) + +Modular framework with Kit-pattern utilities: + +- **ActionKit**: Action sequencing and command pattern +- **AudioKit**: Audio management (includes FMOD integration) +- **Config / Core**: Configuration and core utilities +- **EventSystemKit**: Decoupled event system +- **LogKit**: Structured logging with categories +- **PoolKit**: Object pooling +- **ResourceKit**: Asset loading via `ResourceSystem` (Addressables-based) + - **Note**: New code must use `ResourceSystem`, never `Resources.Load`. See [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md). Asset placement rules in [Resource Management Spec](Docs/ResourceManagementSpec.md). +- **SelectorKit**: Weighted/batch/non-repeat random selection +- **SingletonKit**: Singleton base classes +- **StateMachineKit**: State management +- **OtherKit**: Miscellaneous utilities (`CameraKit`, `AnimatorKit`, `FadeKit`, `LocalizationKit`, etc.) +- **Attribute**: Custom editor attributes + +### Key Game Systems + +- **Game Loop** (Scripts/Game Loop/): `GameManager` (Singleton entry), `YarnVariableStorage` (Yarn variables), `SaveRestoreOrchestrator` / `SaveSystem` (save snapshots), `SceneLoader`, `ChapterController`, `TalkSceneSO` +- **Dialog System** (Scripts/Dialog System/): Yarn Spinner integration — `DialogController`, `LineRunner`, `LocalisedLineProvider`, `BaseYarnCommand` +- **SceneManagement** (Scripts/SceneManagement/): `ActorKit/`, `AnimatorKit/`, `EnvironmentKit/`, `SpawnerKit/`, `TimelineKit/`, `SceneCenter/`, `DreamDoorSystem` +- **UI** (Scripts/UI/): `DialogUI/`, `Panel/`, `Form/`, `Components/`, `Cursor/`, `UIManager` +- **MiniGame** (Scripts/MiniGame/): `HuoShan/` (language particles, EmotionWave), `BlockPuzzle/`, `Peipei/` (Eye, CutLine, Memory) +- **FixSystem** (Scripts/FixSystem/): Legacy — HeatMap, PunchTape, Memory, screen effects +- **FixSystemNew** (Scripts/FixSystemNew/): Active repair system — `FixSystemCenter`, `BodyModule/`, `Cable/`, `WhackMole/`, `Screen System/`, `Open/`, `Clinic/` +- **AssetRefs** (Scripts/AssetRefs/): Addressable key constants (`ConstRef`, `FixAssetRef`, `TimelineAssetRef`) + +### Content & Localization + +- **Assets/GameContent/**: Runtime assets by scope (`Common/`, `UI/`, `Scene_{Name}/`, `Feature_{Name}/`) +- **Assets/Language/**: Unity Localization tables (runtime active: `UIText/`, `Locales/`, `Sprite/`; `Dialog/`、`ActorName/`、`Params/` currently kept as migration backups) +- **Assets/Resources/Yarn/**: Current Yarn dialogue files (target migration to `Assets/Narrative/` per spec, not yet complete) +- **Assets/StreamingAssets/Config/**: CSV-driven localized gameplay data (`character.csv` for actor names, `params.csv` for `l10n.*` substitution terms) +- **Assets/Prototype/**: HTML/JS prototypes for mechanic testing + +## Critical Dependencies + +### Unity Packages +- **Yarn Spinner** 3.2.2 (OpenUPM), **Addressables** 1.21.21, **Cinemachine** 2.9.7 +- **URP** 14.0.8, **TextMesh Pro** 3.0.6, **Timeline** 1.7.5, **Localization** 1.4.5 +- **Visual Effect Graph** 14.0.8, **Visual Scripting** 1.8.0 + +### Third-Party +- **FMOD** (audio engine), **DOTween** (tweening), **Shapes** (vector graphics) +- **More Mountains Feedbacks** (game feel), **Destructible 2D** + +## Development Guidelines + +### Code Organization +1. Each major system self-contained in its own folder under `Assets/Scripts/` +2. Kit-pattern utilities in `Framework/` — reusable across systems +3. Singleton pattern for global managers (derived from `SingletonKit`) +4. Favor composition over inheritance +5. All runtime asset loading via `ResourceSystem` — never `Resources.Load` + +### Scene Structure +- Scenes in `Assets/Scenes/`; `Persistence` scene hosts global managers and Persistent Loader +- Fix scenes: `{Character}FixScene` (e.g. `HuoShanFixScene`, `PeipeiFixScene`, `ExpressFixScene`) +- Test scenes: `languageTest`, `HuoShanExpressionTest`, `wavetest`, etc. + +### Addressables +- Config in `Assets/AddressableAssetsData/`; Groups: `Core`, `Scene_*`, `Feature_*`, `Shared_*`, `Localization-*` +- Key format: `Category/Path` (e.g. `Animation/Peipei`, `Timeline/BlockPuzzle/PanelOpen`) +- Scene keys use bare PascalCase names (e.g. `ClinicOut`) +- Details in [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md) + +### Yarn Dialogue Files +- Current path: `Assets/Resources/Yarn/` (migration to `Assets/Narrative/Yarn/` planned) +- Pattern: `{Character}_{Stage}.yarn`; UTF-8 encoding required for Chinese + +#### Yarn Line Tag Maintenance +- **Line tags** (`#line:xxxxxxx`) must be unique across the entire file. Duplicate tags break Yarn Spinner localization. +- Duplicates typically occur when copying an existing node to create a variant (e.g. `地铁ver1` → `地铁ver3`). +- **Use the dedup tool** (`Tools/dedup_yarn_tags.py`) for bulk cleanup: + ```bash + # Preview duplicates from a specific node onward + python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/Fiction_Day1_begin/Fiction_Day1_begin.yarn --from-node 地铁ver4 + # Fix duplicates from a specific line onward + python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/Fiction_Day1_begin/Fiction_Day1_begin.yarn --from-line 535 --fix + # Scan an entire directory (preview only) + python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/ --scan-all + ``` + +#### Yarn Script Generation +- **Do NOT add `#line:` tags when generating or editing Yarn dialogue.** Leave all line-tag generation to the user's localization workflow (Unity Localization + Yarn Spinner import tools). +- When creating new `.yarn` files, write plain dialogue lines without any `#line:` suffixes. + +### Asset Naming +- **Scripts**: PascalCase (e.g. `DialogController.cs`) +- **Addressable Keys**: `Category/Path` — no spaces, no extensions, ≤3 levels +- **Addressable Groups**: `{Type}_{PascalCaseName}` + +### Git & Commits +- LFS for large binaries; ignored: Library/, Temp/, Build/, *.csproj, *.sln +- **Commit format**: `(): ` — subject in Chinese, type/scope in English +- Extended types: `feat`, `fix`, `art`, `audio`, `scene`, `yarn`, `perf`, `refactor`, `style`, `docs`, `build`, `chore`, `test` +- See [COMMIT_CONVENTION.md](COMMIT_CONVENTION.md) for full details + +## Key Build Commands + +```bash +# Windows build +"C:\Program Files\Unity\Hub\Editor\2022.3.7f1c1\Editor\Unity.exe" -batchmode -quit -projectPath . -buildWindows64Player "Build/AIBIS_Dream.exe" -logFile Build/log.txt +``` + +## Common Tasks + +### Adding a New Mini-Game +1. Create `Assets/Scripts/MiniGame/{GameName}/` +2. Add assets to `Assets/GameContent/Feature_{GameName}/` +3. Create Addressable Group `Feature_{GameName}` +4. Create test scene in `Assets/Scenes/` + +### Adding Yarn Dialogue +1. Create `.yarn` in `Assets/Resources/Yarn/{Module}/` +2. Ensure YarnProject localization assets/CSV are updated (Unity `Assets/Language/Dialog/` is backup-only during migration) +3. Reference in scene's `DialogueRunner`; test with `DialogController` + +## Debugging & Performance +- `LogKit` for structured logging; Addressables Event Viewer for resource debugging +- Monitor `SceneResourceLoader.TotalHandleCount` for leak detection +- Always use PoolKit for frequent instantiation; `LoadUncachedAsync` + `EarlyRelease` for large Timeline assets +- Use `LoadAsync` + `Instantiate` for prefabs, never `InstantiateAsync` + +## Important Notes +- Narrative-focused game — dialogue and story take precedence +- `FixSystemNew` is the active repair architecture; `FixSystem` is legacy +- `YarnVariableStorage` holds Yarn runtime variables; save/load flows through `SaveRestoreOrchestrator` and `SaveSystem` + +## Reference Documents +- [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md) — `ResourceSystem` API, Key/Group/Label naming, lifecycle +- [Resource Management Spec](Docs/ResourceManagementSpec.md) — Asset placement: `GameContent/`, `Narrative/`, `_Archive/` +- [Commit Convention](COMMIT_CONVENTION.md) — Commit message format and branch naming +- [HuoShan Docs](Docs/HuoShan/) — Narrative flow, resources, test flowcharts + +--- + +*This document provides guidance for Codex when working with the AIBIS Dream codebase.*