roblox-ui-hud

Roblox 游戏 UI / HUD 模式

手工构建的 HUD（而非自动缩放模板），在不同设备上都能正常显示且清晰易读。

跨设备的响应式布局

• UIScale（例如 fitScale 辅助函数）会围绕元素的锚点缩放其尺寸，而不是位置。 因此，单靠缩放不会重新定位；必要时应针对不同设备重新计算位置。不要在同一元素上嵌套两个 UIScale（父级 + 子级），否则会重复缩放。
• 根据最小尺寸判断设备类型，不要只依赖 TouchEnabled——math.min(vp.X, vp.Y) 不受屏幕方向影响：手机短边约为 ≤430，平板约为 ≥744。区分桌面设备 / 手机（isMobile and min < 600）/ 平板（isMobile and min >= 600），这样旋转后的平板就不会被当成手机。
• 将堆叠的 HUD 元素锚定到面板的实时高度，而不是硬编码像素偏移。 常见问题：加成 / 胶囊行硬编码“面板是 104px”，但上方面板会随内容增加高度（clamp(base + n*rowH, …)），于是面板展开后两者就会重叠。读取相邻元素的实际 AbsoluteSize.Y（或其计算公式），并据此定位。
• 为 Roblox 自带的移动端控制留出空间： DynamicThumbstick 的触控区域会延伸到左下方约 0.75· vp.Y 的位置，而跳跃按钮位于右下方；底部锚定的 HUD 应向上抬高，避免与它们重叠，同时兼顾有无安全区内边距的情况。请在小屏手机（iPhone SE）和大屏手机（Pro Max）上验证——这是两种最极端的情况。

ScreenGui 面板

• 经测试效果良好的惯例：每个屏幕 / 面板使用一个 ScreenGui，设置 Enabled = false，并预先构建好内容。 将 .Enabled = true 切换为打开。（对于 MCP 测试，启用后会显示居中的面板；滑入式面板关闭时位于屏幕外，因此切换后什么也看不到——应改为将它们动画滑入。）
• 同一时间只打开一个面板： 使用 closeAll() 在打开下一个面板前关闭 / 隐藏所有面板。
• 点击面板外部关闭： .Active = true 无法可靠地拦截穿透子级 ScrollingFrame 的点击。应在背景的 InputBegan 中检查边界——仅当点击位于面板 AbsolutePosition / AbsoluteSize 之外时才关闭。

进度条 / 仪表（可复用方案）

圆角背景 Frame + 填充 Frame + 居中文本叠层：

fill.Size = UDim2.fromScale(math.clamp(frac, 0, 1), 1)   -- fill = fraction of the bar
fill.BackgroundColor3 = good and GREEN or AMBER           -- colour conveys status at a glance
text.Text = ("%d / %d · %s"):format(done, total, statusLabel)

⚠️ 布尔可见性问题（我就栽在这上面了）： 在 Luau 中，local show = a and b and season.teams 返回的是最后一个操作数（一个表），而不是 true——因此 frame.Visible = show 会报错，或者 show == true 总是为假。应确保条件结果是真正的布尔值：以比较表达式结尾（… and season.teams ~= nil），或对其进行封装。即使隐藏，也要保留进度条所占的位置，避免布局跳动。

布局注意事项（能省下好几个小时）

• 水平自动尺寸 UIListLayout 默认会忽略 LayoutOrder——设置 SortOrder = Enum.SortOrder.LayoutOrder，否则标签会按相反顺序 / 创建顺序渲染。
• UDim2.new(0,0,1,0)（只设置一组参数） 会触发 selene 的“use fromScale”警告——请使用 UDim2.fromScale / fromOffset。
• 字体字形： Gotham 会把 ✕ ↻ ✦ 渲染成方框——请使用 X、★、◆、$。表情符号可以正常显示（🍀 👑 ⚡ ⚔️ 🏆），但旗帜表情符号除外（会显示为两个字母）——请用 Frame 绘制旗帜。

文案与清晰度（小规则，大提升）

• **在 HUD 中优先使用图标 / 字形，而非行话。**例如，用货币图标表示货币，而不是写“现金 / 碎片 / 宝石”；名称只应出现在描述奖励的地方（商店）。同样的原则：避免在面向玩家的文本中使用内部系统术语（描述操作 / 结果，而不是说“给 X 面板升级”；说“队伍”，而不是“XI”）。
• 保持通俗易懂——以全新玩家的视角阅读每一条文案。

验证 UI（MCP）

截图可能会误导 UI 状态——自由视角捕获可能导致 ScreenGui 被隐藏，而远距离的 SurfaceGui 特写可能呈现空白。请通过遍历 PlayerGui:GetDescendants() 并检查 .Text / .Visible / ImageLabel.Image / 配件数量进行交叉验证。MCP 工具及其注意事项（按 AbsolutePosition 点击、跨 VM 规则、捕获伪影）见 roblox-studio-mcp 技能；开发 / 测试循环见 roblox-studio-workflow。