ArchSurvivor Conventions

MANDATORY: Apply these namespace and architectural rules when creating or modifying code in the ArchSurvivor project.

🗺️ System Map Read

🔴 MANDATORY: Read ARCHITECTURE.md at session start to understand Agents, Skills, and Scripts.

Before coding, answer:

1. •What is the GOAL of this agent/skill?
2. •What PRINCIPLES must I apply?
3. •How does this DIFFER from generic output?

🏗️ Architectural Layers & Namespaces

The project follows a layered architecture. Always use the appropriate namespace based on the file's location.

📂 Folder Structure

Maintain this structure to ensure architectural integrity and AI readability.

Assets/_ArchSurvivor/
├── _Boot/                  # Entry points, ProjectContext, Global Prefabs
├── Application/            # [AsmDef] Interfaces, DTOs, Business Use Cases
├── Core/                   # [AsmDef] Cross-cutting concerns, Utilities (GameLog, ZString)
├── Domain/                 # [AsmDef] Models, Configs (ScriptableObjects), Pure Logic
├── Infrastructure/         # [AsmDef] Implementations of App Interfaces (LocalSave, Audio)
├── Installers/             # VContainer LifetimeScopes (Project, Game)
└── Presentation/           # [AsmDef] MonoBehaviors, Features, UI
    ├── Features/           # Organized by Domain Area (Player, Enemies, World)
    │   └── Player/
    │       ├── Combat/     # HeroCombat, Weapons
    │       ├── FSM/        # State Machine, States
    │       ├── KCC/        # ArchHeroController, Inputs
    │       ├── Logic/      # CharacterFactory, Providers
    │       └── Visuals/    # HeroAnimation, Effects
    ├── Services/           # Presentation-only services (Juice, Flash)
    └── UI/                 # UI Controllers, Views, UXML

📁 Feature-Specific Namespaces

Within the Presentation layer, code is organized by feature. Namespaces MUST strictly match folder hierarchy. Avoid adding redundant sub-namespaces like .Logic if the folder doesn't exist.

Player / Hero Feature

• •Combat: _ArchSurvivor.Presentation.Features.Player.Combat
• •FSM: _ArchSurvivor.Presentation.Features.Player.FSM
• •KCC: _ArchSurvivor.Presentation.Features.Player.KCC
• •Visuals: _ArchSurvivor.Presentation.Features.Player.Visuals
• •Logic: _ArchSurvivor.Presentation.Features.Player.Logic

🔌 Third-Party Integration

💎 SOLID & Senior Code Style

Apply these principles to maintain a 10/10 codebase.

1. S.O.L.I.D. in Unity

• •S (Single Responsibility): Small classes. If a Script has > 300 lines, split it (e.g., move logic to a non-Mono Domain class).
• •O (Open/Closed): Use ScriptableObject configs for data. Add new content by creating assets, not modifying code.
• •L (Liskov Substitution): Interfaces for everything in Application layer.
• •I (Interface Segregation): Tiny interfaces (e.g., IDamageable, IHero).
• •D (Dependency Inversion): MANDATORY VContainer injection. Never use FindObjectOfType or Static singletons.
• •Odin Validation: Use [Required], [AssetsOnly], and [SceneObjectsOnly] for all serialized references.

2. Code Style & Naming

• •Braces: MANDATORY Egyptian style (Opening brace { on the same line).
• •Variables: _camelCase for private fields (with optional _ prefix), PascalCase for public properties/methods.
• •Namespaces: Must match folder structure (e.g., _ArchSurvivor.Presentation.Features.Player).
• •Grouping: Use blank lines to group logical blocks.
• •Null Safety: Use null! for fields assigned via Inspector/DI.
• •Clean Coding: Leverages ValueTask, UniTask, and record for performance.
• •Logging: Always use GameLog.Info/Warning/Error for all Unity components.

🛠️ Common Patterns

Scoped Hero Spawning

When spawning a Hero, always use LifetimeScope.CreateChild to ensure dependencies are properly scoped.

using (VContainer.Unity.LifetimeScope.CreateChild(_objectResolver, builder => {
    builder.RegisterInstance(runtimeData);
})) {
    SetupInjection(runtimeData);
    var go = Object.Instantiate(prefab, position, Quaternion.identity);
    _objectResolver.InjectGameObject(go);
}

DI in FSM

Always import VContainer and use [Inject] for state machine dependencies.

using VContainer;

public class HeroStateMachine : MonoBehaviour {
    [Inject]
    public void Construct(...) { ... }
}