1. 项目概述与核心痛点如果你在Unity里做过编辑器扩展或者开发过需要实时可视化调试的运行时工具那你肯定对Gizmo不陌生。这个“RuntimeSceneGizmo”项目从名字就能看出来它的目标是把编辑器里那个方便我们移动、旋转、缩放物体的Gizmo手柄搬到游戏运行时Runtime里去。听起来是不是挺酷的想象一下你在运行的游戏里可以直接用鼠标拖拽调整一个NPC的位置或者旋转一个场景道具的角度而不用反复暂停、退出、修改预制体、再运行。这对于关卡设计师快速微调、对于策划配置出生点、甚至对于制作一些简易的关卡编辑器来说价值巨大。但理想很丰满现实往往是一地鸡毛。我接手过好几个类似的需求也看过不少社区里开源的Runtime Gizmo实现几乎没有一个能让人省心的。Unity的Gizmo API比如Handles类在设计之初就是为编辑器服务的它在运行时要么直接不可用要么行为诡异。所以自己动手实现一个运行时场景Gizmo本质上是在“重新发明轮子”而且这个轮子还是个精密仪器要处理输入、渲染、空间变换、物体拾取、不同坐标系转换等一系列问题。这也就导致了各种稀奇古怪的问题层出不穷手柄渲染不出来、点击没反应、拖动时物体乱飞、缩放比例不对、在UI上误触发……每一个坑都足以让开发者调试到怀疑人生。这篇文章就是把我这些年踩过的坑、解决的方案系统地梳理出来。我不会给你一个所谓的“完美”代码包因为不同的项目需求差异很大。但我会把核心的实现原理、常见的“坑点”、以及针对性的解决方案讲透。无论你是想自己从头实现一个还是正在调试一个现成的Runtime Gizmo插件相信下面的内容都能给你带来直接的帮助。2. 核心实现思路与方案选型在动手写代码之前我们必须先想清楚几个根本问题这个运行时Gizmo到底要怎么“画”出来用户怎么跟它交互它怎么知道要控制哪个物体2.1 渲染方案的选择GL vs Mesh vs UGUI这是第一个要命的问题。编辑器里的Gizmo是Unity用底层渲染管线直接画的运行时我们没这个权限。主流方案有三种GL API立即模式渲染使用GL类进行绘制。这是最接近编辑器Gizmo感觉的方案代码简洁画线、画三角形非常直接。优点轻量不产生GameObject适合绘制简单的线框手柄比如移动Gizmo的三个箭头。缺点功能有限难以实现复杂的着色效果如光滑的高光更重要的是GL绘制的内容无法被常规的射线检测Raycast拾取这意味着你还需要另一套机制来处理鼠标交互增加了复杂度。适用场景对视觉效果要求不高、且交互逻辑可以自己通过数学计算解决的简单Gizmo。MeshRenderer网格渲染器为每一个Gizmo部件如X轴箭头、Y轴圆环、缩放方块创建一个独立的GameObject挂上MeshFilter和MeshRenderer。优点功能强大可以使用所有Unity的着色器和材质实现精美的视觉效果由于是实体GameObject可以挂载Collider如MeshCollider从而天然支持Unity的物理射线检测交互实现变得简单。缺点会产生多个GameObject管理稍显复杂性能上比GL略差但对于一个Gizmo来说可忽略不计需要自己准备或生成网格模型。适用场景绝大多数情况下的推荐方案。它平衡了效果、交互和开发难度。你可以用简单的立方体、圆柱体组合出手柄并赋予它们半透明、高亮等材质。UGUI / Canvas将Gizmo手柄作为UI元素绘制在世界空间World SpaceCanvas上。优点可以利用UGUI强大的事件系统EventSystem来处理点击、拖拽交互逻辑编写非常方便。缺点UI渲染顺序和3D场景混合可能有问题容易穿帮在世界空间中精确定位和跟随3D物体比较麻烦尤其是当物体旋转缩放时性能上Canvas的DrawCall可能较高。适用场景适合需要与UI系统深度集成或者Gizmo本身就是2D样式的项目。我的选择与理由经过多次实践我强烈推荐MeshRenderer方案。它虽然需要多创建几个GameObject但带来的好处是决定性的交互实现简单靠Collider、视觉效果可控靠Material、与现代渲染管线兼容性好。GL方案在需要复杂交互时会让你痛不欲生而UGUI方案在3D场景中总有种“隔靴搔痒”的不精准感。所以下文的分析和问题解决都将基于MeshRenderer方案展开。2.2 交互逻辑的核心坐标系转换与数学计算即使用MeshRenderer解决了渲染和拾取最核心、也最容易出错的逻辑还在后面当用户拖拽Gizmo的某个部件时如何正确地计算目标物体的位移、旋转或缩放量这里的关键在于理解多个坐标系屏幕坐标系Screen Space鼠标的位置Input.mousePosition原点在左下角。世界坐标系World Space场景中所有物体的绝对坐标。Gizmo本地坐标系Local Space以Gizmo中心为原点的坐标系其轴向与Gizmo自身旋转一致。拖拽计算的通用思路记录初始状态鼠标按下时记录鼠标的屏幕坐标、目标物体的世界位置/旋转/缩放、以及从摄像机到鼠标按下点的射线Ray。构建操作平面对于移动操作通常需要根据拖拽的轴如X轴构建一个操作平面例如垂直于摄像机视角且包含Gizmo X轴的平面。对于旋转则是围绕某个轴旋转。每帧计算偏移量在鼠标拖拽过程中将当前帧的鼠标位置投影到第2步构建的操作平面上得到一个世界空间中的点。用这个点与初始记录的点进行计算得出在世界空间或本地空间下的偏移量Delta。应用变换将这个偏移量应用到目标物体上。这里要特别注意是应用在世界空间还是本地空间这取决于你的设计需求通常移动和缩放在世界空间旋转可能在本地空间。最容易出错的点操作平面的选择如果平面选得不对物体会沿着你不希望的方向移动。例如拖拽X轴手柄时如果平面完全垂直于摄像机在视角倾斜时可能会无法移动。通常的做法是构建一个平面其法线是摄像机看向方向与拖拽轴方向的叉积这样能保证拖拽始终在屏幕的可感知方向上。深度Z值问题将屏幕坐标只有X, Y转换回世界坐标时需要一个深度值。这个深度值通常取自鼠标按下时射线击中的那个点Gizmo手柄上的点的Z值。如果深度值获取不准投影点就会飘忽不定。本地与世界的混淆直接使用鼠标偏移的屏幕像素差乘以某个系数来移动物体这是绝对错误的必须经过上述的“屏幕→世界”投影计算。3. 常见问题与实战解决方案下面我们就进入实战环节看看那些让你头疼的报错和诡异现象到底该怎么解决。3.1 问题一Gizmo手柄渲染不出来或闪烁现象在Game视图里Gizmo时隐时现或者根本看不见。排查与解决检查Layer和Camera Culling Mask这是最常见的原因你的Gizmo手柄GameObject所在的Layer必须被主摄像机或你用来渲染场景的摄像机的Culling Mask包含。专门为Gizmo创建一个Layer如“Gizmo”并把摄像机的Culling Mask勾选上这个Layer。检查材质和Shader你使用的材质球是否支持当前渲染管线Built-in, URP, HDRP在URP/HDRP下使用Built-in的标准Shader可能会不显示。确保使用对应渲染管线的Unlit或Simple Lit Shader并且渲染队列Render Queue设置为Transparent或Geometry1以上以避免被不透明物体遮挡。检查MeshRenderer组件的启用状态确保脚本在正确时机如选中物体后启用了MeshRenderer而不是在Awake/Start中启用一次后就再也不管了。深度测试Z-Test/Z-Fight问题如果Gizmo和场景物体距离太近可能会产生深度冲突导致闪烁。在材质Shader中可以尝试调整ZWrite深度写入和ZTest深度测试模式。对于始终显示在最前面的Gizmo可以设置ZWrite Off和ZTest Always。// 示例一个简单的半透明Gizmo材质Shader (Built-in) 关键部分 SubShader { Tags { QueueTransparent RenderTypeTransparent } Blend SrcAlpha OneMinusSrcAlpha ZWrite Off // 关闭深度写入避免遮挡问题 ZTest LEqual // 或 Always取决于需求 ... }渲染顺序问题如果有多个透明Gizmo部件可能会因为渲染顺序导致异常。确保它们的渲染队列一致。3.2 问题二鼠标点击Gizmo没反应无法拾取现象鼠标移到Gizmo手柄上没变化点击也无法开始拖拽。排查与解决确认Collider存在且启用为每个Gizmo手柄部件MeshRenderer所在的GameObject添加并启用一个ColliderBoxCollider, MeshCollider等。检查Collider的isTrigger属性根据你的射线检测代码决定是否勾选如果使用Physics.Raycast且不检测触发器就不要勾选。检查射线检测的LayerMask你的射线检测代码Physics.Raycast的layerMask参数必须包含Gizmo对象所在的Layer。和渲染问题一样建议使用专用Layer。int gizmoLayerMask 1 LayerMask.NameToLayer(Gizmo); Ray ray Camera.main.ScreenPointToRay(Input.mousePosition); RaycastHit hit; if (Physics.Raycast(ray, out hit, Mathf.Infinity, gizmoLayerMask)) { // 命中Gizmo部件 GameObject hitGizmoPart hit.collider.gameObject; }检查射线检测的时机和距离确保射线检测在每帧如Update中执行并且最大距离maxDistance设置得足够大例如Mathf.Infinity。事件系统冲突如果你的场景中有EventSystemUGUI并且使用了Standalone Input Module它可能会“吃掉”鼠标点击事件。确保你的Gizmo交互脚本在Update中直接使用Input.GetMouseButtonDown等接口而不是依赖于UGUI的事件。或者你可以通过EventSystem.current.IsPointerOverGameObject()来判断鼠标是否在UI上如果是则忽略Gizmo操作。Collider大小和位置检查Collider是否太小或者位置偏移了导致鼠标实际上点不中。可以在编辑模式下将Collider显示出来Gizmos菜单里勾选Colliders进行观察。3.3 问题三拖拽时物体运动不稳定、抖动或乱飞现象拖动Gizmo手柄时目标物体不是平滑移动而是跳变、抖动或者朝完全错误的方向飞速移动。排查与解决深度值Z值获取不准确这是导致抖动的头号元凶。在鼠标按下时你通过射线检测得到了一个碰撞点hit.point。这个点的Z值在世界空间中的深度应该被记录下来用于后续将鼠标位置投影到操作平面上。务必使用这个hit.point来构造初始的投影点而不是使用目标物体的位置或其他任意值。private Vector3 m_initialHitPointWorld; // 记录按下时命中点的世界坐标 private Plane m_dragPlane; // 操作平面 void OnGizmoPartPressed(RaycastHit hit) { m_initialHitPointWorld hit.point; // 假设是沿X轴移动构建一个平面其法线为摄像机右方向与X轴方向的叉积简化逻辑实际更复杂 Vector3 planeNormal Vector3.Cross(Camera.main.transform.right, transform.right).normalized; m_dragPlane new Plane(planeNormal, m_initialHitPointWorld); }操作平面构建错误如上节所述平面的构建需要根据拖拽轴和摄像机方向精心计算。一个经典的方案是对于轴向移动如拖拽X轴箭头操作平面应包含该轴并且法线垂直于该轴和摄像机看向方向的叉积向量这样能保证拖拽在屏幕空间中是沿该轴方向。// 以拖拽X轴为例更健壮的操作平面构建 Vector3 axis transform.right; // Gizmo的X轴世界空间 Vector3 cameraForward Camera.main.transform.forward; // 计算平面法线避免与轴平行 Vector3 planeNormal Vector3.Cross(axis, cameraForward); if (planeNormal.sqrMagnitude 0.001f) { // 如果轴和摄像机方向几乎平行则用摄像机的上方向作为备选 planeNormal Vector3.Cross(axis, Camera.main.transform.up); } planeNormal.Normalize(); m_dragPlane new Plane(planeNormal, m_initialHitPointWorld);每帧的投影计算在拖拽过程中Update里需要将当前鼠标位置投影到m_dragPlane上。void DuringDrag() { Ray ray Camera.main.ScreenPointToRay(Input.mousePosition); float enter 0f; if (m_dragPlane.Raycast(ray, out enter)) { Vector3 currentHitPointWorld ray.GetPoint(enter); Vector3 worldDelta currentHitPointWorld - m_initialHitPointWorld; // 现在worldDelta是鼠标在操作平面上拖动的世界空间偏移 // 但我们需要的是沿Gizmo X轴的偏移量 float movementOnAxis Vector3.Dot(worldDelta, transform.right); Vector3 translation transform.right * movementOnAxis; targetObject.position translation; // 同时更新初始点为下一帧计算增量做准备或者使用累加模式 // m_initialHitPointWorld currentHitPointWorld; // 增量模式 } }帧率与Time.deltaTime如果你的移动计算直接使用了每帧的偏移量并且没有考虑帧率那么在帧率波动时就会产生速度不均的感觉。但请注意对于基于位置的直接拖拽如鼠标拖动物体到某处我们通常不乘以Time.deltaTime因为偏移量本身就是“距离”而不是“速度”。乘以Time.deltaTime反而会导致移动距离与鼠标拖动距离不匹配。抖动通常源于计算错误而非帧率。父级变换的影响如果目标物体或Gizmo本身有非均匀缩放的父节点世界坐标与本地坐标的转换会变得极其复杂。一个简单的规避方法是在操作期间确保Gizmo和目标物体都处于没有复杂父级变换的环境中例如临时放到根节点下操作完成后再归位。但这实现起来很麻烦。更务实的做法是在计算中全程使用世界空间坐标并谨慎处理旋转和缩放。3.4 问题四缩放或旋转Gizmo时中心点不对现象使用缩放Gizmo时物体不是以自身中心点缩放或者旋转Gizmo不是围绕自身中心旋转。排查与解决Gizmo的Pivot轴心点确保Gizmo空对象的轴心点Pivot与目标物体的轴心点或你希望的操作中心在世界空间中对齐。这通常在每帧Update中完成void Update() { if (targetObject ! null) { transform.position targetObject.position; transform.rotation targetObject.rotation; // 对于旋转和缩放Gizmo可能需要这个 } }缩放的计算缩放操作通常通过拖拽一个位于轴末端的方块来实现。计算缩放比例时需要基于从操作中心Gizmo位置到初始拖拽点的方向和距离。记录初始拖拽点时同时记录从Gizmo中心到该点的向量initialOffset。拖拽过程中计算当前鼠标投影点到Gizmo中心的向量currentOffset。缩放比例可以是currentOffset.magnitude / initialOffset.magnitude均匀缩放或者分别计算各轴分量比非均匀缩放。关键应用缩放时要使用targetObject.localScale initialScale * scaleFactor;直接修改localScale而不是累加以避免误差积累。旋转的计算旋转操作通常围绕一个轴进行。计算旋转角度需要一些向量数学。构建一个以Gizmo中心为原点、旋转轴为法线的平面。将初始拖拽点和当前拖拽点投影到这个平面上得到两个平面向量fromVector和toVector。计算这两个向量之间的夹角使用Vector3.SignedAngle并指定旋转轴以确定正负。将计算出的角度应用到目标物体的旋转上。// 围绕Y轴旋转的简化示例 Plane rotationPlane new Plane(Vector3.up, transform.position); // ... 投影得到 fromVec 和 toVec (在平面上的向量) float angle Vector3.SignedAngle(fromVec, toVec, Vector3.up); targetObject.Rotate(Vector3.up, angle, Space.World); // 或者Space.Self3.5 问题五与UI如UGUI的点击冲突现象当Gizmo画在UI按钮前面时点击按钮却触发了Gizmo的拖拽。解决方案在Gizmo交互前进行UI检测在尝试用射线检测Gizmo之前先判断鼠标是否在UI上。using UnityEngine.EventSystems; bool IsPointerOverUI() { // 检查是否有EventSystem且鼠标是否在UI上 if (EventSystem.current ! null EventSystem.current.IsPointerOverGameObject()) { return true; } return false; } void Update() { if (Input.GetMouseButtonDown(0)) { if (IsPointerOverUI()) { return; // 点在UI上不处理Gizmo } // 否则进行Gizmo的射线检测... } }为UI Canvas设置更高的Sorting Order或Render Mode如果Gizmo是使用UGUI绘制的确保交互性UI的Canvas位于更上层更高的Sort Order。对于世界空间的UI可能需要调整渲染顺序。物理射线检测的优先级确保你的Gizmo射线检测只针对Gizmo所在的Layer而UI通常在不同的Layer如“UI”这样即使射线穿过了UI也不会检测到Gizmo因为LayerMask不匹配。但这种方法不够彻底因为UI可能阻挡了射线。3.6 问题六性能问题与多物体选择现象当场景中有大量物体或同时需要显示多个Gizmo时帧率下降。优化建议按需渲染只在物体被选中或需要交互时才实例化并显示Gizmo。在物体取消选中时销毁或禁用Gizmo对象。使用对象池如果频繁切换选中对象可以为Gizmo的各个部件箭头、圆环等创建简单的对象池避免频繁的Instantiate和Destroy。简化网格和材质Gizmo手柄的网格面数尽可能低。使用共享材质Shared Material以减少Draw Call。合并绘制调用高级如果使用GL方案本身绘制调用就少。如果使用Mesh方案可以考虑将静态的、不交互的Gizmo部件合并成一个Mesh但这会使得交互处理变复杂。多物体选择支持如果需要同时操作多个物体Gizmo应显示在这些物体的包围盒中心Bounds Center。所有变换操作移动、旋转、缩放都应基于这个中心点来计算然后同步应用到每一个选中的物体上。计算包围盒中心时注意要使用物体的世界坐标顶点来计算而不是简单的位置平均这样更准确。4. 进阶技巧与设计模式解决了基本问题后我们可以考虑让Runtime Gizmo变得更强大、更好用。4.1 视觉反馈与状态管理一个好的Gizmo应该有清晰的视觉反馈悬停高亮当鼠标悬停在某个可交互部件上时该部件应高亮如改变材质颜色。选中状态当前正在拖拽的部件应有不同的颜色。禁用状态对于不可操作如被锁定的轴可以显示为灰色。实现这些可以通过在射线检测到悬停或按下时切换对应部件MeshRenderer的材质来实现。可以预先准备几套材质正常、高亮、激活。4.2 坐标系切换世界/本地像Unity编辑器一样提供世界坐标系World和本地坐标系Local的切换功能。世界坐标系Gizmo的轴向始终与世界坐标轴X-红Y-绿Z-蓝对齐。本地坐标系Gizmo的轴向与目标物体自身的旋转对齐即其Transform的right, up, forward方向。 实现起来很简单在更新Gizmo朝向时根据当前模式选择不同的旋转void UpdateGizmoTransform() { transform.position targetObject.position; if (coordinateMode CoordinateMode.World) { transform.rotation Quaternion.identity; // 世界坐标无旋转 } else if (coordinateMode CoordinateMode.Local) { transform.rotation targetObject.rotation; // 本地坐标与目标一致 } }4.3 吸附功能Snapping这是提升效率的利器。在拖拽移动、旋转或缩放时可以按住某个键如Ctrl启用吸附。移动吸附将移动的增量舍入到指定步长如1单位的倍数。float snappedValue Mathf.Round(delta / gridSize) * gridSize;旋转吸附将旋转角度舍入到指定度数如15度的倍数。缩放吸附将缩放比例舍入到指定步长的倍数。 实现时在计算出的最终变换值上应用这个舍入操作即可。4.4 输入封装与可配置性不要将输入逻辑Input.GetMouseButton和核心变换计算硬编码在一起。考虑将输入抽象成一个IInputProvider接口这样可以在PC鼠标、触摸屏触摸、甚至VR控制器之间切换。同样Gizmo的样式、颜色、尺寸等都应该做成可配置的通过一个配置文件或ScriptableObject来管理便于美术和策划调整。5. 调试与问题排查清单当你的Runtime Gizmo行为异常时可以按照以下清单快速排查现象可能原因检查点完全不显示1. 摄像机未渲染Gizmo层2. 材质Shader不兼容当前渲染管线3. MeshRenderer被禁用1. 检查Camera的Culling Mask和Gizmo对象的Layer。2. 在Game视图的Stats面板查看Draw Calls确认是否有渲染。3. 检查材质球在相应管线下的表现。点击无反应1. Collider未添加/未启用2. 射线检测LayerMask不匹配3. 被UI或其它Collider阻挡1. 在Scene视图勾选显示Collider。2. 调试输出射线检测的hit.collider信息。3. 使用Debug.DrawRay绘制射线查看路径。拖拽时抖动1. 操作平面构建错误2. 深度(Z)值计算不准3. 变换应用在了错误的坐标系1. 在拖拽时用Debug.DrawLine画出操作平面法线。2. 检查记录和投影用的hit.point是否准确。3. 确认是对position还是localPosition进行操作。旋转/缩放中心不对1. Gizmo的Pivot未与目标中心对齐2. 缩放计算未以中心为原点1. 在Update中确保transform.position target.position。2. 调试输出计算缩放比例时用的向量。与UI冲突1. 未检测鼠标是否在UI上2. UI Canvas阻挡了射线1. 添加EventSystem.current.IsPointerOverGameObject()判断。2. 确保UI和Gizmo在不同Layer且射线检测屏蔽UI层。性能低下1. 未销毁闲置Gizmo2. 网格或材质过于复杂1. 使用对象池管理Gizmo实例。2. 简化Gizmo部件的网格使用低面数模型。实现一个稳定、好用的Runtime Scene Gizmo绝非易事它涉及图形渲染、输入处理、3D数学和软件设计多个方面。最关键的体会是不要试图一次性搞定所有功能。先从最简单的单轴移动开始确保渲染、拾取、拖拽计算这一条链路完全跑通并且理解其中每一个步骤的数学意义。然后再逐步加入旋转、缩放、多坐标系、吸附等高级功能。每增加一个功能都可能引入新的问题耐心调试并用可视化调试工具Debug.DrawLine,Debug.DrawRay来辅助你理解空间关系。当你最终把它打磨顺手看到策划和美术能流畅地在运行时布置场景时那种成就感会让你觉得所有的折腾都是值得的。