Godot 4 MultiplayerSynchronizer 深度解析:属性同步与按需可见性控制
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 的通知机制触发的。官方文档明确说明:
- 同步开始时,它调用 MultiplayerAPI.object_configuration_add(),把
root_path指向的节点作为object、把自身作为configuration传入; - 同步结束时,以同样方式调用 MultiplayerAPI.object_configuration_remove()。
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 的增量同步。
七、同步限制与注意事项
官方文档明确了两类不受支持的属性,规划同步方案前务必确认:
Object类型属性:例如Resource及其子类。资源作为属性值无法参与同步;- 对端间唯一的属性:例如对象的实例 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() 设计服务器权威逻辑,即可搭建出稳定、可控的联机状态同步层。