Cielonos/.claude/docs/technical-preferences.md

Technical Preferences

引擎与语言

• 引擎：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

• [尚无 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