Godot 4 MultiplayerSynchronizer 深度解析:属性同步与按需可见性控制

原创2026-10-12 19:22:071,890 阅读
文章标签:文档教程游戏开发

Godot 4 MultiplayerSynchronizer 深度解析:属性同步与按需可见性控制

导读

MultiplayerSynchronizer 是 Godot Engine 高层多人游戏 API 中负责**属性状态复制(Replication)**的核心节点,它把多人权威端(通常为服务器)上配置好的节点属性持续同步到所有远程对端,并与 MultiplayerSpawner 协作实现"谁可见谁生成"的动态节点管理。阅读本文后,你将掌握该节点的全部属性、方法、信号与可见性过滤机制,能够在自己的联机项目中完成位置、血量、得分等游戏状态的自动同步与逐对端(per-peer)可见性控制。

本文以官方类参考 class_multiplayersynchronizer.rst 为主体,并结合仓库内 class_scenereplicationconfig.rst、class_multiplayerspawner.rst、class_scenemultiplayer.rst 与 高层多人网络教程 进行源码级佐证。

一、节点定位与工作原理

1.1 类层次与核心职责

从 class_multiplayersynchronizer.rst 可以看到:

Inherits: Node < Object

它的职责可以用一句话概括:Synchronizes properties from the multiplayer authority to the remote peers——将"多人权威"持有的属性状态,同步到远程对端。

"多人权威"(multiplayer authority)指的是对某个节点拥有网络控制权的对端。根据 class_node.rst 中 set_multiplayer_authority(id, recursive = true) 的说明,权威默认是 peer ID 1(即服务器),可以通过该方法为任意节点单独指定权威,且该权威不会自动复制给其他对端,开发者需要自行借助 MultiplayerSynchronizer、RPC 或 MultiplayerSpawner.spawn_function 来传播权威信息。

1.2 与 MultiplayerAPI 的协作:object_configuration_add/remove

MultiplayerSynchronizer 的启动与停止不是凭空发生的,而是通过 MultiplayerAPI 的通知机制触发的。官方文档明确说明:

object_configuration_add/remove 是 MultiplayerAPI 的通用扩展接口:SceneTree 用它配置自身的 root path,MultiplayerAPI 的具体实现(如 SceneMultiplayer)可以借此提供额外特性,这一设计也意味着通过 MultiplayerAPIExtension 自定义 MultiplayerAPI 时,同样要正确处理这两个调用。

1.3 与 MultiplayerSpawner 的联动

MultiplayerSpawner 是"生成/销毁节点"的节点,MultiplayerSynchronizer 是"同步属性"的节点,二者配合构成完整的场景复制方案。官方文档给出关键约束:

MultiplayerSpawner 会依据同步器的可见性来处理节点,前提是 root_path 指向的节点是由该 Spawner 生成的。

也就是说:当一个节点由 MultiplayerSpawner 生成,且 MultiplayerSynchronizer.root_path 指向它时,对端是否能看到这个节点、进而是否生成/销毁它,会跟随同步器的可见性设置自动联动——这为"视野同步"(只同步玩家附近的实体)提供了现成的骨架。关于 Spawner 的 spawn_path、spawn_limit、spawn_function 等细节,可参考 class_multiplayerspawner.rst。

1.4 默认行为

默认情况下,MultiplayerSynchronizer 会把配置好的属性同步给所有对端(public_visibility = true)。若需要更细粒度的控制,则使用下文介绍的可见性 API。

二、属性同步配置:replication_config 与 SceneReplicationConfig

MultiplayerSynchronizer 本身不直接声明"同步哪些属性",而是引用一个 SceneReplicationConfig 资源:

replication_config: SceneReplicationConfig

该资源的定位是"Configuration for properties to synchronize with a MultiplayerSynchronizer",即同步属性清单(详见 class_scenereplicationconfig.rst)。每个被同步的属性由其相对 root_path 的 NodePath 标识,并带有三类配置维度:

维度 说明
是否参与同步(Spawn) 节点生成(spawn)时是否携带该属性值,对应 property_set_spawn()
复制模式(Replication Mode) 属性在运行过程中的同步策略,对应 property_set_replication_mode()

2.1 三种复制模式(ReplicationMode 枚举)

SceneReplicationConfig 定义了三个枚举值,直接决定 MultiplayerSynchronizer 的两个同步间隔属性(replication_interval / delta_interval)如何生效:

枚举值 值 语义
REPLICATION_MODE_NEVER 0 不保持该属性同步
REPLICATION_MODE_ALWAYS 1 每个处理帧(process)持续发送更新,使用 不可靠(unreliable) 传输模式
REPLICATION_MODE_ON_CHANGE 2 属性值发生变化时发送更新,使用 可靠(reliable) 传输模式

