forked from Shardstone/trail-into-darkness
112 lines
5.7 KiB
Markdown
112 lines
5.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Nox is a Unity 6 RPG game (product name "Nox", Windows build target `Nox.exe`). Party-based gameplay with Addressables for asset management, Newtonsoft JSON for serialization, URP 17.3.0 for rendering, and Unity Input System 1.18.0.
|
|
|
|
## Build & Development
|
|
|
|
- **Unity version**: 6.0.3 (C# 9.0, .NET Framework 4.7.1)
|
|
- **Build output**: `Builds/Nox.exe`
|
|
- **No CI/CD pipeline** — builds are done through Unity Editor
|
|
- **No test suite exists** — `com.unity.test-framework` is in manifest but unused
|
|
- **Scene authoring**: Individual scenes can be played standalone via `SceneReference` component
|
|
|
|
## Architecture
|
|
|
|
### Dual-Layer State Management
|
|
|
|
Two layers of state drive the application:
|
|
|
|
- **Game States** (`IGameState`): Application-level flow — `SplashGameState` → `MainMenuGameState` → `GameModeGameState`
|
|
- Lifecycle: `EnterGameState()` → `Tick()` / `LateTick()` → `ExitGameState()` → `Dispose()`
|
|
- **Play Modes** (`IPlayMode`): Gameplay modes within GameMode — Adventure, Town, Rest, Combat, PauseMenu
|
|
- Lifecycle: `EnterPlayMode()` → `Tick()` / `LateTick()` → `ExitGameMode()` → `Dispose()`
|
|
|
|
`GameModeGameState` bridges these layers, managing play mode transitions and scene loading via Addressables. `GameStateRunner` (MonoBehaviour) drives the update loop and handles fade-in/fade-out transitions via `ISceneTransition`.
|
|
|
|
### Boot Sequence
|
|
|
|
`Boot.cs` (`[RuntimeInitializeOnLoadMethod]`) → loads `"Initializer"` prefab via Addressables → `EntryPoint.cs` (MonoBehaviour) loads all config ScriptableObjects, creates game states, initializes platform subsystems and character systems → `GameStateRunner` begins ticking states.
|
|
|
|
In editor, `Boot.cs` checks `BootMode` preference (Full Boot, Scene Boot, Unity Default).
|
|
|
|
### GameDataState
|
|
|
|
Central state container holding current `GameState`, `PlayMode`, `ActiveParty`, `platformSelector`, `activeSessionId`, and `savedPartyPosition`. State changes via `ChangeGameState()` and `ChangePlayMode()`.
|
|
|
|
### Character System
|
|
|
|
Factory-based architecture with ScriptableObject configuration:
|
|
|
|
```
|
|
DefaultCharacterSystemsFactory.Create()
|
|
├─ PerkFactory (PerkRegistry ScriptableObject)
|
|
├─ CharacterAttributesFactory (validates attributes)
|
|
├─ CharacterStatsFactory (derives stats from attributes)
|
|
├─ CharacterFactory (creates from templates or custom requests)
|
|
└─ PartyFactory (assembles: 1 protagonist + companions)
|
|
```
|
|
|
|
- **Data**: `EntityAttributes` (might, reflex, knowledge, perception) → `EntityStats` (health, stamina, level, experience)
|
|
- **CharacterDefinition**: ID, DisplayName, Attributes, Stats, Race, Class, Role (Protagonist/Companion), Perks, Modifiers
|
|
- **Config ScriptableObjects**: `CharacterBaseSettings`, `PerkRegistry`, `CharacterRegistry`
|
|
- **Key interfaces**: `ICharacterSystems`, `ICharacterFactory`, `IPartyFactory`, `IPerkFactory`
|
|
|
|
### Persistence
|
|
|
|
`GamePersistenceController` + Jovian.SaveSystem with JSON serialization to `Application.persistentDataPath`. Save data model: `NoxSavedDataSet` (activePlayMode, partyDefinition, partyPosition, adventureData). Save slots managed by `SaveSlotManager`.
|
|
|
|
### Platform Abstraction
|
|
|
|
`IPlatform` with `DesktopPlatform` and `UnityEditorPlatform`. Each initializes platform-specific `IInput` (DesktopInput/EditorInput using Unity InputSystem generated code).
|
|
|
|
### Addressables Asset Keys
|
|
|
|
Assets loaded by string key: `"Initializer"`, `"AdventureMapPrefabs"`, `"PauseMenuPrefabs"`, `"AdventureSettings"`, `"CharacterBaseSettings"`, `"PerkRegistry"`, `"CharacterRegistry"`, `"BootstrapReferences"`.
|
|
|
|
### Namespace Convention
|
|
|
|
Namespaces mirror folder structure: `Nox.Core`, `Nox.Game`, `Nox.Input`, `Nox.Platform`, `Nox.Util`.
|
|
|
|
## Code Layout
|
|
|
|
```
|
|
Assets/Code/
|
|
├── Core/ # Boot, EntryPoint, GameStateRunner, IGameState, IPlayMode, GameDataState
|
|
├── GameState/
|
|
│ ├── Camera/ # CameraController, CameraSettings
|
|
│ ├── Entities/ # Character/Party/Perk factories and registries
|
|
│ ├── PlayModes/ # AdventurePlayMode, PauseMenuPlayMode, stubs for Town/Rest/Combat
|
|
│ └── UI/ # View implementations (PauseMenu, Adventure views)
|
|
├── Input/ # IInput abstraction, Desktop/Editor implementations
|
|
├── Platform/ # IPlatform, DesktopPlatform, UnityEditorPlatform
|
|
├── SplashMainMenuUI/
|
|
└── Util/ # BootMode editor utility
|
|
```
|
|
|
|
## C# Style (from .editorconfig)
|
|
|
|
- 4 spaces, LF line endings
|
|
- **`var` preferred** (`csharp_style_var_*: true:suggestion`) — use `var` when type is apparent
|
|
- **Target-typed `new`** when type is evident (`CharacterDefinition c = new()`)
|
|
- **No space after keywords** in control flow (`if(`, `for(`, not `if (`)
|
|
- **Opening braces on same line** (`csharp_new_line_before_open_brace = none`)
|
|
- **`else`/`catch`/`finally` on new line** after closing brace
|
|
- Block-scoped namespaces (`namespace Foo { ... }`)
|
|
- Always use braces (`csharp_prefer_braces = true`)
|
|
- Naming: PascalCase for types/methods/properties, camelCase for all fields (public and private), `I` prefix for interfaces
|
|
- Expression-bodied: yes for properties/accessors/indexers/lambdas; no for constructors/methods/operators/local functions
|
|
- No `this.` qualifier
|
|
- Use language keywords over BCL types (`int` not `Int32`)
|
|
|
|
## Patterns
|
|
|
|
- Constructor-based dependency injection (no DI container)
|
|
- ScriptableObject-based configuration loaded via Addressables
|
|
- Factory pattern for character/party creation
|
|
- Action delegates for UI event communication (e.g., `menuGameStateData.startGameRequests += handler`)
|
|
- Mixed async patterns: both `async Task` and `IEnumerator` coroutines for async operations
|