迁移实战:把一张蓝图完整翻译成 Verse

一、原始素材:一张待翻译的蓝图

翻译得先有原文。下面这张图叫 BP_PressurePlate,是那种每张地图里都能找到的小机关:踩上去,门开;过几秒,门自己关上。它的父类是 Actor,资产是一个 .uasset 二进制文件,双击打开能看到两块内容——左下角的变量面板,和中间那张事件图表。

变量面板一共三行。「小眼睛」那一列就是 Instance Editable:点亮之后,这个变量会出现在关卡里每个实例的 Details 面板上,策划不碰蓝图也能改。

事件图表只有一条执行线,七格节点,从左到右串成一串:

连起来读一遍:踩上去 → 判断门是不是关着 → 记状态 → 开门 → 等 OpenDuration 秒 → 关门 → 状态复位。你在脑子里应该已经能看见那张图了——七个方块、一条白线、右上角挂着一个 Delay 的小钟表。接下来的六步,就是把这张图一块一块搬进 .verse 文件。

翻译前先立一条纪律:第一遍要忠实,不要顺手优化。你现在已经知道 Verse 里有 race、有 option、有更漂亮的写法,但一边翻译一边重新设计,出了 bug 你分不清是翻错了还是改错了。先让译本跑出和原图一模一样的行为,再谈重构——什么时候该重构、重构成什么样,留给本课的拔高拓展页。

二、逐段翻译:六步走完整张图

每一步都是同一个套路:原图的这一块 → Verse 的这几行 → 为什么这样对应。顺序是有讲究的——先骨架、再数据、再引用、最后才是执行线,和你在蓝图里新建一个类的顺序完全一致。

第一步:类的骨架与父类

原图的这一块:资产 BP_PressurePlate 本身。Class Settings 里 Parent Class 那一栏写着 Actor。

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

pressure_plate_door := class(creative_device):

为什么这样对应:蓝图里「右键新建 Blueprint Class → 选父类 → 起名字」这三步操作,在 Verse 里合成了一行 子类名 := class(父类名):。三行 using 是蓝图里没有的东西——蓝图的节点面板里什么都能搜到,Verse 得先声明你要用哪些模块的东西(第 7 课)。命名也换了规矩:资产名的 BP_ 前缀和 PascalCase,在 Verse 里变成 snake_case 的 pressure_plate_door(第 4 课)。

父类为什么不是 Actor?因为今天能真正跑 Verse 的地方是 UEFN,那里一段「能被拖进关卡、有 Event BeginPlay 入口」的 Verse 代码,就是 creative_device 的子类(第 6 课)。UE6 把 UE5 与 UEFN 合并之后,Scene Graph 的 entity + component 会是另一套骨架——第 26、27 课讲过,x2 拓展页会把这台设备按那套模型再拆一次。

第二步:变量面板 → 字段

原图的这一块:变量面板的前两行,IsOpen 和 OpenDuration。

    # 原图:OpenDuration,Float,已勾 Instance Editable
    @editable
    OpenDuration:float = 5.0

    # 原图:IsOpen,Boolean,未勾 Instance Editable
    var IsOpen:logic = false

为什么这样对应:蓝图里变量只有一种,「会不会被改」不需要提前声明;Verse 反过来,默认不可变,只有会被 Set 的才写 var(第 8 课)。判断方法很机械,不用动脑:在原图里对这个变量按一下「Find References」,接过 Set 节点的就写 var,没接过的就不写。IsOpen 在③⑦两格被 Set 过,所以是 var;OpenDuration 全图只被读,所以不写。

那只小眼睛就是 @editable(第 22 课)。类型对照表也很直接:Boolean → logic、Float → float、Integer → int、String → string(第 9、10、11 课)。注意 Verse 的字段必须给默认值,这一点和蓝图变量面板的 Default Value 那一栏是对得上的。

第三步:Actor 引用 → @editable 的设备引用

原图的这一块:变量面板第三行 TargetDoor,类型是 BP_Door 的 Actor 引用,默认 None,放进关卡后要用 Details 面板上那个吸管指向场景里那扇门。另外还有原图没写在变量面板里的一样东西:压力板本体那个碰撞盒——①号节点 Event ActorBeginOverlap 就挂在它身上。

    # 原图的碰撞盒:触发源改由关卡里的一台设备承担
    @editable
    Plate:button_device = button_device{}

    # 原图变量面板:TargetDoor,BP_Door 的 Actor 引用
    @editable
    TargetDoor:barrier_device = barrier_device{}