一句话总结取舍:ALWAYS 适合位置、朝向这类高频且允许偶发丢失的状态,延迟更低;ON_CHANGE 适合血量、得分这类必须送达的离散状态,带宽更省但可靠传输有性能开销。

2.2 属性清单管理 API

SceneReplicationConfig 提供了完整的属性清单管理接口:

  • add_property(path: NodePath, index: int = -1):把指定路径加入同步清单,可选 index 控制顺序;
  • remove_property(path: NodePath):从配置中移除指定属性;
  • get_properties() -> Array[NodePath]:返回全部被同步属性的路径列表;
  • has_property(path: NodePath) -> bool:判断某路径是否已在同步清单中;
  • property_get_index(path: NodePath) -> int:查找某路径在清单中的索引;
  • property_set_spawn(path, enabled) / property_get_spawn(path) -> bool:控制属性是否在生成时同步;
  • property_set_replication_mode(path, mode) / property_get_replication_mode(path) -> ReplicationMode:设置/查询复制模式。

需要注意:property_set_sync() / property_get_sync() 与 property_set_watch() / property_get_watch() 已被标记为 Deprecated(弃用),官方建议分别改用 REPLICATION_MODE_ALWAYS 与 REPLICATION_MODE_ON_CHANGE 对应的复制模式 API。在编辑器里,这些配置通常通过 Inspector 中 MultiplayerSynchronizer 的复制配置面板直接勾选完成,代码方式则可用于运行时动态调整。

三、核心属性逐一拆解

MultiplayerSynchronizer 共暴露 6 个可配置属性,下面按"路径与配置、同步节奏、可见性"三组展开。

3.1 root_path:复制属性的相对基准

root_path: NodePath = NodePath("..")
  • 含义:被复制属性的相对路径基准。NodePath("..") 默认指向同步器节点的父节点,因此无需额外设置即可把"父节点及其子节点上的属性"作为同步对象;
  • 联动:如果 root_path 指向的节点由 MultiplayerSpawner 生成,那么该节点会依据同步器的可见性选项被生成或销毁(spawned and despawned)。

这也是官方推荐的节点结构:把 MultiplayerSynchronizer 作为目标节点的子节点,默认 root_path 即命中目标。

3.2 replication_config:同步属性清单

replication_config: SceneReplicationConfig

类型为 SceneReplicationConfig 资源,决定"同步哪些属性、以什么模式同步"(详见上文第二章)。它是整个同步器的"内容来源",未配置时没有任何属性会被同步。

3.3 replication_interval 与 delta_interval:两种同步节奏

replication_interval: float = 0.0
delta_interval: float = 0.0

这两个属性分别对应 SceneReplicationConfig 的两种复制模式:

属性 适用复制模式 语义
replication_interval REPLICATION_MODE_ALWAYS 两次**同步(sync)**之间的时间间隔
delta_interval REPLICATION_MODE_ON_CHANGE 两次**增量同步(delta sync)**之间的时间间隔

两者均以秒为单位,默认值 0.0 表示在每个网络处理帧(network process frame)都执行同步。需要控制带宽占用时,可按需调大间隔(例如位置同步每 0.1 秒一次);需要极低延迟时保持 0.0。

关于包大小,可在 SceneMultiplayer 上做全局调优(详见 class_scenemultiplayer.rst):

  • max_sync_packet_size = 1350:每个同步包的最大字节数(默认贴近 UDP MTU);值越大,单帧收到完整更新的概率越高,但丢包概率也上升;
  • max_delta_packet_size = 65535:每个增量(delta)包的最大字节数;值越大越可能在单帧收到完整增量,但也更容易引发网络拥塞(高延迟、断连)。

3.4 public_visibility 与 visibility_update_mode

public_visibility: bool = true
visibility_update_mode: VisibilityUpdateMode = 0
  • public_visibility:同步是否默认对所有对端可见。true 时所有对端都能收到同步数据;配合 set_visibility_for(0, ...) 可整体修改它;
  • visibility_update_mode:可见性过滤器(visibility filter)在什么时机被更新,取值见第五章的 VisibilityUpdateMode 枚举。

3.5 属性速查表

属性 类型 默认值 作用
root_path NodePath NodePath("..") 被复制属性的相对基准路径
replication_config SceneReplicationConfig — 同步属性清单资源
replication_interval float 0.0 ALWAYS 模式下的同步间隔
delta_interval float 0.0 ON_CHANGE 模式下的增量同步间隔
public_visibility bool true 是否默认对所有对端可见
visibility_update_mode VisibilityUpdateMode 0 可见性过滤器更新时机

