# unity_framework **Repository Path**: Raindrips/unity_framework ## Basic Information - **Project Name**: unity_framework - **Description**: unity 通用接口代码组件 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-24 - **Last Updated**: 2026-07-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Unity Game Core 一个基于 Unity 2022.3 LTS 的可复用 C# 游戏框架，提供模块化的事件系统、状态机、行为树、物理检测、寻路、对象池等功能。 ## 概述 本框架以**本地 UPM 包**（`com.unity_framework`）的形式设计，可嵌入任何 Unity 项目。所有系统基于 `GameCore` 命名空间，解耦且经过实战验证。 ## 环境要求 - Unity 2022.3.x LTS - Input System 1.14.2+ - TextMesh Pro 3.0.7+ ## 安装方式 在项目的 `Packages/manifest.json` 中添加本地包引用： ```json "com.unity_framework": "file:../package_my/unity_framework" ``` 或将 `unity_framework` 文件夹直接复制到项目的 `Packages/` 目录下。 ## 模块一览 ### Core — 纯逻辑层，无 Unity 依赖 | 模块 | 说明 | | ------------------------- | --------------------------------------------------------------------------- | | `Core/Event/` | 静态泛型事件总线（`EventManager`）— 基于类型的发布/订阅，无需继承 | | `Core/ServiceLocator/` | 泛型依赖注入 / 服务定位器（`Register` / `Resolve` / `Unregister`） | | `Core/BehaviorTree/` | 行为树核心节点 — 组合节点、装饰节点、叶子节点（纯 C#） | | `Core/StateMachine/` | 状态机核心 — 条件、转换、层级、构建器（纯 C#） | | `Core/SortArray/` | 泛型排序数组 | ### Utils — 静态 Unity 工具类 | 模块 | 说明 | | ------------------------- | ------------------------------------------------- | | `Utils/GameObjectUtils` | 静态 GameObject 创建辅助方法 | | `Utils/TagExtensions` | GameObject 标签操作扩展方法 | | `Utils/TagQuery` | 静态标签查询工具（FindWithTag、FindInRadius 等） | | `Utils/AStarPathfinder` | 静态 A* 寻路算法 | ### Utilities — 非静态 Unity 封装 | 模块 | 说明 | | ----------------------------- | --------------------------------------------------------------------------------- | | `Utilities/Singleton` | 泛型 MonoBehaviour 单例 — 懒加载、自动创建 GameObject、DontDestroyOnLoad | | `Utilities/AStarGrid` | A* 网格地图，支持障碍物烘焙 | | `Utilities/AStarNode` | A* 寻路节点数据 | | `Utilities/GridCanvas` | 纯色网格画布 — 引擎无关的像素缓冲区，提供 `SetCell`、`Clear`、`FillRect` 等方法 | | `Utilities/TransformUtils` | Transform 辅助方法（LookAt 等） | | `Utilities/WorldDrawing` | 3D 世界空间绘制组件 | | `Utilities/NormalVisualizer` | Scene 视图地面法线可视化 | | `Utilities/GlobalMethodInvoker` | 基于反射的全局方法调用器 | | `Utilities/DraggableSprite` | 2D 精灵拖拽组件 | ### Manager — 单例管理器 | 模块 | 说明 | | ------------------------- | ----------------------------------------------------------------------------- | | `Manager/Audio/` | 音频管理器单例 | | `Manager/Pool/` | 对象池 — 主动 `ObjectPool` + 被动 `PassiveObjectPool` | | `Manager/TagManager/` | 多标签系统 — 基于 HashSet 的 O(1) 查询，自定义 Inspector，支持 AND/OR 过滤 | | `Manager/FrameSync/` | 确定性帧同步（`SimpleFrameManager`、`SimpleRecorder`） | | `Manager/UI/` | 简易 UI 管理器 | ### Module — 复合功能集合 | 模块 | 说明 | | ----------------------------------------- | ----------------------------------------------------------------------- | | `Module/Framework/Save/` | JSON 存档/读档系统（`SaveManager` + `ISaveable` 接口） | | `Module/Framework/Replay/` | 命令模式 + 回放系统（`CommandExecutor`、`ICommand`、`ReplayManager`） | | `Module/Framework/Network/` | 网络抽象层（`NetworkManager`、`INetworkSync`） | | `Module/Gameplay/Pathfinding/` | A* 寻路瓦片数据组件 | | `Module/Gameplay/BehaviorTree/Core/` | 行为树核心节点 — 组合、装饰、叶子（纯 C#） | | `Module/Gameplay/BehaviorTree/Runtime/` | 行为树 MonoBehaviour 驱动封装 | | `Module/Gameplay/BehaviorTree/Example/` | 行为树使用示例 | | `Module/Gameplay/StateMachine/Core/` | 状态机核心 — 条件、转换、层级、构建器（纯 C#） | | `Module/Gameplay/StateMachine/Runtime/` | 状态机 MonoBehaviour 封装 + ScriptableObject 定义 | | `Module/Gameplay/StateMachine/Example/` | 状态机使用示例 | | `Module/Gameplay/StateMachine/Editor/` | 状态机调试窗口 | | `UI/` | UI 窗口系统 — 层级管理、模态阻断、过渡动画、对象池 | | `UI/Core/` | UIManager、LayerManager、ModalManager、WindowManager、BaseWindow、WindowConfig | | `UI/Transition/` | 过渡系统 — IUITransition、FadeTransition、NoopTransition | | `UI/Example/` | 示例窗口（Settings、ConfirmDialog）+ 自动引导 | ### Component — MonoBehaviour 组件 | 模块 | 说明 | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `Component/Physics/Cast/` | 3D 物理检测器 — Raycast、BoxCast、SphereCast、CapsuleCast、OverlapBox、OverlapSphere、OverlapCapsule | | `Component/Physics/Cast2D/` | 2D 物理检测器 — Raycast2D、BoxCast2D、CircleCast2D、CapsuleCast2D、OverlapBox2D、OverlapCircle2D 等 | | `Component/Physics/RTSRaycastDetection` | RTS 风格鼠标点击和框选射线检测 | | `Component/CameraFreeMove` | 自由视角摄像机控制器（WSAD + 鼠标） | | `Component/UniqueID` | 基于 GUID 的唯一标识符 | | `Component/Ticker` | 基于 Tick 的计时器组件 | | `Component/PoolableObject` | 销毁时自动归还到对象池 | | `Component/TagComponent` | 每个 GameObject 的标签存储 | | `Component/GridDisplay` | 通过 Texture2D + RawImage 渲染 `GridCanvas` | | `Component/GridRendererExample` | 网格渲染器示例（A*、生命游戏、贪吃蛇） | ## 核心模式 ### 事件系统 ```csharp // 订阅事件 EventManager.On(data => Debug.Log(data.Message)); // 发布事件 EventManager.Publish(new MyEvent { Message = "Hello" }); ``` ### 服务定位器 ```csharp // 注册服务 ServiceLocator.Register(new MyService()); // 获取服务 var service = ServiceLocator.Resolve(); ``` ### 单例模式 ```csharp public class GameManager : Singleton { public void DoSomething() { } } // 在任何地方访问 GameManager.Instance.DoSomething(); ``` ### 对象池 ```csharp // 从池中获取 var obj = ObjectPool.Instance.Get(prefab, position, rotation); // 归还到池中 ObjectPool.Instance.Return(obj); ``` ### UI 窗口系统 ```csharp // 打开窗口 UIManager.Instance.Open("Settings"); // 带参数打开 UIManager.Instance.Open("Confirm", new ConfirmDialogData { title = "确认", message = "确定要执行此操作吗？", callback = (yes) => Debug.Log(yes) }); // 关闭窗口 UIManager.Instance.Close("Settings"); // 带淡入淡出过渡关闭 UIManager.Instance.CloseWithTransition("Settings", TransitionType.Fade, 0.3f); // 检查窗口状态 bool isOpen = UIManager.Instance.IsOpen("Settings"); ``` ### 网格渲染器 ```csharp // 初始化（通过 GridDisplay 组件或直接使用 GridCanvas） var canvas = new GridCanvas(columns: 40, rows: 30, cellSize: 16, spacing: 1); // 设置单元格颜色 canvas.SetCell(5, 10, new Color32(255, 0, 0, 255)); // 批量操作 canvas.Clear(new Color32(20, 20, 30, 255)); canvas.FillRect(0, 0, 10, 10, new Color32(0, 255, 0, 255)); canvas.DrawLine(0, 0, 20, 15, new Color32(255, 255, 0, 255)); canvas.DrawRect(5, 5, 20, 15, new Color32(255, 255, 255, 255)); // 刷新到显示器（Unity） display.Flush(); ``` ## 命名空间 | 命名空间 | 作用域 | | ------------------------- | ------------------------------------------------------- | | `GameCore` | 根命名空间 — 工具类（`Singleton`、`GlobalMethodInvoker`）| | `GameCore.Events` | 静态事件总线 | | `GameCore.GridRenderer` | 网格画布与显示 | | `GameCore.UI` | UI 窗口系统（层级、过渡、模态、对象池） | | `GameCore.Managers` | 管理器（Audio、Tag、Pool、FrameSync、UI） | | `Project.Core` | 服务定位器 | | `Project.Save` | 存档/读档系统 | | `Project.Replay` | 命令模式 + 回放 | | `Project.Network` | 网络抽象层 | ## 项目结构 ``` unity_framework/ ├── Core/ # 纯逻辑层，无 Unity 依赖 │ ├── Event/ # 静态事件总线 │ ├── ServiceLocator/ # 依赖注入 / 服务定位器 │ ├── BehaviorTree/ # 行为树核心 │ ├── StateMachine/ # 状态机核心 │ └── SortArray/ # 泛型排序数组 ├── Utils/ # 静态 Unity 工具类 │ ├── GameObjectUtils.cs │ ├── TagExtensions.cs │ ├── TagQuery.cs │ └── AStarPathfinder.cs ├── Utilities/ # 非静态 Unity 封装 │ ├── Singleton.cs │ ├── AStarGrid.cs, AStarNode.cs │ ├── GridCanvas.cs │ ├── TransformUtils.cs, WorldDrawing.cs │ ├── NormalVisualizer.cs, GlobalMethodInvoker.cs │ └── DraggableSprite.cs ├── UI/ # UI 窗口系统 │ ├── Core/ # UIManager, WindowManager, LayerManager, ModalManager │ ├── Transition/ # FadeTransition, NoopTransition, TransitionManager │ └── Example/ # SettingsWindow, ConfirmDialog, ExampleUI, UIBootstrap ├── Manager/ # 单例管理器 │ ├── Audio/ │ ├── FrameSync/ │ ├── Pool/ │ ├── TagManager/ │ └── UI/ ├── Module/ # 复合功能集合 │ ├── Framework/ │ │ ├── Save/ # SaveManager + ISaveable 接口 │ │ ├── Replay/ # CommandExecutor + ICommand + ReplayManager │ │ └── Network/ # NetworkManager + INetworkSync │ └── Gameplay/ │ ├── Pathfinding/ │ ├── BehaviorTree/ │ │ ├── Core/ # BTree, Node, INode, Composite, Decorator, Leaf │ │ ├── Runtime/ # BehaviorTreeComponent MonoBehaviour 封装 │ │ └── Example/ # BTExample 使用示例 │ └── StateMachine/ │ ├── Core/ # StateMachineCore, Builder, Conditions, Transitions │ ├── Runtime/ # StateMachineComponent, StateMachineDefinition │ ├── Example/ # CharacterAnimationSM, ActionGameCharacter │ └── Editor/ # StateMachineDebugger └── Component/ # MonoBehaviour 组件 ├── Physics/Cast/ # 3D 物理检测器 ├── Physics/Cast2D/ # 2D 物理检测器 ├── CameraFreeMove.cs, UniqueID.cs, Ticker.cs ├── PoolableObject.cs, TagComponent.cs └── GridDisplay.cs, GridRendererExample.cs ``` ## 许可证 此代码可自由使用和修改。