Read this manual in English

消息传递

消息传递是 Defold 游戏对象间互相交流的机制. 本教程假设你已经大概了解了 Defold 的 定位机制 和 基本构成.

Defold 不使用类继承对象成员函数 (像 Java, C++ 或者 C#) 这类面向对象的概念. Defold 使用了一个简单有效的面向对象的设计扩展了 Lua, 把对象保存在脚本组件内部, 通过 self 引用来进行访问. 对象间通过消息交流机制进一步解耦.

使用示例

来看几个简单的例子. 假设你的游戏由以下部分构成:

1. 主启动集合里有一个带 GUI 组件的游戏对象 (GUI 包含一个迷你地图和一个计分器). 还有一个集合 id 叫 “level”.
2. 这个 “level” 集合包含两个游戏对象: 一个主角一个敌人.

游戏需要一个对象间的交流机制:

① 主角攻击敌人

作为机制的一部分, 一个 "punch" 消息从 “hero” 脚本组件发送到 “enemy” 脚本组件. 因为两个游戏对象处在集合层级结构的同级, 可以使用相对地址定位:

-- 从 "hero" 脚本向 "enemy" 脚本发送 "punch" 消息
msg.post("enemy#controller", "punch")

这个消息不带数据, 发送消息明就可以, “punch”.

在敌人的脚本组件里, 使用如下函数接收消息:

function on_message(self, message_id, message, sender)
  if message_id == hash("punch") then
    self.health = self.health - 100
  end
end

像这样, 代码仅查看了消息名 (作为哈希字符串在参数 message_id 里接收). 并不关系消息数据和发送者—任何组件 只要发送了 “punch” 都会对敌人造成伤害.

② 主角得分

主角打败敌人, 获得分数. 一个 "update_score" 消息从 “hero” 游戏对象脚本组件发送到 “interface” 游戏对象的 “gui” 组件.

-- 敌人被击败. 加 100 分.
self.score = self.score + 100
msg.post("/interface#gui", "update_score", { score = self.score })

这回就不能使用相对地址定位了因为 “interface” 处于层级根部而 “hero” 不是. 消息被发送到 GUI 组件的脚本上, 可被正确响应. 消息可以在脚本, GUI 脚本和渲染脚本间自由发送.

消息 "update_score" 带有分数数据. 数据作为一个 Lua 表由 message 参数接收:

function on_message(self, message_id, message, sender)
  if message_id == hash("update_score") then
    -- 更新计分器为当前分数
    local score_node = gui.get_node("score")
    gui.set_text(score_node, "SCORE: " .. message.score)
  end
end

③ 敌人在迷你地图上的位置

屏幕上有一个用于定位跟踪敌人的迷你地图. 敌人需要发送 "update_minimap" 消息到 “interface” 游戏对象的 “gui” 组件上:

-- 发送当前位置以更新迷你地图
local pos = go.get_position()
msg.post("/interface#gui", "update_minimap", { position = pos })

GUI 脚本代码跟踪每个敌人的位置, 如果某个敌人更新了位置, 旧的位置会被替换. 消息发送者 (由 sender 参数接收) 可以作为 Lua 位置表的键:

function init(self)
  self.minimap_positions = {}
end

local function update_minimap(self)
  for url, pos in pairs(self.minimap_positions) do
    -- 更新地图上的位置
    ...
  end
end

function on_message(self, message_id, message, sender)
  if message_id == hash("update_score") then
    -- 更新计分器为当前分数
    local score_node = gui.get_node("score")
    gui.set_text(score_node, "SCORE: " .. message.score)
  elseif message_id == hash("update_minimap") then
    -- 更新地图上的位置
    self.minimap_positions[sender] = message.position
    update_minimap(self)
  end
end

发送消息

发送消息机制, 从上面可以看到, 非常简单. 调用函数 msg.post() 把消息加入消息队列. 然后, 每一帧, 引擎遍历消息队列把每条消息发送到目标去. 有些系统消息 (像 "enable", "disable", "set_parent" 之类的) 引擎自己处理这些消息. 引擎也会发送一些消息 (像物理碰撞的 "collision_response" 消息) 到负责接收的游戏对象. 对于那些发送到脚本的消息, 引擎会调用函数 on_message().

可以向存在的对象或者组件发送任意消息. 如果脚本组件收到但不响应消息, 没问题. 响应与否完全取决于接收方.

引擎检查每条消息的目标. 如果消息接收者未知, Defold 会在控制台提示错误:

-- 尝试向不存在的对象发送消息
msg.post("dont_exist#script", "hello")

ERROR:GAMEOBJECT: Instance '/dont_exists' could not be found when dispatching message 'hello' sent from main:/my_object#script

函数 msg.post() 完整语法是:

msg.post(receiver, message_id, [message])

receiver

目标游戏对象或组件的 id. 如果目标是游戏对象, 消息会传播至游戏对象的所有组件上.

message_id

消息名字符串或者字符串哈希.

[message]

可选参数, 作为消息数据的 Lua 表键-值对. 几乎所有数据都可以存在表里. 可以用来传输数字, 字符串, 布尔值, 地址, 哈希和嵌套表. 不能传输函数.

-- 发送带嵌套表的数据
local inventory_table = { sword = true, shield = true, bow = true, arrows = 9 }
local stats = { score = 100, stars = 2, health = 4, inventory = inventory_table }
msg.post("other_object#script", "set_stats", stats)

简化符

Defold 提供两种简化写法用来简化消息传递时需要输入的完整地址:

.

指代当前游戏对象.

#

指代当前组件.

举例:

   -- 使当前游戏对象获得输入焦点
   msg.post(".", "acquire_input_focus")

   -- 向当前脚本组件发出 "reset" 信息
   msg.post("#", "reset")

接收消息

接收消息由 on_message() 函数完成. 函数接收4个参数:

function on_message(self, message_id, message, sender)

self

对脚本组件自身的引用.

message_id

消息名. 这个值 是哈希字符串.

message

包含消息数据. 即一个 Lua 表. 如果消息不包含数据, 此表为空.

sender

发送者绝对路径地址.

function on_message(self, message_id, message, sender)
    print(message_id) --> hash: [my_message_name]

    pprint(message) --> {
                    -->   score = 100,
                    -->   value = "some string"
                    --> }
    
    print(sender) --> url: [main:/my_object#script]
end

游戏世界之间的消息传递

如果使用集合代理载入一个新的游戏世界, 你可能需要游戏世界之间的消息传递功能. 假设已经用一个代理载入了一个集合, 其 Name 属性是 “level”:

当集合被载入, 初始化并开启, 就可以通过指定目标 “接口” 的方法向其中的任何游戏对象和组件发送消息了:

-- 向新游戏世界的主角发送消息
msg.post("level:/player#controller", "wake_up")

关于代理使用详情请见 集合代理 教程.

消息链

发送的消息最终由接收方 on_message() 函数调用接收. 由此函数里再发出消息是很常见的, 消息仍会被加入到消息队列中.

引擎把消息分别发送到接收方的 on_message() 函数里直到消息队列为空. 如果接收方还要发送消息, 会进行新一轮消息传输. 然而, 引擎清空消息队列次数有一个限制, 也就相当于每帧消息链长度的限制. 可以使用如下代码在 update() 函数里测试出这个限制:

function init(self)
    -- 初始化时建立一个长消息链
    -- 并在 update() 中记录消息链发送长度.
    print("INIT")
    msg.post("#", "msg")
    self.updates = 0
    self.count = 0
end

function update(self, dt)
    if self.updates < 5 then
        self.updates = self.updates + 1
        print("UPDATE " .. self.updates)
        print(self.count .. " dispatch passes before this update.")
        self.count = 0
    end
end

function on_message(self, message_id, message, sender)
    if message_id == hash("msg") then
        self.count = self.count + 1
        msg.post("#", "msg")
    end
end

运行代码输出如下:

DEBUG:SCRIPT: INIT
INFO:ENGINE: Defold Engine 1.2.36 (5b5af21)
DEBUG:SCRIPT: UPDATE 1
DEBUG:SCRIPT: 10 dispatch passes before this update.
DEBUG:SCRIPT: UPDATE 2
DEBUG:SCRIPT: 75 dispatch passes before this update.
DEBUG:SCRIPT: UPDATE 3
DEBUG:SCRIPT: 75 dispatch passes before this update.
DEBUG:SCRIPT: UPDATE 4
DEBUG:SCRIPT: 75 dispatch passes before this update.
DEBUG:SCRIPT: UPDATE 5
DEBUG:SCRIPT: 75 dispatch passes before this update.

可以看到这版 Defold 引擎在 init() 到 update() 中间发送10轮消息. 然后每帧发送75轮消息.