四、可见性控制:从全量广播到逐对端定制

默认的"同步给所有人"在很多场景下不够用(例如射击游戏中只想让玩家看到自己视野内的实体)。MultiplayerSynchronizer 提供了两套互补的可见性控制手段。

4.1 直接指定:set_visibility_for / get_visibility_for

set_visibility_for(peer: int, visible: bool)
get_visibility_for(peer: int) -> bool
  • set_visibility_for(peer_id, visible):把指定对端的可见性设为 visible;当 peer 传 0 时,等价于修改 public_visibility;
  • get_visibility_for(peer_id):查询当前对某对端的可见性。

这套 API 适合"规则简单、一次性设定"的场景,例如组队游戏中把己方队友设为可见、把敌方设为不可见。

4.2 运行时过滤:add_visibility_filter / remove_visibility_filter

add_visibility_filter(filter: Callable)
remove_visibility_filter(filter: Callable)

过滤器以 Callable(可调用对象)形式注册,该可调用对象应接收一个 peer ID(int)并返回一个 bool,返回 true 表示该对端可见。可以在一个同步器上注册多个过滤器,它们共同决定最终可见性。

4.3 触发更新:update_visibility

update_visibility(for_peer: int = 0)
  • 按过滤器更新 for_peer 的可见性;
  • 当 for_peer 为 0(默认值)时,更新所有对端的可见性。

它需要与 visibility_update_mode 配合理解:

  • 若 visibility_update_mode 为 VISIBILITY_PROCESS_IDLE 或 VISIBILITY_PROCESS_PHYSICS,框架会在对应帧自动调用过滤器更新,此时通常无需手动调用;
  • 若设为 VISIBILITY_PROCESS_NONE,过滤器不会自动更新,你必须自行调用 update_visibility()(例如在玩家位置变化或事件触发时)。

4.4 可见性变更通知:visibility_changed 信号

visibility_changed(for_peer: int)

当某个对端的可见性被更新时发出(携带对端 ID)。常用于驱动游戏逻辑,例如:敌人变为可见时创建其表现节点、变为不可见时回收节点。

五、VisibilityUpdateMode 枚举:过滤器何时运行

枚举值 值 更新时机
VISIBILITY_PROCESS_IDLE 0 在**处理帧(process frames)**中更新,对应 Node.NOTIFICATION_INTERNAL_PROCESS
VISIBILITY_PROCESS_PHYSICS 1 在**物理帧(physics frames)**中更新,对应 Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS
VISIBILITY_PROCESS_NONE 2 不自动更新,必须手动调用 update_visibility()

选择建议:与物理状态强相关(如位置、碰撞体)的可见性用 VISIBILITY_PROCESS_PHYSICS,与 UI、输入等逻辑相关的用 VISIBILITY_PROCESS_IDLE,对更新时机有精确控制需求的用 VISIBILITY_PROCESS_NONE + 手动触发。

六、同步完成信号:synchronized 与 delta_synchronized

信号 触发时机
synchronized() 收到新的同步(sync)状态且属性已更新后发出
delta_synchronized() 收到新的增量同步(delta sync)状态且属性已更新后发出

两者都在"属性已应用完毕"之后触发,因此非常适合作为插值(interpolation)、动画驱动或 UI 刷新的钩子。它们的区别对应前文两种复制模式:synchronized 关联 REPLICATION_MODE_ALWAYS 的常规同步,delta_synchronized 关联 REPLICATION_MODE_ON_CHANGE 的增量同步。

七、同步限制与注意事项

官方文档明确了两类不受支持的属性,规划同步方案前务必确认:

  1. Object 类型属性:例如 Resource 及其子类。资源作为属性值无法参与同步;
  2. 对端间唯一的属性:例如对象的实例 ID(见 Object.get_instance_id())与 RID。这类值在每个对端上各不相同,同步它们没有意义也不会生效。

另外值得注意:SceneMultiplayer 文档(class_scenemultiplayer.rst)提示高层多人协议是引擎实现细节,不保证向非 Godot 服务器开放,且可能随时变更;在做自定义服务器对接前要评估这一风险。

八、实战示例:玩家位置同步 + 视野可见性过滤

下面给出一个可直接上手的 GDScript 组合示例,串联本文全部核心概念:网络初始化(ENetMultiplayerPeer,详见 高层多人网络教程 的"Initializing the network"一节)、MultiplayerSynchronizer 属性同步与可见性过滤。

8.1 初始化网络(服务器/客户端)

