QFramework实现类幸存者文字飘字系统：对象池与UI坐标转换全解析

在类幸存者项目的表现层里“飘字”是一个很典型但又容易做砸的功能。玩家打死一只怪掉出伤害数字玩家被包围身上不断飘出受击提示拾取经验石时屏幕上一排 1 2 的反馈。文字飘动支持这个需求看似只是把 Text 换个位置、调个透明度但一旦放进 QFramework 这种带架构约束的项目里就会牵扯出对象池、System、UI 坐标转换、文本生命周期管理等一系列问题。本文围绕 QFramework 游戏开发专门拆解类幸存者项目中的文字飘动支持方案。我会从需求定位、架构设计、组件实现、对象池封装、System 接入、战斗流程接入、参数配置到常见问题完整写一套可以直接抄走的实现。适合已经在用 QFramework 搭项目或者正想在独立游戏里做飘字系统的开发者。1. 文字飘动功能在类幸存者项目中的定位1.1 为什么需要文字飘动早期原型阶段很多开发者在敌人死亡位置直接Instantiate一个 Text两三行代码就实现飘字。项目一旦进入复杂战斗这种写法会很快失控。类幸存者游戏的最大特点是“单位数量多、战斗节奏快、持续十几分钟”。一把刷下来玩家可能会打出几百上千次伤害产生大量短生命周期的 UI 对象。如果每次伤害都创建新 Text场景里会瞬时堆积几十个甚至上百个 UI 节点Canvas 的顶点重建压力会直接反映到帧率上。文字飘动支持如果只是“能显示”那很容易如果要做到“掉帧不明显、内存不持续上涨、代码可维护”就必须从架构层面认真设计。飘字在游戏里承担的是“战斗反馈”职责。它让每一次伤害、暴击、治疗、拾取、闪避都能被玩家看见。对类幸存者这种割草玩法来说飘字不只是装饰它还在帮助玩家理解当前 Build 的输出强度、技能触发频率和敌人血量变化。所以飘字的实现质量直接影响手感。1.2 飘字系统在整个架构中的位置在 QFramework 架构里飘字功能不应该散落在各个MonoBehaviour中。更合理的做法是把它收敛成一个System对外提供统一的飘字接口比如ShowDamageText、ShowPickupText。战斗逻辑不关心文字是向上飘还是向左飘也不关心用了什么字体、什么颜色它只需要告诉系统“这里发生了一次数值变化请显示出来”。这种分层思路的核心是伤害计算是逻辑层的事飘字展示是表现层的事。两者通过接口或事件解耦。QFramework 的ISystem正好适合承载这类表现层能力因为 System 可以注册到架构中也可以被任意Command、Controller获取调用路径短、依赖清晰。1.3 实现目标一套完整的文字飘动支持至少需要满足下面几点支持伤害数字、暴击数字、治疗数字等多种文本类型。文字有上浮、淡出、缩放等基础动画。能复用对象不能每次创建新 GameObject。不受世界观坐标和 UI 坐标差异影响任意 3D 点位都能正确显示在 UI 上。对外调用简单业务方不需要知道内部实现。有了明确目标下面就能逐个模块去落地。2. QFramework 下飘字系统的设计思路2.1 用 System 承载飘字逻辑QFramework 提供ISystem、IController、ICommand、IQuery等架构元素。飘字属于系统级能力它需要被多个模块调用比如玩家攻击脚本、敌人受伤脚本、拾取物脚本。如果用 Controller 去实现就意味着多个模块都要持有同一个 Controller耦合会很奇怪。用 System 则没有这个问题System 注册在架构里任何地方通过GetSystemT()就能拿到单例实例。飘字 System 的职责边界要控制好。它只负责“接收一个文本内容 一个世界坐标 一组表现参数”然后创建或复用飘字节点播放表现最后回收节点。它不关心伤害公式也不关心敌人是不是要掉血。2.2 对象池解决频繁生成问题频繁创建和销毁 UI 节点是飘字功能最大的性能隐患。虽然 Unity 的Instantiate和Destroy在低频率下开销可接受但类幸存者里每秒可能出现几十次命中反馈每一次都走完整生命周期就会产生大量 GC 和 Canvas 重建。解决方案是对象池。预先创建一批飘字节点使用时从池中取出播放完再还回池中。对象池的粒度以单个飘字节点为单位池子内部维护一个栈或队列取节点时从栈顶 Pop回收时压回栈顶。对象池设计得好飘字节点数量可以达到动态平衡不会随战斗时长无限增长。2.3 数据流设计飘字的数据流可以这样设计战斗逻辑计算伤害得到伤害数值和命中点世界坐标。逻辑层调用FloatTextSystem.ShowDamageText。FloatTextSystem从对象池取一个飘字节点。将世界坐标转为 UI 局部坐标设置文本和颜色。飘字节点自己播放上浮和淡出动画。动画结束后节点通过事件通知 System 将其回收。这个流程里最容易被忽略的是“坐标转换”。3D 游戏的世界坐标和 UI 坐标是两个坐标系直接赋值会导致文字位置偏移或用默认坐标堆在角落。所以 System 内部必须做一次WorldToScreenPoint和ScreenPointToLocalPointInRectangle转换。3. 环境准备与项目结构3.1 环境说明本文的代码示例以常见的 Unity 开发环境为准UI 部分使用 UGUI 和 TextMeshPro。QFramework 的 API 以 0.10 系列为参考包括ArchitectureT、AbstractSystem、GetSystemT等。不同小版本之间可能存在命名空间或接口细节差异请以项目实际引用的 QFramework 源码为准。如果你还没有把项目接入 QFramework需要先通过 Package Manager 或直接拷贝源码的方式导入 QFramework并在项目里建一个继承ArchitectureT的入口类。下面所有代码都基于这个架构入口。3.2 项目目录为了让代码结构清晰建议把飘字相关脚本单独放在一个目录下Assets/ └── Scripts/ ├── Architecture/ │ └── ClassSurvivorArchitecture.cs ├── Gameplay/ │ ├── IDamageable.cs │ └── MeleeWeapon.cs └── UI/ ├── FloatText/ │ ├── FloatTextConfig.cs │ ├── FloatTextController.cs │ ├── FloatTextPool.cs │ └── FloatTextSystem.cs └── Resources/ └── FloatTextConfig.assetFloatTextSystem虽然放在Gameplay或UI都能用但我更推荐放在UI/FloatText下因为它在职责上属于 UI 表现层只是通过 QFramework 注册为全局 System。3.3 TextMeshPro 环境检查TextMeshPro 是 Unity 官方 UI 文本解决方案默认集成在 Unity 中。使用时需要导入基础资源也就是 TMP Essential Resources。如果项目里创建 TextMeshPro 文本时提示导入点击导入即可。飘字使用TextMeshProUGUI注意和旧版Text组件区分开。TMP 的字体、渲染和性能都比旧版 Text 好尤其适合频繁复用的飘字节点。4. FloatText 节点组件实现4.1 组件职责一个飘字节点本身是一个普通的 UI GameObject挂上RectTransform、TextMeshProUGUI、CanvasGroup和一个控制脚本。控制脚本只负责飘字节点的自身表现设置文本、设置颜色、播放动画、在结束时发出回收信号。它不关心自己来自哪里、回收到哪里。我把这个控制脚本命名为FloatTextController。它内部会保存开始时间、持续时间、上浮速度、淡出延迟等参数并通过Update()逐帧更新位置和透明度。4.2 核心字段FloatTextController的核心字段如下using System; using TMPro; using UnityEngine; namespace QFGame.ClassSurvivor.UI { public class FloatTextController : MonoBehaviour { [SerializeField] private TextMeshProUGUI text; [SerializeField] private CanvasGroup canvasGroup; private float currentTime; private bool isPlaying; // 表现参数 private float duration 0.6f; private float upSpeed 90f; private float fadeDelay 0.15f; private Color textColor Color.white; public event ActionFloatTextController OnComplete; ... } }这里的CanvasGroup用来控制整个节点的淡出而不是单独控制text.color.a。原因是实际项目中飘字节点上可能还会挂图标、描边、阴影等子节点统一控制CanvasGroup.alpha可以一次影响所有子节点表现更完整。4.3 飘动与淡出逻辑Setup方法负责接收外部传入的文本内容、颜色和表现参数。每次从对象池取出节点时都会重新调用一次Setup确保上一次的状态不会残留。public void Setup( string content, Color color, float duration 0.6f, float upSpeed 90f, float fadeDelay 0.15f) { this.duration duration; this.upSpeed upSpeed; this.fadeDelay fadeDelay; this.textColor color; currentTime 0f; isPlaying true; text.text content; text.color color; canvasGroup.alpha 1f; }Update中按照帧率累加时间并同时在垂直方向移动位置和淡出透明度。这里的fadeDelay是淡出延迟表示文字先保持一小段时间完全不透明再进入淡出阶段。视觉上比从一开始就淡出更有“弹出来”的感觉。private void Update() { if (!isPlaying) return; currentTime Time.deltaTime; if (currentTime duration) { isPlaying false; OnComplete?.Invoke(this); return; } transform.localPosition Vector3.up * (upSpeed * Time.deltaTime); if (currentTime fadeDelay) { float fadeDuration duration - fadeDelay; float fadeT (currentTime - fadeDelay) / Mathf.Max(0.01f, fadeDuration); canvasGroup.alpha Mathf.Lerp(1f, 0f, Mathf.Clamp01(fadeT)); } }这里有一个细节我用了Vector3.up * (upSpeed * Time.deltaTime)而不是直接设置localPosition的 y 值原因是直接设置会覆盖外部设置好的初始位置。每次在当前位置基础上向上累加可以让节点从初始点平滑上升。另外动画结束后立即触发OnComplete外部对象池收到这个事件后会把节点回收到池中。节点自己不直接调用Destroy这是对象池设计的关键。5. GameObject 对象池封装5.1 为什么不用 Instantiate 直接创建如果直接使用Instantiate最直观的问题是 GC 压力。每次Instantiate要创建托管对象、加载材质实例、布局 UI都会产生临时内存分配每次Destroy也不是立即释放而是要等待帧末。在类幸存者场景中大量敌人同时死亡时会爆发式创建飘字很容易卡顿。对象池直接把节点数量控制在一个较小的动态范围内。即使战斗再激烈池中的活跃节点数也基本等于“同一屏最大可见飘字数”不会再向上增长到离谱的量级。5.2 Pool 实现这里实现一个简单的FloatTextPool内部使用StackFloatTextController保存空闲节点。预创建一部分节点避免第一次使用时卡顿。using System.Collections.Generic; using UnityEngine; namespace QFGame.ClassSurvivor.UI { public class FloatTextPool { private readonly StackFloatTextController freePool new StackFloatTextController(); private readonly Transform parent; private readonly FloatTextController prefab; public FloatTextPool(FloatTextController prefab, Transform parent, int preloadCount) { this.prefab prefab; this.parent parent; for (int i 0; i preloadCount; i) { FloatTextController item Object.Instantiate(prefab, parent); item.ResetState(); item.gameObject.SetActive(false); freePool.Push(item); } } public FloatTextController Get() { FloatTextController item; if (freePool.Count 0) { item freePool.Pop(); } else { item Object.Instantiate(prefab, parent); } item.gameObject.SetActive(true); item.ResetState(); return item; } public void Free(FloatTextController item) { if (item null) return; item.ResetState(); item.gameObject.SetActive(false); if (!freePool.Contains(item)) { freePool.Push(item); } } } }FloatTextController需要提供ResetState方法把文本、透明度、位置和时间统一重置。只有状态完全重置节点才会在下次使用时表现出全新状态。public void ResetState() { currentTime 0f; isPlaying false; text.text string.Empty; text.color Color.white; canvasGroup.alpha 1f; transform.localPosition Vector3.zero; }5.3 生命周期的释放池本身不负责Destroy。如果游戏场景切换整个父节点被销毁池中所有节点也一并销毁这不会有内存泄漏。需要注意的是如果使用DontDestroyOnLoad的 Canvas那么切场景时池中的节点会继续存在需要在切换场景时主动清空池子。这里不展开实际项目按场景管理策略处理即可。6. FloatTextSystem 接入 QFramework6.1 ISystem 实现在 QFramework 中飘字系统继承AbstractSystem并重写OnInit做初始化。AbstractSystem是 QFramework 提供的基础 System 基类它有OnInit生命周期并且注册到架构后可以通过GetSystemT()获取。using UnityEngine; using QF; using QFGame.ClassSurvivor.UI; namespace QFGame.ClassSurvivor { public class FloatTextSystem : AbstractSystem { private FloatTextPool pool; private RectTransform containerRect; private Canvas canvas; private Camera worldCamera; private FloatTextConfig config; protected override void OnInit() { config Resources.LoadFloatTextConfig(FloatTextConfig); if (config null) { Debug.LogError(FloatTextConfig not found in Resources.); return; } pool new FloatTextPool(config.Prefab, config.Container, config.PreloadCount); containerRect config.Container; canvas config.Container.GetComponentCanvas(); worldCamera Camera.main; } ... } }这里的FloatTextConfig是 ScriptableObject 配置用来保存飘字预制体、挂载容器、预创建数量这些编辑器参数。通过Resources.Load加载可以减少硬编码。6.2 坐标转换与展示接口ShowDamageText是对外最常用的接口。它接收一个 3D 世界坐标、一段文本和一个颜色然后内部完成坐标转换、取对象、设置参数和监听完成事件。public void ShowDamageText(Vector3 worldPos, string content, Color color) { if (pool null || canvas null) return; Vector2 screenPos RectTransformUtility.WorldToScreenPoint(worldCamera, worldPos); Vector2 localPos; Camera uiCamera canvas.renderMode RenderMode.ScreenSpaceOverlay ? null : canvas.worldCamera; RectTransformUtility.ScreenPointToLocalPointInRectangle( containerRect, screenPos, uiCamera, out localPos); FloatTextController item pool.Get(); item.transform.SetParent(containerRect, false); item.transform.localPosition localPos config.Offset; item.Setup(content, color, config.Duration, config.UpSpeed, config.FadeDelay); item.OnComplete OnFloatTextComplete; } private void OnFloatTextComplete(FloatTextController item) { if (item null) return; item.OnComplete - OnFloatTextComplete; pool.Free(item); }这里要注意RectTransformUtility.WorldToScreenPoint的第一个相机参数。当 Canvas 是ScreenSpaceOverlay模式时世界坐标到屏幕坐标的转换不需要 UI 相机而当 Canvas 是ScreenSpaceCamera模式时需要传入 UI 相机。我在代码里根据canvas.renderMode动态判断这样两种模式都能适配。6.3 注册到架构有了FloatTextSystem还需要在架构入口类中注册。假设你的类幸存者架构入口叫ClassSurvivorArchitectureusing QF; namespace QFGame.ClassSurvivor { public class ClassSurvivorArchitecture : ArchitectureClassSurvivorArchitecture { protected override void Init() { RegisterSystemFloatTextSystem(new FloatTextSystem()); } } public static class ClassSurvivorGame { public static IArchitecture Interface new ClassSurvivorArchitecture(); } }业务方调用时只需要写一行ClassSurvivorGame.Interface .GetSystemFloatTextSystem() .ShowDamageText(hitPoint, -100, Color.yellow);外部完全不需要知道对象池、坐标转换这些细节。7. 在类幸存者战斗流程中接入7.1 伤害事件的产生类幸存者战斗流程通常是这样的玩家或者自动武器碰到敌人调用IDamageable.TakeDamage计算伤害然后根据结果播放各种表现。飘字属于命中表现的一部分逻辑上应该在伤害计算完成后触发。一个简单的伤害接口可以这样定义namespace QFGame.ClassSurvivor { public interface IDamageable { float TakeDamage(float damage); } }敌人实现这个接口在TakeDamage中扣血并返回实际伤害值。这样武器脚本不需要知道敌人内部如何结算。7.2 调用飘字接口以一个近战武器为例using UnityEngine; using QFGame.ClassSurvivor.UI; namespace QFGame.ClassSurvivor { public class MeleeWeapon : MonoBehaviour { [SerializeField] private float damage 15f; [SerializeField] private float attackRadius 1.5f; public void DoAttack() { Collider[] hits Physics.OverlapSphere(transform.position, attackRadius); foreach (Collider hit in hits) { if (hit.TryGetComponent(out IDamageable target)) { float finalDamage target.TakeDamage(damage); ShowDamageNumber(hit.transform.position, finalDamage); } } } private void ShowDamageNumber(Vector3 worldPos, float damageValue) { int displayValue Mathf.RoundToInt(damageValue); ClassSurvivorGame.Interface .GetSystemFloatTextSystem() .ShowDamageText(worldPos, - displayValue, Color.yellow); } } }这里把伤害值取整后拼接成-100这种形式。你也可以在暴击时传入不同颜色比如橙色代表暴击绿色代表治疗。7.3 世界坐标转 UI 坐标的坑很多开发者在接入飘字时遇到文字显示在右下角或左上角往往是因为没有做坐标转换。FloatTextSystem内部虽然已经做了转换但要注意worldPos的准确性。敌人中心点往往不等于敌人头顶飘字一般应该从敌人头顶上方出现。所以调用处可以传入这样一个位置Vector3 textPos hit.transform.position Vector3.up * 0.8f;这个高度可以根据敌人模型大小微调。如果所有飘字都从模型中心出现十几个敌人叠在一起时数字会挤成一团体验很差。7.4 演示效果说明如果按照上面的流程接入运行游戏后每次武器命中敌人敌人头顶会出现一个黄色数字数字向上漂浮一小段距离后淡出。连续攻击时数字之间不会互相覆盖也不会因为前面节点残留而出现文字堆积因为池中的每个节点都在动画结束后自动回收到池中。8. 参数配置与表现控制8.1 使用可配置的 FloatTextSetting飘字参数如果硬编码在代码里调起来会很痛苦。我建议把参数配置到一个 ScriptableObject 中命名FloatTextConfig。using UnityEngine; using QFGame.ClassSurvivor.UI; namespace QFGame.ClassSurvivor { [CreateAssetMenu(menuName ClassSurvivor/FloatTextConfig, fileName FloatTextConfig)] public class FloatTextConfig : ScriptableObject { public FloatTextController Prefab; public RectTransform Container; public int PreloadCount 8; public Vector3 Offset new Vector3(0, 40, 0); public float Duration 0.6f; public float UpSpeed 90f; public float FadeDelay 0.15f; } }在 Unity 中右键Create - ClassSurvivor - FloatTextConfig把生成的资源放到Resources目录下并将飘字预制体和 Canvas 容器拖到对应字段上。Resources.Load会加载这个配置。8.2 不同伤害类型的颜色区分飘字的颜色可以用来区分伤害类型。例如普通伤害白色或黄色暴击伤害橙色治疗量绿色拾取经验浅蓝色颜色一般不用写死在飘字 System 里而是在业务调用处决定。FloatTextSystem只负责接收 Color 参数业务方可以根据伤害判定结果传入不同颜色。8.3 命中特效与飘字节奏飘字不是越多越好。类幸存者后期怪群大量死亡时如果每只怪都飘一个数字屏幕会非常乱甚至影响玩家判断。比较好的做法是普通小怪死亡时不飘字只有玩家受到伤害、暴击触发、拾取关键道具时飘字。这样既能保留反馈又不会刷屏。飘字的出现节奏也需要控制。如果单帧内飘字数量超过一定阈值可以做一个合并逻辑同一帧、同一目标、同类文本合并成一个更长的数字比如-150而不是-15 -15 -15。这个优化在实战中很实用。9. 常见问题与排查思路9.1 文字不显示或显示为方块飘字文字不显示最常见原因是字体没有正确配置。TMP 对中文字符支持依赖字体资产如果当前 TMP 字体资源没有包含中文字符运行时会显示为方块或一片空白。排查步骤打开 TMP 字体资产检查使用的字体是否支持中文。如果是在 Windows 下创建的资源确认动态字体文件没有被合并掉。在 TextMeshProUGUI 的 Inspector 中查看字体信息和字符集。解决方法是使用一个包含常用字符集的 TMP 字体资产或者使用 TMP 的 Dynamic Font 模式动态渲染需要的字符。9.2 飘字位置错乱位置错乱通常与 Canvas 渲染模式、相机参数、坐标变换有关。如果 Canvas 是ScreenSpaceCamera模式但FloatTextSystem没有获取 UI 相机会导致RectTransformUtility换算结果不正确。建议在OnInit中打印canvas.renderMode和canvas.worldCamera确认当前模式。如果使用ScreenSpaceOverlay在调用RectTransformUtility.WorldToScreenPoint时传 null如果使用ScreenSpaceCamera一定要传入对应的 UI 相机。9.3 对象池回收后状态未重置如果你发现第二次飘字时节点还保留上一次的颜色、文本或位置一般是ResetState不完整。例如只重置了text.text没有重置canvasGroup.alpha或者没有重置localPosition。排查时可以把所有状态重置集中到一个ResetState方法中每次从池中取出和归还都调用它不要在Get和Free中各自写一段逻辑。这样状态管理更集中不容易漏。9.4 频繁生成导致 Canvas 重建卡顿飘字节点属于 UIUI 内容变化会触发 Canvas 重建。如果同一帧创建了大量飘字或者在每帧都修改文字内容会增加重构开销。优化方向是减少活跃节点数量、合并同类文本、避免每帧修改文本尽量在飘字结束时立刻禁用节点。如果飘字数量确实很大还可以考虑把飘字从主 Canvas 中独立出去单独放在一个子 Canvas 中。这样主 UI 的布局变化不会强制飘字 Canvas 一起重建。问题现象常见原因解决思路文字不显示TMP 字体不支持字符换用支持中文的字体资产显示为方块字体资源没有中文字改用 Dynamic 字体或重新生成字体资产位置偏到角落坐标转换没做或相机参数错误校验 Canvas.reMode 和相机第二次显示残留旧状态ResetState 不完整统一在 ResetState 重置全部字段飘字抖动Update 中累加位置受帧率影响使用 Time.deltaTime 修正帧率差异卡顿同一帧创建大量飘字合并文本、控制飘字数量、子 Canvas 隔离10. 最佳实践与扩展方向10.1 架构层面的建议文字飘动支持看起来只是 UI 表现但放到 QFramework 架构中依然要遵守“逻辑层和表现层分离”的原则。战斗逻辑只负责计算和返回结果不要把ShowDamageText直接写在TakeDamage内部。正确的顺序是武器或技能造成伤害拿到伤害结果后再决定是否飘字、飘什么颜色、飘多大。对象池建议单独封装不要和 System 耦合死。当前FloatTextPool只服务于飘字后续如果要做拾取飘字、任务提示飘字可以考虑抽出一个通用 GameObejctPool但不要过度设计。飘字场景规模不大专门的 Pool 类完全够用。10.2 表现层扩展方向飘字功能可以从这些方向继续扩展暴击放大当暴击时飘字字体更大、颜色更亮甚至可以加一点缩放弹性动画。暴击缩放曲线用 AnimationCurve 控制 UI 的缩放视觉上更有冲击力。命中延迟根据伤害来源距离设置飘字延迟出现避免所有数字同一帧出现。多行飘字同一目标同时触发多个伤害时自动排列成多行避免重叠。方向偏移受击方向不同飘字初始偏移方向也不同增加临场感。10.3 UI 层与逻辑层分离我见过不少项目在Enemy的TakeDamage里直接写Instantiate(damageText, pos)初期开发确实快但代码会越来越难维护。一旦数值策划要调整飘字表现就得在多个敌人脚本里来回找。用 QFramework System 的方式所有飘字表现都收敛到一个类里。后续改颜色、改字体、改动画、改对象池策略都只需要动FloatTextSystem或FloatTextController业务调用方的代码基本不动。这个收益在项目进入中期后会非常明显。飘字功能本身不难难的是把它放到架构里让每个模块各司其职同时还能保持足够的表现自由度。你可以先按本文搭建一个最简版本跑通完整流程再做暴击放大、多行排列这些进阶效果。等一套飘字系统稳定运行在自己的类幸存者项目中你会发现后续加新技能、新道具的技能反馈都变得特别顺手。