@editable 进阶:ToolTip、Categories 与滑条

一、先复习基本功

第 18 课讲过:@editable 是写给编辑器的便签——贴在 creative_device 字段上一行,字段就出现在细节面板里。基础用法有三条铁律:字段必须有默认值;类型要在支持清单里(基本类型、设备引用、agent、数组,以及标了 <concrete> 的自定义类);它是 attribute,永远独占一行待在声明上方。

第 18 课讲过:@editable 是写给编辑器的便签——贴在设备(creative_device)某个变量上一行,这个变量就冒进细节面板,等于给它点亮 Instance Editable 小眼睛。基础用法有三条铁律:变量必须有默认值;类型要在支持清单里(基本类型、设备引用、agent(玩家引脚)、数组,以及标了 <concrete> 的自定义类);它是 @ 便签,永远自己独占一行、待在上方。

但只用裸的 @editable,你的设备面板和原生设备一比就露怯了:原生设备的属性有分组折叠、鼠标悬停有说明文字、数值有范围滑条,而你的字段孤零零挤在默认分组里,一个不小心还会被策划填进离谱数值。差距在哪?在元数据。

但只用裸的 @editable,你的设备面板和原生设备一比就露怯了:原生设备的属性有分组折叠、鼠标悬停有说明文字、数值有范围滑条,而你的变量孤零零挤在默认分组里,一个不小心还会被策划填进离谱数值。差距在哪?在元数据——就是你在蓝图变量 Details 面板里填的那些 Tooltip、Category、Slider 设置。

二、块级元数据:让面板长出高级控件

@editable 家族支持「块级元数据」写法:attribute 后面跟一个冒号,下一层缩进里逐条填元数据。这个能力最早在 Verse Update | GDC 2024 演讲中公开,官方文档长期没写清,论坛倒是早就验证出了可用语法。以滑条变体 @editable_slider 为例:

@editable 家族支持「块级元数据」写法:@ 便签后面跟一个冒号,下一层缩进里逐条把元数据填进去(就像在蓝图变量的 Details 面板里一项项设 Tooltip、Category)。这个能力最早在 Verse Update | GDC 2024 演讲里公开,官方文档长期没写清,论坛倒是早就验证出了可用写法。以滑条变体 @editable_slider 为例:

using { /Fortnite.com/Devices }

# ToolTip 和 Categories 的值要求 <localizes> message 常量
AttackGapTip<localizes>:message = "两次进攻之间的间隔秒数"
TowerCategory<localizes>:message = "防御塔设置"

tower_device := class(creative_device):

    # 块级元数据:分组 + 悬浮提示 + 滑条范围
    @editable_slider(float):
        Categories := array{TowerCategory}
        ToolTip := AttackGapTip
        MinValue := option{0.5}
        MaxValue := option{10.0}
    var AttackGap:float = 2.0

逐行拆解:@editable_slider(float) 声明「这个 float 字段用滑条控件展示」;Categories 把字段归进名为「防御塔设置」的分组(值是 message 数组,支持多级);ToolTip 是鼠标悬停时的说明文字;MinValue / MaxValue 用 option 包住滑条的上下限——策划从此拖不出 0.5 秒以下的进攻间隔,一整类配置事故直接消失。

读图翻译,逐行看:@editable_slider(float) 说「这个小数变量用滑条来调」;Categories 把它归进名为「防御塔设置」的分组(值是一串 message 常量,支持多级);ToolTip 是鼠标悬停时冒出来的说明;MinValue / MaxValue 用 option(可能有、可能没有的那种值)包住滑条的上下限——策划从此拖不出 0.5 秒以下的进攻间隔,一整类配置事故直接消失。这几个字段名,你在蓝图变量的 Details 面板里几乎原样见过。

注意一个容易被忽略的前置条件:ToolTip 和 Categories 的值不能直接写字符串字面量,必须是带 <localizes> 的 message 常量(如上面的 AttackGapTip)。<localizes> 意味着这些文案进了本地化管线——你的设备面板天生就是可翻译的。

注意一个容易被忽略的前置条件:ToolTip 和 Categories 的值不能直接写一句带引号的字符串,必须是戴了 <localizes> 徽章的 message 常量(就是上面那两行 AttackGapTip、TowerCategory)。<localizes> 表示这些文案进了本地化(翻译)管线——你的设备面板天生就能被翻成多国语言。

三、已知坑与实测建议

这套写法好用,但处在「官方演讲公开、文档跟进缓慢」的灰色地带,写之前先看三条提醒:

• Categories 曾在普通 Verse 设备上失效:论坛有 bug 报告称分组只在 NPC Behavior 上正常工作,普通 creative_device 上不生效。不同 UEFN 版本表现不一,写完务必在编辑器里实测一眼。
• 版本敏感:块级元数据的字段名和形态可能随版本调整,以当期 UEFN 版本实测为准(# TODO: 以 Verse API Reference 为准)。
• @editable 循环引用会出大事:A 设备 @editable 引用 B、B 又引用 A,曾有导致 UEFN 直接崩溃的报告——设计引用关系时保持单向。

即便有这些毛边,进阶 @editable 仍然值得投入:它是「代码写一次、策划调一万次」工作流的地基。面板体验做得越好,你被同事@的次数就越少。

本文整理自 Epic 开发者论坛与社区指南:论坛:How can I use the editable attributes with tooltips and categories ↗、论坛 bug 报告:editable Categories does not work in Verse devices ↗、Verse Island:Making class attributes editable in UEFN ↗。