aibis-dream/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 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. Asset placement rules in Resource Management Spec.
• 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), 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)

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 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

• 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

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:

  # 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: <type>(<scope>): <subject> — 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 for full details

Key Build Commands

# 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<GameObject> + Instantiate for prefabs, never InstantiateAsync

Important Notes

• 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 — ResourceSystem API, Key/Group/Label naming, lifecycle
• Resource Management Spec — Asset placement: GameContent/, Narrative/, _Archive/
• Commit Convention — Commit message format and branch naming
• HuoShan Docs — Narrative flow, resources, test flowcharts

---

This document provides guidance for Claude Code when working with the AIBIS Dream codebase.