From 3918fbce98442fecfb022d81cf1de100e46ad220 Mon Sep 17 00:00:00 2001 From: Ding Yuntian <1491671119@qq.com> Date: Wed, 15 Apr 2026 22:23:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20CLAUDE.md=20?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 231 ++++++++++++++++++++---------------------------------- 1 file changed, 86 insertions(+), 145 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 59a1a5017..7fec583c3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,192 +1,133 @@ -# CLAUDE.md +# CLAUDE.md This file provides guidance to Claude Code (claude.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 (notably the HuoShan/Volcano language particle system). +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:** Unity 2022.3.x LTS (Universal Render Pipeline) +**Unity Version:** 2022.3.7f1c1 (Universal Render Pipeline) ## Architecture ### Core Framework (Assets/Scripts/Framework/) -The project uses a custom modular framework with these key systems: +Modular framework with Kit-pattern utilities: -- **ActionKit**: Action sequencing and command pattern implementation -- **AudioKit**: Audio management and sound effect system -- **Config**: Game configuration and settings management -- **Core**: Core game systems and utilities -- **EventSystemKit**: Decoupled event system for inter-system communication -- **PoolKit**: Object pooling for performance optimization -- **ResourceKit**: Asset loading and resource management - - **Note**: New code should use `ResourceSystem` (via Addressables), see [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) for details. **Where assets live on disk** (e.g. `GameContent/`, `Narrative/`) is defined in [Resource Management Spec](Docs/ResourceManagementSpec.md). -- **SingletonKit**: Singleton base classes for managers -- **StateMachineKit**: Game state management -- **TimelineKit**: Timeline-based event sequencing +- **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 -- **Dialog System** (Assets/Scripts/Dialog System/): Yarn Spinner integration for narrative flow -- **Clue System** (Assets/Scripts/Clue/): Investigation and evidence collection mechanics -- **MiniGame System** (Assets/Scripts/MiniGame/): Modular mini-game framework - - **HuoShan** (Volcano): Language particle system for emotional expression gameplay -- **SceneManagement**: Scene flow control and transitions -- **FixSystem**: Interactive repair/puzzle mechanics +- **Game Loop** (Scripts/Game Loop/): `GameManager` (Singleton entry), `StorageSystem` (save + Yarn variables), `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`) -### Web Prototypes +### Content & Localization -Located in `web-prototype/` and `WebPrototype/` directories, these contain HTML/JavaScript prototypes for testing game mechanics before Unity implementation. - -## Key Development Commands - -### Unity Build Process - -```bash -# Build for Windows (64-bit) -"C:\Program Files\Unity\Hub\Editor\2022.3.x\Editor\Unity.exe" -batchmode -quit -projectPath . -buildWindows64Player "Build/AIBIS_Dream.exe" -logFile Build/log.txt - -# Build for WebGL -"C:\Program Files\Unity\Hub\Editor\2022.3.x\Editor\Unity.exe" -batchmode -quit -projectPath . -executeMethod BuildScript.WebGL -logFile Build/webgl_log.txt -``` - -### Asset Import and Generation - -```bash -# Regenerate solution files (Visual Studio) -Assets\Open C# Project.regenerate-sln.bat - -# Refresh asset database -# (Use Unity Editor menu: Assets > Refresh or Ctrl+R) -``` +- **Assets/GameContent/**: Runtime assets by scope (`Common/`, `UI/`, `Scene_{Name}/`, `Feature_{Name}/`) +- **Assets/Language/**: Unity Localization tables (`Dialog/`, `ActorName/`, `UIText/`, `Locales/`, `Sprite/`) +- **Assets/Resources/Yarn/**: Current Yarn dialogue files (target migration to `Assets/Narrative/` per spec, not yet complete) +- **Assets/Prototype/**: HTML/JS prototypes for mechanic testing ## Critical Dependencies -### Unity Packages (via Package Manager) -- **Yarn Spinner**: Dialogue system (dev.yarnspinner.unity) -- **TextMesh Pro**: Text rendering and typography -- **Universal Render Pipeline**: Graphics rendering -- **2D Animation**: Sprite-based animation tools -- **Cinemachine**: Camera system -- **Timeline**: Cinematic sequencing -- **Localization**: Multi-language support +### Unity Packages +- **Yarn Spinner** 2.4.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 Assets -- **More Mountains Feedbacks**: Game feel and feedback system -- **FMOD**: Advanced audio engine -- **DOTween**: Tweening and animation -- **Shapes**: Vector graphics and shapes rendering -- **Destructible 2D**: 2D destruction mechanics +### Third-Party +- **FMOD** (audio engine), **DOTween** (tweening), **Shapes** (vector graphics) +- **More Mountains Feedbacks** (game feel), **Destructible 2D** ## Development Guidelines ### Code Organization - -1. **Modular Systems**: Each major system should be self-contained in its own folder under `Assets/Scripts/` -2. **Kit Pattern**: Reusable utilities go in `Framework/` with "Kit" suffix -3. **Manager Classes**: Use Singleton pattern for global managers (derived from `SingletonKit`) -4. **Component Design**: Favor composition over inheritance for game objects +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. -- Scenes are located in `Assets/Scenes/` -- Main scenes use naming convention: `{Character}_{Day}{Time}` (e.g., `Fiction_Day1_begin`) -- Mini-game scenes start with prefix: `HuoShan*`, `languageTest*`, etc. -- Always configure scenes in `EditorBuildSettings` for proper loading +### 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 -Target layout and co-location with Dialog localization tables: [Resource Management Spec](Docs/ResourceManagementSpec.md) (`Assets/Narrative/Yarn/`, `Assets/Narrative/Localization/`). Legacy paths may still include `Assets/Resources/Yarn/` during migration. +### Asset Naming +- **Scripts**: PascalCase (e.g. `DialogController.cs`) +- **Addressable Keys**: `Category/Path` — no spaces, no extensions, ≤3 levels +- **Addressable Groups**: `{Type}_{PascalCaseName}` -Convention for file naming and UTF-8: -- Organize by narrative module / character and day as the project requires -- Files often follow pattern: `{Character}_{Stage}.yarn` -- Use UTF-8 encoding for Chinese text support +### 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 -### Asset Naming Conventions +## Key Build Commands -- **Scripts**: PascalCase with component purpose (e.g., `DialogController.cs`) -- **Prefabs**: PascalCase with type suffix (e.g., `ClueItem.prefab`) -- **Scenes**: Snake_Case with descriptive names -- **Resources**: Organize by system/type in `Assets/Resources/` +```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 +``` -## Important Configuration - -### Editor Settings -- **Text Encoding**: All text files must use UTF-8 (especially for Chinese) -- **Line Endings**: Windows (CRLF) for C# files, but be consistent -- **Visual Studio**: Use provided `.sln` and `.csproj` files - -### Build Settings -- **Target Platform**: Primarily Windows and WebGL -- **Scripting Backend**: IL2CPP for Windows, Emscripten for WebGL -- **API Compatibility**: .NET Standard 2.1 - -### Git Configuration -- **LFS**: Used for large binary assets (.unity, textures, audio) -- **Ignored**: Library/, Temp/, Logs/, Build/, *.csproj.user -- **Commit Convention**: See [COMMIT_CONVENTION.md](COMMIT_CONVENTION.md) for commit message format and branch naming rules. All commits must follow `(): ` format. - -## Testing and Iteration - -### Running Individual Mini-Games - -Most mini-genes can be tested independently by opening their specific scene: -- HuoShan Language Game: `Assets/Scenes/languageTest.unity` -- HuoShan Fix Scene: `Assets/Scenes/HuoShanFixScene.unity` -- Expression Test: `Assets/Scenes/HuoShanExpressionTest.unity` - -### Web Prototyping - -For testing mechanics before Unity implementation: -1. Create HTML/JS prototype in `web-prototype/` -2. Use similar logic to planned Unity implementation -3. Test in browser for rapid iteration - -## Common Development Tasks +## Common Tasks ### Adding a New Mini-Game - -1. Create folder in `Assets/Scripts/MiniGame/{GameName}/` -2. Implement game logic using Framework kits -3. Create test scene in `Assets/Scenes/{GameName}Test.unity` -4. Add required assets to `Assets/Resources/{GameName}/` -5. Document in `README_{GameName}.md` +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. Add Dialog string tables in `Assets/Language/Dialog/` +3. Reference in scene's `DialogueRunner`; test with `DialogController` -1. Create `.yarn` file in appropriate `Assets/Resources/Yarn/{Character}/` folder -2. Add file to Resources using Unity's `Resources.Load` system -3. Reference in scene's `DialogueRunner` component -4. Test with `DialogueController` - -### Debugging Tips - -- Use `LogKit` for consistent logging with categories -- Enable verbose logging in `ProjectSettings/LogKit` -- Use Unity's frame debugger for rendering issues -- Profile with Unity Profiler, especially for mini-games with many particles - -## Performance Considerations - -- **Pooling**: Always use PoolKit for frequently instantiated objects (particles, UI elements) -- **Asset Loading**: Use ResourceKit for async loading to avoid frame drops. - See [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) for detailed specifications including Group/Key/Label naming and preloading strategies. -- **Particle Systems**: Pool particle systems, limit overdraw in language particle game -- **Audio**: Use object pooling for frequent SFX, FMOD for advanced audio +## 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 - -- This is a narrative-focused game - ensure dialogue and story take precedence -- The HuoShan language particle system is a core feature - changes should maintain the emotional expression mechanics -- Web prototypes are for testing only - production code must be in Unity/C# +- Narrative-focused game — dialogue and story take precedence +- `FixSystemNew` is the active repair architecture; `FixSystem` is legacy +- `StorageSystem` serves as both save system and Yarn variable storage ## Reference Documents - -- [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) - How to load assets: `ResourceSystem`, Addressables Key/Group/Label, lifecycle and performance -- [Resource Management Spec](Docs/ResourceManagementSpec.md) - Where to place assets: `GameContent/`, `Narrative/` (Yarn + Dialog tables), `_Archive/`, and exceptions (distinct from loading mechanics above) -- [Commit Convention](COMMIT_CONVENTION.md) - Git commit message format and branch naming rules +- [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 ---