为什么这样对应:这是整张图最需要动脑的一格。蓝图的 Actor 引用默认值是 None,忘了绑,运行时就是那句人见人烦的 Accessed None;Verse 的 @editable 设备引用必须给一个默认值(barrier_device{} 是个空壳占位),所以它在编译期永远不为空——忘了绑的表现变成「按了没反应」,难查一点,但不会崩。真正表达「可能没有」的类型在 Verse 里叫 option(第 18 课),这是这门语言对 Accessed None 的正面回答。

还有一处必须诚实交代:原图那个「踩上去」的碰撞盒,没有一对一的译文。Verse 里没有「我这个 Actor 被谁 overlap 了」这种事件可以订阅,触发源得是关卡里一台真实存在的设备,由它广播事件。所以这一步把碰撞盒外置成了一个设备插槽。本课用已核实的 button_device.InteractedWithEvent 做演示;如果你用触发器 / 区域一类的设备,事件名请对照官方 Verse API Reference 核实一遍再写。

第四步:事件绑定 → 登记一次监听

原图的这一块:①号节点 Event ActorBeginOverlap。

    OnBegin<override>()<suspends>:void =
        Print("压力板译本上线,等待触发。")
        spawn{ PlateLoop() }

为什么这样对应:蓝图的事件节点是引擎替你挂好的——你把 Event ActorBeginOverlap 拖进图,连上线,登记这件事就已经完成了,你甚至没意识到有「登记」这一步。Verse 没有这个自动挂载:你得自己找一个入口,在那里把监听登记上去。入口就是 OnBegin,也就是 Event BeginPlay 的覆写。

登记有两种写法(第 25 课):事件.Subscribe(函数) 完全对应蓝图的 Bind Event,事件响了就调用那个函数;事件.Await() 则是让当前这条执行线停在原地等。原图是「每次触发,把下面那串节点从头跑一遍」,所以译本用 loop + Await() 更贴形状——循环的每一圈就是原图的一次触发。而 loop 会一直占着它所在的那条线,所以要用 spawn 岔一条常驻线专门跑它(第 24 课),OnBegin 登记完就退场。

第五步:Branch → if;Delay → Sleep

原图的这一块:②号 Branch 和⑤号 Delay,执行线的两个关节。

    PlateLoop()<suspends>:void =
        loop:
            Plate.InteractedWithEvent.Await()
            if (not IsOpen?):
                OpenDoor()
                Sleep(OpenDuration)
                CloseDoor()

Branch → if:蓝图的 Branch 有一个 Boolean 条件引脚、两个出口。Verse 的 if 括号里要的不是一个布尔值,而是一段「走不走得通」的判断——官方叫失败上下文(第 12 课)。所以 logic 变量得先加一个 ? 变成一次盘问:IsOpen? 在 true 时走得通、false 时走不通(第 11 课)。原图的条件引脚上挂了个 NOT,取反就是 not IsOpen?。True 引脚往下那一串节点 = 缩进进去的那一块;原图 False 引脚空着,译本就不写 else。

Delay → Sleep:蓝图的 Delay 是 Latent 节点,左上角挂着小钟表。Verse 里它叫 Sleep(秒数),秒数直接喂 OpenDuration,和原图把变量拖到 Duration 引脚上是同一件事。

但这里有一条蓝图作者最容易忽略的规则:能等的东西,只能待在挂了 <suspends> 的函数里。原图能把 Delay 随便丢进任意一张事件图,是因为蓝图的事件图天生就允许 Latent 节点;Verse 把这件事写进了函数签名——PlateLoop()<suspends>:void 里那个 <suspends>,就是「这张函数图允许放带小钟表的节点」的书面许可(第 23 课)。删掉它,Sleep 和 Await() 当场编不过。反过来,下一步那两个小函数不写 <suspends>,因为它们不等任何东西,一口气跑完就返回。

第六步:收尾与完整代码

原图的这一块:③④两格和⑥⑦两格。

    OpenDoor():void =
        set IsOpen = true
        TargetDoor.Disable()
        Print("门已打开,倒计时开始。")

    CloseDoor():void =
        set IsOpen = false
        TargetDoor.Enable()
        Print("门已关闭,压力板复位。")

为什么这样对应:③④和⑥⑦是同一种形状(记状态 + 拨那扇门)出现了两次,所以打包成两个小函数——蓝图里你也会把重复的一串节点折叠成 Collapse to Function,是同一个动作。set 就是 Set 节点,一个都不能省(第 8 课)。

还有一处极性陷阱:barrier 设备的 Enable() 意思是「屏障存在」,也就是门关;Disable() 是「屏障消失」,也就是门开——和原图 Open() / Close() 的字面意思正好反着。逐节点翻译时这一格翻反的概率极高。把它封进函数名里,图上从此只出现「开门」「关门」,再也不用在脑子里做一次取反。