# 服务器端:监听端口 7000,最多 8 个客户端
func _start_server():
    var peer := ENetMultiplayerPeer.new()
    var err := peer.create_server(7000, 8)
    if err != OK:
        return err
    multiplayer.multiplayer_peer = peer
    return OK

# 客户端:连接服务器
func _join_server(ip: String):
    var peer := ENetMultiplayerPeer.new()
    var err := peer.create_client(ip, 7000)
    if err != OK:
        return err
    multiplayer.multiplayer_peer = peer
    return OK

8.2 配置同步器并注册可见性过滤器

以"玩家角色"节点为例,其子节点挂载 MultiplayerSynchronizer,默认 root_path = NodePath("..") 正好指向玩家节点本身。在服务器侧完成属性清单与可见性配置:

# 假设 sync 是子节点上的 MultiplayerSynchronizer
func _setup_sync(sync: MultiplayerSynchronizer, player: Node3D):
    # 1) 配置同步属性:position、velocity 走 ALWAYS(不可靠、高频),health 走 ON_CHANGE(可靠、变化才发)
    var cfg := SceneReplicationConfig.new()
    cfg.add_property(NodePath(":position"))
    cfg.property_set_replication_mode(NodePath(":position"), \
            SceneReplicationConfig.REPLICATION_MODE_ALWAYS)
    cfg.add_property(NodePath(":velocity"))
    cfg.property_set_replication_mode(NodePath(":velocity"), \
            SceneReplicationConfig.REPLICATION_MODE_ALWAYS)
    cfg.add_property(NodePath(":health"))
    cfg.property_set_replication_mode(NodePath(":health"), \
            SceneReplicationConfig.REPLICATION_MODE_ON_CHANGE)

    sync.replication_config = cfg
    # ALWAYS 模式每 0.1 秒同步一次,控制带宽
    sync.replication_interval = 0.1
    # ON_CHANGE 模式的增量同步间隔
    sync.delta_interval = 0.05

    # 2) 可见性:只同步给与自己阵营相同的对端
    sync.public_visibility = false
    sync.add_visibility_filter(_is_same_team)
    # 物理帧驱动过滤器更新
    sync.visibility_update_mode = \
            MultiplayerSynchronizer.VisibilityUpdateMode.VISIBILITY_PROCESS_PHYSICS

    # 3) 监听同步完成,驱动插值
    sync.synchronized.connect(_on_synced)
    sync.delta_synchronized.connect(_on_delta_synced)
    sync.visibility_changed.connect(_on_visibility_changed)


func _is_same_team(peer_id: int) -> bool:
    return _teams.get(peer_id) == _my_team_id

8.3 动态调整可见性

需要临时屏蔽某个对端、或整体切换可见性时:

# 单独控制某个对端
sync.set_visibility_for(peer_id, false)

# peer 传 0 等价于修改 public_visibility
sync.set_visibility_for(0, true)

# 若 visibility_update_mode 为 VISIBILITY_PROCESS_NONE,
# 需在合适的时机手动刷新(for_peer 为 0 表示全部对端)
sync.update_visibility(0)

# 查询当前对某对端的可见性
if sync.get_visibility_for(peer_id):
    pass

需要强调的是:可见性的最终效果与 MultiplayerSpawner 联动——只有 root_path 节点由 MultiplayerSpawner 生成时,节点才会随可见性变化自动生成/销毁;如果是场景中静态存在的节点,可见性变化仅影响其属性数据是否下发。

九、小结

MultiplayerSynchronizer 是 Godot 高层多人 API 中"状态复制"的承载者,把开发者的同步负担从手写序列化/组包/发包中解放出来。本文要点回顾:

  • 同步什么:由 SceneReplicationConfig 属性清单决定,含 ALWAYS(不可靠、高频)与 ON_CHANGE(可靠、变化才发)两种复制模式;
  • 何时同步:由 replication_interval / delta_interval 控制,0.0 表示每个网络处理帧都同步;
  • 同步给谁:默认全量广播,可用 set_visibility_for、add_visibility_filter + update_visibility 做逐对端过滤,并由 visibility_update_mode 决定过滤器的刷新时机;
  • 如何联动:内部通过 MultiplayerAPI.object_configuration_add/remove 接入同步生命周期,与 MultiplayerSpawner 配合即可实现"按可见性生成节点"的完整场景复制方案。

上手建议:先在局域网(ENetMultiplayerPeer + 服务器/客户端初始化)中验证基础属性同步,再逐步引入可见性过滤与包大小调优(SceneMultiplayer.max_sync_packet_size、max_delta_packet_size),最后结合 Node.set_multiplayer_authority() 设计服务器权威逻辑,即可搭建出稳定、可控的联机状态同步层。

登录后查看全文
godot-docs