最后同步日期：2026-04-15 | Godot 官方原文 — var_to_bytes_with_objects

var_to_bytes_with_objects

定义

var_to_bytes_with_objects() 和 var_to_bytes() 的作用一样，都是把数据打包成字节数组。但它有一个重要的额外能力：能够序列化包含对象引用的数据。

打个比方：普通的 var_to_bytes() 只能打包"纯物品"——衣服、书本、零食（数字、字符串、数组这些纯数据）。但如果你要寄一个包裹，里面附了一张写着"回寄地址"的小卡片（对象引用），普通快递就不行了。var_to_bytes_with_objects() 就是"支持带地址卡片的快递"——它能连同对象引用一起打包进去。

收到包裹后，需要用配套的 bytes_to_var_with_objects() 来拆开，而不是普通的 bytes_to_var()。

函数签名

C#

// C# 中可使用 GodotObject 的静态方法
public static byte[] VarToBytesWithObjects(Variant variable)

// 也可通过 GD 全局访问
byte[] bytes = GD.VarToBytesWithObjects(myVariant);

GDScript

func var_to_bytes_with_objects(variable: Variant) -> PackedByteArray

参数说明

参数	类型	必需	说明
variable	Variant	是	要序列化的值，可以包含对象引用（如节点实例、资源对象等）

返回值

PackedByteArray（字节数组）—— 将输入值及其中的对象引用一起编码后得到的二进制数据。

代码示例

C#

using Godot;

public partial class VarToBytesWithObjectsExample : Node
{
    public override void _Ready()
    {
        // 普通数据（不含对象）也可以用这个函数打包
        var _simpleData = new Godot.Collections.Dictionary
        {
            ["name"] = "勇者",
            ["level"] = 5
        };
        byte[] _simpleBytes = GD.VarToBytesWithObjects(Variant.From(_simpleData));
        GD.Print("普通数据打包完成");

        // 包含对象引用的数据：字典中存了一个节点引用
        var _playerNode = GetNode<Node>("Player");
        var _dataWithObject = new Godot.Collections.Dictionary
        {
            ["player_ref"] = _playerNode,
            ["position_x"] = 100.0f,
            ["position_y"] = 200.0f
        };
        byte[] _objBytes = GD.VarToBytesWithObjects(Variant.From(_dataWithObject));
        GD.Print($"包含对象的数据打包完成，字节长度: {_objBytes.Length}");

        // 用配套的 bytes_to_var_with_objects 还原
        var _restored = GD.BytesToVarWithObjects(Variant.From(_objBytes));
        GD.Print($"还原成功: {_restored}");

        // 注意：还原后得到的 player_ref 仍然是同一个对象实例
        // （前提是对象在反序列化时仍然存在）
    }
}

GDScript

extends Node

func _ready():
	# 普通数据（不含对象）也可以用这个函数打包
	var _simple_data = {
		"name": "勇者",
		"level": 5
	}
	var _simple_bytes = var_to_bytes_with_objects(_simple_data)
	print("普通数据打包完成")

	# 包含对象引用的数据：字典中存了一个节点引用
	var _player_node = get_node("Player")
	var _data_with_object = {
		"player_ref": _player_node,
		"position_x": 100.0,
		"position_y": 200.0
	}
	var _obj_bytes = var_to_bytes_with_objects(_data_with_object)
	print("包含对象的数据打包完成，字节长度: ", _obj_bytes.size())

	# 用配套的 bytes_to_var_with_objects 还原
	var _restored = bytes_to_var_with_objects(_obj_bytes)
	print("还原成功: ", _restored)

	# 注意：还原后得到的 player_ref 仍然是同一个对象实例
	# （前提是对象在反序列化时仍然存在）

	# 对比：如果用普通的 var_to_bytes 打包含对象的数据
	# 对象引用信息会丢失
	var _bad_bytes = var_to_bytes(_data_with_object)
	var _bad_restored = bytes_to_var(_bad_bytes)
	print("普通方式打包含对象的数据，player_ref 会变成: ", _bad_restored["player_ref"])
	# 输出可能是 null 或空值

注意事项

• 用 var_to_bytes_with_objects() 打包的数据，必须用 bytes_to_var_with_objects() 来还原，不能混用普通的 bytes_to_var()。
• 对象引用在序列化时保存的是对象的运行时标识（ID），而不是对象本身的完整数据。因此，反序列化时原始对象必须仍然存在于内存中，否则引用会失效（变成 null）。
• 如果你打包的数据中不包含任何对象引用，建议使用普通的 var_to_bytes()，它更轻量、更快。
• 在 C# 中，调用 GD.VarToBytesWithObjects() 时需要先将值转换为 Variant 类型，可以使用 Variant.From(value) 来完成。
• 此函数最典型的使用场景是网络多人游戏中同步带有对象引用的游戏状态，或者在内存中临时保存和恢复复杂的数据结构。