Agency-Hud：为每个服务器打造理想 FiveM HUD 的设计理念

HUD问题

默认 FiveM HUD 混乱不堪。玩家屏幕上堆积半打冲突覆盖层，无统一视觉语言，关键信息被装饰性元素掩盖。我们加入的每个服务器都有同样问题：HUD 太多，清晰度不足。Agency-Hud 旨在解决此问题。

信息层级

我们将 HUD 元素分为三个层级。第一层级始终可见：生命值、护甲、饥饿、口渴。第二层级根据情境显示：驾驶时的车辆速度表，说话时的语音范围指示器。第三层级按需显示：小地图切换，职业状态，库存。每个层级有自己的视觉权重，进出动画流畅。除非当前重要，否则不会争夺注意力。

内置无障碍功能

高对比度模式、可配置大小和色盲安全状态指示器开箱即用。2026年这不是可选项，您的玩家将包括有各种视觉需求的人群，专业的HUD能满足他们。服务器所有者可以为其社区切换这些默认设置。

车辆生成下的性能

HUD性能最大陷阱是在大量车辆或NPC生成时重绘。Agency-Hud使用单一渲染目标和增量更新，我们只重绘变化部分，而非整个覆盖层。在64人服务器的抢劫事件中，HUD的资源消耗仅为同类替代品的十分之一。

无混乱的定制

服务器所有者可以重新定位每个 HUD 元素，切换配色方案，并从单一配置文件隐藏特定部分。但我们刻意不提供主题市场或用户端定位，您构建的 HUD 是所有玩家看到的 HUD，这保持了服务器视觉语言的一致性。统一性是一种功能。

安装与设置

Agency-Hud 不依赖数据库。从 Tebex 下载后，将文件夹放入 resources 目录，然后添加 ensure agency-hud 到 server.cfg. 资源自动检测您的框架，并从相应来源获取生命值、护甲、饥饿和口渴值。独立设置中，数据钩子为四个配置函数。

如果您替换现有 HUD，请先禁用旧的。大多数 HUD 冲突是由两个资源同时绘制同一屏幕区域引起的。Agency-Hud 没有硬编码的屏幕区域，所有位置均可配置，因此在需要时可以与特定第三方覆盖共存。

配置选项

该 config.lua 涵盖布局、视觉和性能设置：

• 元素位置，每个 HUD 元素的 X/Y 位置和锚点单独设置。
• 缩放，全局缩放因子及每个元素的缩放覆盖。适用于超宽显示器用户。
• 配色方案，状态指示器的主色、警告色和关键色。默认遵循 Agency 的青绿色调色板。
• 高对比度模式，预配置的颜色集，针对低对比度敏感玩家优化。
• 色盲模式，为状态指示颜色提供红绿色盲（deuteranopia）、红色盲（protanopia）和蓝黄色盲（tritanopia）预设。
• 第二等级条件，精确定义每个上下文元素（速度表、语音指示器等）显示的条件。
• 小地图行为，始终开启、移动时切换或仅手动切换。
• 更新率，HUD轮询数值变化的频率。默认：250毫秒（性能平衡）。

框架兼容性

Agency-Hud 自带 QBCore 和 ESX 数据适配器。对于 standalone，需要实现用于读取生命值、护甲、饥饿值、口渴值、语音范围和职业数据的配置函数。渲染层、动画系统、等级逻辑和无障碍模式都与框架完全无关。切换框架时，只需替换数据适配器，无需重新安装资源。

为什么这对角色扮演很重要

HUD是唯一始终显示的UI元素。不同于玩家主动打开的手机或平板，HUD是环境的一部分，存在于感知边缘，影响每一个游戏时刻。设计糟糕的HUD是对玩家体验的持续负担。优秀的HUD则是隐形的：需要时出现，不需要时消失，从不争夺未获许可的注意力。

分级可见性方法是核心设计洞察。一级（始终可见，小型）持续告诉玩家他们需要知道的信息：“我快死了吗，我饿了吗，我有护甲吗？”二级（情境性，条件出现）告诉玩家情境所需信息：“我开多快了，我的麦克风开了吗？”三级（按需）告诉玩家偶尔需要知道的信息：“我的工作状态如何，我的快捷库存里有什么？”

无障碍在Agency HUD中不是事后考虑，而是首要关注，因为游戏玩家中有相当一部分存在某种形式的色觉差异。对色盲玩家不可读的HUD不仅是用户体验失败，更是影响服务器真实玩家的无障碍失败。提供预设不花费任何成本，却对需要它们的玩家意义重大。

常见问题

玩家可以自定义自己的HUD布局吗？

不，这是有意为之。服务器所有者控制HUD布局，玩家无权更改。这是为了保持一致性：每个玩家HUD布局不同的服务器缺乏统一的视觉识别。如果想提供有限的玩家选择（切换小地图、缩放大小），这些选项可以作为游戏内命令暴露，写入玩家偏好表。

Agency-Hud 是否替换默认的 FiveM 小地图？

是的。它在canvas元素上渲染自己的小地图，支持可配置缩放和路径点显示。资源启动时隐藏原生小地图。如果您需要保留特定原生小地图行为（某些反作弊工具挂钩其上），有一个 Config.UseNativeMinimap = true 重新启用Agency-Hud其他元素下的原生地图的选项。

在拥挤服务器上的性能表现如何？

Agency-Hud 使用增量渲染，只会重绘值相较上一帧发生变化的 HUD 元素。在玩家人数达到 128 的繁忙服务器上，HUD 每帧的典型绘制调用耗时为 0.01-0.03ms。我们文档中的基准测试对比显示，在相同条件下，这一耗时比大多数替代 HUD 低 3-5 倍。

我可以为服务器特定机制添加自定义HUD元素吗？

是的。使用 exports['agency-hud']:RegisterElement(id, options) 添加自定义指示器。传入一个在 Agency-Hud 绘制循环中调用的渲染函数。您的自定义元素自动参与层级系统并遵循服务器的配色方案。

需求

• FiveM 服务器（QBCore、ESX 或独立）
• 拥有有效 Agency-Hud 许可证的 cfx.re 账户
• 无数据库依赖
• 可选：ox_lib（用于UI组件，带回退）