# Technical Preferences

<!-- 由 /setup-engine 填充。随开发决策更新。 -->
<!-- 所有 Agent 引用此文件获取项目标准和规范。 -->

## 引擎与语言

- **引擎**：Unity 6 (6000.3.7f1)
- **语言**：C# (.NET Standard 2.1)
- **渲染管线**：Universal Render Pipeline (URP) 17.3.0
- **物理**：Unity Physics 3D + AI Navigation 2.0.9

## 输入与平台

- **目标平台**：PC (Windows)、主机（PlayStation / Xbox）
- **输入方式**：键鼠 + 手柄（双一等公民）
- **主要输入**：手柄（动作游戏，面向主机）
- **手柄支持**：Full
- **触控支持**：None
- **平台备注**：二次元 3D 动作游戏；战斗对输入响应要求严格。使用 Input System 1.18.0（新版，非 Legacy）。

## 命名规范

- **类名**：PascalCase（如 `CharacterBase`、`CombatManager`、`AttackAreaBase`）
- **变量**：camelCase（字段/局部变量），PascalCase（属性）（如 `currentHealth`、`MaxHealth`）
- **事件**：`On` 前缀 + PascalCase（如 `OnPhaseChanged`、`OnNodeSelected`、`onAttack`、`onGetHit`）
- **文件名**：与类名一致，PascalCase（如 `CharacterBase.cs`、`RunManager.cs`）
- **场景/预制体**：PascalCase 描述性命名（如 `CityArena`、`PlayerCanvas`、`C1_Axe`）
- **常量**：PascalCase 或 UPPER_SNAKE_CASE 视场景而定
- **架构模式**：Submodule（轻量工具）/ Subcontroller（重逻辑）组合模式——避免深层继承。Partial Class 按职责拆分（如 `FutureWand.cs`、`FutureWand_Functions.cs`、`FutureWand_AnimationCallbacks.cs`）。

## 性能预算

- **目标帧率**：60 FPS（主机基线）
- **帧预算**：16.67ms
- **Draw Call**：待定——URP Batching 已启用
- **内存上限**：待定——按平台分析

## 测试

- **框架**：Unity Test Framework 1.6.0
- **最低覆盖**：数值公式、玩法系统
- **必测项**：数值公式、玩法系统

## 禁止模式

- 深层继承链——使用 Submodule/Subcontroller 组合代替
- 在可用 EventSubmodule 事件广播的场景中直接使用 Singleton 访问
- 原生 Unity Audio——所有音频走 Wwise 中间件

## 自有工具库（SLSUtilities 程序集）

> **重要**：以下系统是项目自建的核心工具，非第三方依赖。在涉及 Feedback、动画事件、及通用工具时优先使用这些实现。

- **Feedback 系统** (`Assets/Scripts/SLSUtilities/Feedback/`) — 自研的屏幕反馈框架（Cinemachine 震动、后处理效果、时间缩放等），替代 More Mountains Feel
- **FunctionalAnimation 系统** (`Assets/Scripts/SLSUtilities/FunctionalAnimation/`) — 自研的事件驱动动画框架，通过 FuncAnimPayload 在关键帧执行游戏逻辑
- **其它工具** — SLSUtilities 程序集下的其它通用工具类

## 允许的库 / 插件

### Unity Package（通过 Package Manager）
- Universal Render Pipeline (URP) 17.3.0
- Visual Effect Graph 17.3.0
- Shader Graph 17.3.0
- Timeline 1.8.10
- Input System 1.18.0
- AI Navigation 2.0.9
- Localization 1.5.11
- Burst 1.8.27
- Collections 2.6.2
- Mathematics 1.3.3
- Editor Coroutines 1.0.1

### 第三方（项目内集成）
- **Wwise (Audiokinetic)** — 专业音频中间件（完整项目在 Cielonos_WwiseProject/）
- **Odin Inspector (Sirenix)** — 序列化与编辑器增强
- **DOTween (Demigiant)** — 动画缓动库
- **UniRx** — Unity 响应式扩展
- **Behavior Designer (Opsive)** — AI 行为树框架
- **PotaToon** — 二次元/卡通渲染管线（核心视觉身份）
- **MagicaCloth 2** — 物理布料模拟
- **DamageNumbers Pro** — 浮动伤害数字
- **Yarn Spinner** — 叙事/对话系统（git: YarnSpinnerTool/YarnSpinner-Unity#current）
- **Amplify Shader Editor** — Shader 编辑工具
- **LeanPool** — 对象池优化

### 已弃用（素材保留但不再使用）
- ~~i2 Localization~~ — 已弃用
- ~~LeTai TranslucentImage~~ — 已弃用
- ~~More Mountains Feel~~ — 已弃用，由 SLSUtilities/Feedback 自研系统替代
- ~~Nice Vibrations~~ — 已弃用

### VFX 资源包
- MagicArsenal、Piloto Studio、VFX_Klaus、MasterStylizedFX、MasterStylizedProjectiles、CartoonVFX9X、Hovl Studio、INab Studio、Lana Studio、Vefects、BOXOPHOBIC、Archanor、Ground Impact VFX、HTraceSSGI、EnvironmentWeatherEffect

## Architecture Decisions Log

<!-- 快速引用，链接到 docs/architecture/ 中的完整 ADR -->
- [尚无 ADR — 使用 /architecture-decision 创建]

## 引擎专家路由

- **Primary**：unity-specialist
- **语言/代码专家**：unity-specialist（C# / MonoBehaviour / ScriptableObject 模式）
- **Shader 专家**：unity-shader-specialist（PotaToon、Shader Graph、URP 自定义 Shader）
- **UI 专家**：unity-ui-specialist（UGUI Canvas + UI Toolkit 混合）
- **额外专家**：unity-addressables-specialist（若后续采用 Addressables）
- **路由备注**：本项目使用 URP + PotaToon 实现二次元渲染。战斗系统使用自研 FuncAnim（Functional Animation）事件驱动架构——Shader 工作常与 VFX Feedback 绑定。UI 主要基于 UGUI Canvas，部分界面使用 UI Toolkit。

### 文件扩展名路由

| 文件扩展名 / 类型 | 派发专家 |
|-----------------------|---------------------|
| 游戏代码 (`.cs`) | unity-specialist |
| Shader / 材质文件 (`.shader`, `.shadergraph`, `.mat`) | unity-shader-specialist |
| UI / 界面文件 (`.uxml`, `.uss`, Canvas 预制体) | unity-ui-specialist |
| 场景 / 预制体 / 关卡文件 (`.unity`, `.prefab`) | unity-specialist |
| 原生扩展 / 插件文件 | unity-specialist |
| 总体架构评审 | unity-specialist |