From d1ed43cdf080ace0f444641e4392ba4a60cdd11f Mon Sep 17 00:00:00 2001 From: gitee-bot Date: Sun, 8 Feb 2026 07:48:43 +0000 Subject: [PATCH] Add README.md --- README.en.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 README.en.md create mode 100644 README.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..e822304 --- /dev/null +++ b/README.en.md @@ -0,0 +1,91 @@ +# XFramework Skill System (Unity Skill Editor) + +This is a visual skill editor and runtime core library built on Unity. It provides a complete Gameplay Ability System (GAS) solution, encompassing the full workflow from visual skill editing to runtime execution. + +## Core Features + +1. **Visual Skill Editor**: + * Node-based editing interface built on Unity's `GraphView`. + * Supports visual editing of Ability nodes, Task nodes, Effect nodes, Condition nodes, and Cue nodes. + * **Animation Timeline**: Integrated Spine animation preview and skill timeline editing, allowing precise control over the timing of visual effects and logic triggers within the editor. + +2. **Complete Runtime Core**: + * **GAS Architecture**: Implements `AbilitySystemComponent`, `GameplayAbilitySpec`, and `GameplayEffectSpec`, supporting skill authorization, activation, cooldown, cost consumption, and effect management. + * **Attribute System**: A flexible numerical calculation system supporting base values, current values, modifiers, snapshot capture, and multiple aggregation modes. + * **Gameplay Tags System**: Hierarchical tag management for handling state, permission, and filtering logic. + +3. **Rich Skill Component Library**: + * **Effects**: Damage, Heal, Buff/Debuff, Cooldown, Cost, Displace, Projectile, Placement, etc. + * **Cues**: Particle effects, Sound effects, Floating Text/Damage Numbers. + * **Tasks**: Search Target, End Ability. + * **Conditions**: Attribute Comparison. + +4. **Runtime Dependencies**: + * **Targeting**: Supports various range search algorithms including circular, conical, and linear. + * **Formula System**: Built-in formula parser supporting complex damage/healing calculation formulas. + +## Directory Structure + +Project code resides under the `Assets/SkillEditor` directory and is primarily divided into three parts: + +### 1. Data (Data Definitions) +Defines all data structures, enums, and configurations used in the editor. +* **`Data/Base/`**: Core data structures (`NodeData`, `SkillGraphData`) and enums (`NodeType`, `EffectDurationType`, etc.). +* **`Data/Ability/`**: Ability node data (`AbilityNodeData`). +* **`Data/Effect/`**: Data definitions for various effects (`DamageEffectNodeData`, `BuffEffectNodeData`, etc.). +* **`Data/Task/`**: Task node data (`AnimationNodeData`, `SearchTargetTaskNodeData`). +* **`Data/Attribute/`**: Core classes for the attribute system (`Attribute`, `AttributeModifier`, `AttributeSetContainer`) and execution logic. +* **`Data/Tags/`**: Definitions and containers for gameplay tags. + +### 2. Editor (Editor Interface) +Implements Unity editor extensions responsible for skill editing, previewing, and management. +* **`Editor/SkillEditorWindow.cs`**: Main window of the skill editor. +* **`Editor/Base/GraphView/`**: Graph view controls, node creation, and serialization logic. +* **`Editor/Base/Node/`**: Visual classes for all nodes (e.g., `AbilityNode`, `DamageEffectNode`), defining node appearance and input/output ports in the editor. +* **`Editor/Base/Inspector/`**: Node property panels displaying detailed configurations when a node is selected. +* **`Editor/Task/Animation/`**: **Animation Timeline component**, including `TimelineView` and `SpinePreviewRenderer` for visual editing of animation frames and trigger points. +* **`Editor/Tags/`**: Independent `GameplayTagsEditorWindow` for managing the gameplay tag tree. + +### 3. Runtime (Runtime Core) +These scripts are packaged for use in the final game runtime. +* **`Runtime/Core/`**: Core architecture (`AbilitySystemComponent`, `GASHost` lifecycle management, `SpecExecutionContext` execution context). +* **`Runtime/Ability/`**: Skill authorization (`AbilityContainer`) and activation state management (`GameplayAbilitySpec`). +* **`Runtime/Effect/`**: Runtime execution logic for various effects (`DamageEffectSpec`, `BuffEffectSpec`, `ProjectileEffectSpec`). +* **`Runtime/Target/`**: Target search algorithms (`TargetSearcher`). +* **`Runtime/Cue/`**: Runtime management of visual/audio feedback (`GameplayCueManager`, `FloatingTextManager`). +* **`Runtime/Utils/`**: Utility tools including formula parser (`FormulaEvaluator`) and timer (`GASTimer`). + +## Quick Start + +### 1. Open the Editor +Click **Tools -> Skill Editor** in the Unity menu bar to open the skill editor window. + +### 2. Create a Skill +1. Right-click in the left asset tree and select **Create -> SkillFile** (or create a ScriptableObject under `Assets/SkillEditor/Resources/SkillAsset`). +2. Double-click the `.asset` file to open it; the graph view will load automatically. +3. Right-click an empty area in the graph and select a node from the **Create Node** menu. + +### 3. Core Node Usage Workflow +A typical skill usually includes the following nodes: +* **Ability (Skill Root Node)**: Defines skill ID, required tags, and costs. +* **Animation (Animation Node)**: Plays the skill animation. +* **Task -> Search Target**: Finds targets based on shape (circular, conical, etc.). +* **Effect -> Damage**: Deals damage to the targeted entities. +* **Effect -> Buff**: Applies a status effect to the target. + +### 4. Run Tests +The project includes built-in test scenes and examples. +* Refer to `Assets/SkillEditor/Runtime/Test/README.md` for detailed testing methods and preset skill configurations. +* Skill activation can be tested via the **UI interface**, **editor menu**, or **in-scene units (Boss/Player)**. + +## Attributes and Formulas + +This system supports complex numerical calculations: +* **Fixed Value**: Fixed numeric value. +* **Formula**: Mathematical formula expressed as a string (supports addition, subtraction, multiplication, division, parentheses, and `Attri.attributeName` references). +* **MMC (Modifier Magnitude Calculation)**: Calculates coefficients via attribute capture (e.g., Damage = Attack * Coefficient). + +## Notes +* This framework requires **Unity 2019.4** or higher. +* Editor code runs only in development mode and does not increase the size of the final build. +* Ensure **TextMeshPro** is installed in your project to support floating text UI functionality. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..dded537 --- /dev/null +++ b/README.md @@ -0,0 +1,90 @@ + + +# XFramework Skill System (Unity技能编辑器) + +这是一个基于 Unity 的可视化技能编辑器及运行时核心库。它提供了一套完整的 Gameplay Ability System (GAS) 解决方案，包含了从技能可视化编辑到运行时执行的完整工作流。 + +## 核心特性 + +1. **可视化技能编辑器**： + * 基于 Unity `GraphView` 的节点式编辑界面。 + * 支持技能节点（Ability）、任务节点（Task）、效果节点（Effect）、条件节点（Condition）和提示节点（Cue）的可视化编辑。 + * **动画时间轴**：集成了 Spine 动画预览和技能时间轴编辑，支持在编辑器中精确控制特效和逻辑的触发时间。 +2. **完整的运行时核心 (Runtime Core)**： + * **GAS 架构**：实现了 `AbilitySystemComponent`、`GameplayAbilitySpec` 和 `GameplayEffectSpec`，支持技能的授权、激活、冷却、消耗和效果管理。 + * **属性系统 (Attribute System)**：灵活的数值计算系统，支持基础值、当前值、修改器（Modifiers）、快照捕获以及多种聚合模式。 + * **标签系统 (Gameplay Tags)**：层级化的标签管理，用于处理状态、权限和过滤逻辑。 +3. **丰富的技能组件库**： + * **效果 (Effects)**：伤害 (Damage)、治疗 (Heal)、Buff/DEBuff (Buff)、冷却 (Cooldown)、消耗 (Cost)、位移 (Displace)、投射物 (Projectile)、放置物 (Placement) 等。 + * **提示 (Cues)**：粒子特效 (Particle)、音效 (Sound)、飘字 (Floating Text/Damage Number)。 + * **任务 (Tasks)**：搜索目标 (Search Target)、结束技能 (End Ability)。 + * **条件 (Conditions)**：属性比较 (Attribute Comparison)。 +4. **运行时依赖**： + * **目标搜索 (Targeting)**：支持圆形、扇形、线性等多种范围搜索算法。 + * **公式系统**：内置公式解析器，支持复杂的伤害/治疗数值计算公式。 + +## 目录结构 + +项目代码位于 `Assets/SkillEditor` 目录下，主要分为三大部分： + +### 1. Data (数据定义) +定义了编辑器中使用的所有数据结构、枚举和配置。 +* **`Data/Base/`**: 核心数据结构（`NodeData`, `SkillGraphData`）和枚举（`NodeType`, `EffectDurationType` 等）。 +* **`Data/Ability/`**: 技能节点数据（`AbilityNodeData`）。 +* **`Data/Effect/`**: 各种效果的数据定义（`DamageEffectNodeData`, `BuffEffectNodeData` 等）。 +* **`Data/Task/`**: 任务节点数据（`AnimationNodeData`, `SearchTargetTaskNodeData`）。 +* **`Data/Attribute/`**: 属性系统的核心类（`Attribute`, `AttributeModifier`, `AttributeSetContainer`）以及执行计算逻辑。 +* **`Data/Tags/`**: 游戏标签的定义和容器。 + +### 2. Editor (编辑器界面) +实现了 Unity 编辑器扩展，负责技能的编辑、预览和管理。 +* **`Editor/SkillEditorWindow.cs`**: 技能编辑器的主窗口。 +* **`Editor/Base/GraphView/`**: 技能图谱的视图控制、节点创建和序列化逻辑。 +* **`Editor/Base/Node/`**: 所有节点的可视化类（如 `AbilityNode`, `DamageEffectNode`），定义了节点在编辑器中的外观和输入输出端口。 +* **`Editor/Base/Inspector/`**: 节点属性面板，当选中节点时显示详细配置。 +* **`Editor/Task/Animation/`**: **动画时间轴组件**，包含 `TimelineView` 和 `SpinePreviewRenderer`，用于可视化编辑动画帧和触发点。 +* **`Editor/Tags/`**: 独立的 `GameplayTagsEditorWindow`，用于管理游戏标签树。 + +### 3. Runtime (运行时核心) +这些脚本被打包后用于最终的游戏运行时。 +* **`Runtime/Core/`**: 核心架构（`AbilitySystemComponent`, `GASHost` 生命周期管理, `SpecExecutionContext` 执行上下文）。 +* **`Runtime/Ability/`**: 技能授权（`AbilityContainer`）和激活状态管理（`GameplayAbilitySpec`）。 +* **`Runtime/Effect/`**: 各种效果的运行时执行逻辑（`DamageEffectSpec`, `BuffEffectSpec`, `ProjectileEffectSpec`）。 +* **`Runtime/Target/`**: 目标搜索算法（`TargetSearcher`）。 +* **`Runtime/Cue/`**: 视觉/听觉反馈的运行时管理（`GameplayCueManager`, `FloatingTextManager`）。 +* **`Runtime/Utils/`**: 辅助工具，包括公式解析器（`FormulaEvaluator`）和计时器（`GASTimer`）。 + +## 快速开始 + +### 1. 打开编辑器 +在 Unity 菜单栏中点击 **Tools -> Skill Editor** 即可打开技能编辑器窗口。 + +### 2. 创建技能 +1. 在左侧资源树中右键选择 **Create -> SkillFile** (或在 `Assets/SkillEditor/Resources/SkillAsset` 下创建 ScriptableObject)。 +2. 双击打开 `.asset` 文件，图谱视图会自动加载。 +3. 右键图谱空白处，在 **Create Node** 菜单中选择节点。 + +### 3. 核心节点使用流程 +一个典型的技能通常包含以下节点： +* **Ability (技能根节点)**：定义技能 ID、所需标签和消耗。 +* **Animation (动画节点)**：播放技能动作。 +* **Task -> Search Target (搜索目标)**：根据形状（圆形、扇形等）查找目标。 +* **Effect -> Damage (伤害效果)**：对搜索到的目标造成伤害。 +* **Effect -> Buff (Buff效果)**：为目标添加状态。 + +### 4. 运行测试 +项目内置了测试场景和用例。 +* 请参考 `Assets/SkillEditor/Runtime/Test/README.md` 了解详细的测试方法和预设技能配置。 +* 可以通过 **UI 界面**、**编辑器菜单** 或 **场景内的单位 (Boss/Player)** 进行技能释放测试。 + +## 属性与公式 + +该系统支持复杂的数值计算： +* **Fixed Value**: 固定数值。 +* **Formula**: 字符串形式的数学公式（支持加减乘除、括号和 `Attri.attributeName` 引用）。 +* **MMC (Modifier Magnitude Calculation)**: 通过属性捕获计算系数（例如：伤害 = 攻击力 * 系数）。 + +## 注意事项 +* 此框架需要 **Unity 2019.4** 或更高版本。 +* 编辑器部分代码仅在开发环境下运行，不会增加发布包的大小。 +* 确保项目中已安装 **TextMeshPro** 以支持 UI 飘字功能。 \ No newline at end of file -- Gitee