六步走完,零件齐了。下一节把它们拼成完整的 .verse 文件,并且一行一行跑给你看。

三、逐行运行:译本跑一遍,对回原图

下面就是 BP_PressurePlate 的完整 Verse 译本,43 行。右边运行面板里的每一步,都会告诉你这一行对应原图里的哪个节点——点「运行下一步」,一路对回去。

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

# BP_PressurePlate 的 Verse 译本——逐节点对照见本课「蓝图对照」
pressure_plate_door := class(creative_device):

    # 原图的碰撞盒:触发源改由关卡里的一台设备承担
    @editable
    Plate:button_device = button_device{}

    # 原图变量面板:TargetDoor,BP_Door 的 Actor 引用,已勾 Instance Editable
    @editable
    TargetDoor:barrier_device = barrier_device{}

    # 原图变量面板:OpenDuration,Float,已勾 Instance Editable
    @editable
    OpenDuration:float = 5.0

    # 原图变量面板:IsOpen,Boolean,未勾 Instance Editable
    var IsOpen:logic = false

    OnBegin<override>()<suspends>:void =
        Print("压力板译本上线,等待触发。")
        spawn{ PlateLoop() }

    PlateLoop()<suspends>:void =
        loop:
            Plate.InteractedWithEvent.Await()
            if (not IsOpen?):
                OpenDoor()
                Sleep(OpenDuration)
                CloseDoor()

    OpenDoor():void =
        set IsOpen = true
        TargetDoor.Disable()
        Print("门已打开,倒计时开始。")

    CloseDoor():void =
        set IsOpen = false
        TargetDoor.Enable()
        Print("门已关闭,压力板复位。")

跑完你会注意到一个语义差异,值得记一笔:原图里 Event ActorBeginOverlap 每次都会触发,②号 Branch 才是那个把重复触发挡回去的门卫;译本里 loop 没绕回第 29 行之前,新的触发根本不会被接住——结构本身就防重入了,IsOpen 这个门卫其实已经冗余。先照搬,别急着删:第一遍忠实,第二遍再决定要不要重新设计。这正是拔高拓展页要谈的事。

四、翻译时最容易出错的 5 个地方

这五条不是随手列的,是「蓝图作者第一次翻译」几乎必踩的五格。每条都标了回链课号——踩到了就回去补一课。

五、哪些东西翻译不过去

一门诚实的迁移课必须讲这一节。下面这几样东西,不是「Verse 里写法不同」,而是不在 Verse 的职责范围内——你去找对应写法,只会浪费一个下午。

把这几条摆出来,不是为了泼冷水,而是为了让你在真实项目里划对边界:一张蓝图里通常只有一部分是玩法逻辑,剩下的是美术、动画、编辑器工具。迁移的对象是前者。

关于时间线,把事实再摆一次(措辞按官方口径):Actor 与 Blueprint 在 UE6 Early Access(目标 2027 年底)及早期版本中完整支持;弃用要等 Scene Graph 足够成熟,时间未定。Epic 已承诺在弃用前提供转换工具,但尚未发布。所以这一课教的手工翻译,短期内是「读懂两边」的训练,长期看是「审阅转换工具的产出」的底气——工具能搬结构,搬不动设计意图,你得看得出来哪一段该重写。

蓝图对照

整张 BP_PressurePlate,逐节点、逐变量的对照总表。差异那一列才是重点——它解释了为什么有些格子不是简单换个写法,而是换了思路。

通读这张表,你会发现差异集中在三处:可变性要声明(var)、判断要能失败(? 与失败上下文)、等待要有许可(<suspends>)。这三条不是 Verse 在为难你,而是它把蓝图里三类「运行时才炸」的问题——改错了状态、判断了个空、在不该等的地方等——统统提到了编译期。代价是多写几个关键字,回报是那三类崩溃在你按下 Build 的那一刻就被拦下。

还有一层差异不在语法上:蓝图是二进制资产,两个人同时改一张事件图,冲突基本只能二选一;.verse 是文本,能 diff、能 review、能逐行合并,也能直接交给 AI 读写——这正是下一课的主题。

六、关卡挑战

先把译本最关键的三块补回去,再答三道题。答对拿星星 ★,答错可以一直重试。

# 补全三个空:让 Delay 合法的那块牌子、Set 节点的关键字、Delay 本身
PlateLoop()<____>:void =
    loop:
        Plate.InteractedWithEvent.Await()
        if (not IsOpen?):
            ____ IsOpen = true
            TargetDoor.Disable()
            ____(OpenDuration)
            set IsOpen = false
            TargetDoor.Enable()

拓展阅读