Codebase Documentation Index

Please start here to understand the codebase patterns before making changes.

Introduction

• AI Working Guidelines - Common mistakes, question-asking behavior, documentation practices
• Code Style Guide - Conventions, dependency injection, SerializeField patterns
• Architecture Overview - Three-layer state management, scene architecture

Systems Documentation

System	Description
GameConfigs	Level definitions, difficulty settings, balance
GameRuns	Run lifecycle, state management, WorkDayProgress
HelperCats	Helper cat abilities, deck system, combos
Levels	Level structure, cat spawning, progression
OrderingCats	Customer cats, orders, delivery mechanics
Overworld	Hub world exploration, character controller
SaveLoad	Save/load system, profiles, persistence
Scoring	Score calculation, perfection system, prestige
Shop	Shop UI, results review, shift preparation
Tutorial	Tutorial run system, in-level sequences, dialogue bubbles
DependencyInjection	Init(args) DI framework, service registration, singleton migration
SceneManagement	Multi-scene architecture, scene transitions, initialization
Waves	Wave-based spawning (tutorial and density modes)
Bosses	Boss encounter system, phase/health mechanics, modular UI (designs)
Cutscenes	Cutscene playback, Dialogue System integration, CutsceneDatabase registry, dev tool

Unity Scene Setup

Detailed breakdown of what GameObjects/components go in each scene:

Scene	Description
BootstrapScene	Persistent services (ProfileManager, SaveLoadManager, etc.), loading overlay
GamePlaythroughBaseScene	Playthrough-scoped services (PersistentHelperCatManager, PersistentPlayerProgressionManager)
MainMenuScene	Profile selection, character customization, difficulty selection, game start
GameRunScene	Shop, gameplay, victory/loss, tutorial, cutscenes — all run systems

Folder Structure

Assets/_Game/Scripts/
├── Managers/              # Core managers (GameRunManager, GameRunOrchestrator)
├── Systems/               # Feature systems (preferred location for new code)
│   ├── ActiveHelperCats/  # Active ability system
│   ├── CharacterCustomization/
│   ├── GameConfig/        # Remote config
│   ├── GameFlags/         # Runtime flags
│   ├── Overworld/         # Hub world
│   ├── Perfection/        # Perfection multiplier
│   ├── PrepareForShift/   # Shop substates
│   ├── Progression/       # Campaign structure
│   ├── Bosses/            # Boss encounter system (phases, damage, UI)
│   ├── Spawning/          # Adaptive + wave spawn controllers
│   ├── Tutorial/          # Tutorial run manager, sequences, UI
│   ├── UniqueOrderingCats/
│   └── Upgrades/          # Cake upgrades
├── Cutscene/              # Cutscene system (GameCutscene, CutsceneCat, adapters)
├── Data/                  # ScriptableObjects and data classes
│   ├── Config/            # JSON-loadable configs
│   └── Runtime/           # Runtime data
├── Controllers/           # Input handling
├── Views/                 # UI view components
├── UI/                    # UI managers
└── SceneManagement/       # Scene loading, initialization

Testing

Tests are located in Assets/Tests/:

• CakeUpgradeSystemTest.cs
• ComboSystemTests.cs, CustomComboTests.cs, PatternComboTests.cs
• DatabaseIntegrationTests.cs
• HelperCatsManagerTests.cs

Run via Unity Test Runner (Window → General → Test Runner).

Updating Documentation

When making significant changes to a system, please update the corresponding documentation file. This helps future Claude sessions understand the codebase and maintain consistency.