GFVariantData

API Reference / Standard / 类索引

• 路径：addons/gf/standard/foundation/variant/gf_variant_data.gd
• 模块：Standard
• 继承：RefCounted
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：3.17.0

通用 Variant 数据复制与默认值合并。 提供不依赖 GFArchitecture 的集合复制、Resource 可选复制、差异报告和默认值递归补齐。 JSON 兼容编码由 GFVariantJsonCodec 负责。

成员概览

类型	名称	签名
方法	duplicate_variant	static func duplicate_variant(value: Variant, deep: bool = true, duplicate_resources: bool = false) -> Variant:
方法	duplicate_collection	static func duplicate_collection(value: Variant, deep: bool = true) -> Variant:
方法	to_dictionary	static func to_dictionary(value: Variant, default_value: Dictionary = {}, deep: bool = true) -> Dictionary:
方法	as_dictionary	static func as_dictionary(value: Variant, default_value: Variant = null) -> Dictionary:
方法	to_array	static func to_array(value: Variant, default_value: Array = [], deep: bool = true) -> Array:
方法	as_array	static func as_array(value: Variant, default_value: Variant = null) -> Array:
方法	to_bool	static func to_bool(value: Variant, default_value: bool = false) -> bool:
方法	to_int	static func to_int(value: Variant, default_value: int = 0) -> int:
方法	is_exact_integer	static func is_exact_integer(value: Variant) -> bool:
方法	to_exact_int	static func to_exact_int(value: Variant, default_value: int = 0) -> int:
方法	to_float	static func to_float(value: Variant, default_value: float = 0.0) -> float:
方法	to_text	static func to_text(value: Variant, default_value: String = "") -> String:
方法	to_string_name	static func to_string_name(value: Variant, default_value: StringName = &"") -> StringName:
方法	to_vector2	static func to_vector2(value: Variant, default_value: Vector2 = Vector2.ZERO) -> Vector2:
方法	to_vector3	static func to_vector3(value: Variant, default_value: Vector3 = Vector3.ZERO) -> Vector3:
方法	to_string_array	static func to_string_array(value: Variant, default_value: Array[String] = []) -> Array[String]:
方法	to_string_name_array	static func to_string_name_array(value: Variant, default_value: Array[StringName] = []) -> Array[StringName]:
方法	to_int_array	static func to_int_array(value: Variant, default_value: Array[int] = []) -> Array[int]:
方法	duplicate_metadata	static func duplicate_metadata(metadata: Dictionary) -> Dictionary:
方法	values_equal	static func values_equal(left: Variant, right: Variant, options: Dictionary = {}) -> bool:
方法	merge_dictionary	static func merge_dictionary( target: Dictionary, source: Dictionary, overwrite: bool = true, recursive: bool = true ) -> Dictionary:
方法	merge_metadata	static func merge_metadata( target: Dictionary, source: Dictionary, overwrite: bool = true, recursive: bool = true ) -> Dictionary:
方法	deep_merge_defaults	static func deep_merge_defaults(base: Dictionary, defaults: Dictionary) -> Dictionary:
方法	diff_variant	static func diff_variant(before: Variant, after: Variant, options: Dictionary = {}) -> Dictionary:
方法	get_option_value	static func get_option_value(options: Dictionary, key: Variant, default_value: Variant = null) -> Variant:
方法	get_option_bool	static func get_option_bool(options: Dictionary, key: Variant, default_value: bool = false) -> bool:
方法	get_option_int	static func get_option_int(options: Dictionary, key: Variant, default_value: int = 0) -> int:
方法	get_option_float	static func get_option_float(options: Dictionary, key: Variant, default_value: float = 0.0) -> float:
方法	get_option_string	static func get_option_string(options: Dictionary, key: Variant, default_value: String = "") -> String:
方法	get_option_string_name	static func get_option_string_name(options: Dictionary, key: Variant, default_value: StringName = &"") -> StringName:
方法	get_option_vector2	static func get_option_vector2(options: Dictionary, key: Variant, default_value: Vector2 = Vector2.ZERO) -> Vector2:
方法	get_option_vector3	static func get_option_vector3(options: Dictionary, key: Variant, default_value: Vector3 = Vector3.ZERO) -> Vector3:
方法	get_option_dictionary	static func get_option_dictionary(options: Dictionary, key: Variant, default_value: Dictionary = {}) -> Dictionary:
方法	get_option_array	static func get_option_array(options: Dictionary, key: Variant, default_value: Array = []) -> Array:
方法	get_option_string_array	static func get_option_string_array( options: Dictionary, key: Variant, default_value: Array[String] = [] ) -> Array[String]:
方法	get_option_string_name_array	static func get_option_string_name_array( options: Dictionary, key: Variant, default_value: Array[StringName] = [] ) -> Array[StringName]:
方法	get_option_int_array	static func get_option_int_array( options: Dictionary, key: Variant, default_value: Array[int] = [] ) -> Array[int]:
方法	get_option_packed_string_array	static func get_option_packed_string_array( options: Dictionary, key: Variant, default_value: PackedStringArray = PackedStringArray() ) -> PackedStringArray:

方法

duplicate_variant

• API：public

static func duplicate_variant(value: Variant, deep: bool = true, duplicate_resources: bool = false) -> Variant:

深拷贝 Dictionary 或 Array；其他 Variant 原样返回。

参数：

名称	说明
value	待复制的值。
deep	是否深拷贝集合或 Resource。
duplicate_resources	是否复制 Resource；默认为 false 以保留引用语义。

返回：复制后的值。

结构：

• value: 待复制的 Variant 值。
• return: 复制后的 Variant 值。

duplicate_collection

• API：public

static func duplicate_collection(value: Variant, deep: bool = true) -> Variant:

深拷贝集合值；语义同 duplicate_variant()，便于集合字段调用处表达意图。

参数：

名称	说明
value	待复制的值。
deep	是否深拷贝集合。

返回：复制后的值。

结构：

• value: 待复制的 Variant 集合值。
• return: 复制后的 Variant 集合值。

to_dictionary

• API：public

static func to_dictionary(value: Variant, default_value: Dictionary = {}, deep: bool = true) -> Dictionary:

将 Variant 归一为 Dictionary 副本。

参数：

名称	说明
value	待读取的值。
default_value	value 不是 Dictionary 时使用的默认值。
deep	是否深拷贝集合。

返回：Dictionary 副本。

结构：

• value: 期望为 Dictionary 的 Variant 值。
• default_value: value 不是 Dictionary 时复制的默认 Dictionary。
• return: 复制后的 Dictionary 结果。

as_dictionary

• API：public

static func as_dictionary(value: Variant, default_value: Variant = null) -> Dictionary:

将 Variant 收窄为 Dictionary 引用；value 不是 Dictionary 时返回 default_value 引用。

参数：

名称	说明
value	待读取的值。
default_value	value 不是 Dictionary 时使用的默认值；不是 Dictionary 时忽略。

返回：Dictionary 引用。

结构：

• value: 期望为 Dictionary 的 Variant 值。
• default_value: 为 Dictionary 时按引用返回的 Variant 兜底值。
• return: 收窄后的 Dictionary 结果。

to_array

• API：public

static func to_array(value: Variant, default_value: Array = [], deep: bool = true) -> Array:

将 Variant 归一为 Array 副本。

参数：

名称	说明
value	待读取的值。
default_value	value 不是 Array 时使用的默认值。
deep	是否深拷贝集合。

返回：Array 副本。

结构：

• value: 期望为 Array 的 Variant 值。
• default_value: value 不是 Array 时复制的默认 Array。
• return: 复制后的 Array 结果。

as_array

• API：public

static func as_array(value: Variant, default_value: Variant = null) -> Array:

将 Variant 收窄为 Array 引用；value 不是 Array 时返回 default_value 引用。

参数：

名称	说明
value	待读取的值。
default_value	value 不是 Array 时使用的默认值；不是 Array 时忽略。

返回：Array 引用。

结构：

• value: 期望为 Array 的 Variant 值。
• default_value: 为 Array 时按引用返回的 Variant 兜底值。
• return: 收窄后的 Array 结果。

to_bool

• API：public

static func to_bool(value: Variant, default_value: bool = false) -> bool:

将 Variant 安全归一为 bool。

参数：

名称	说明
value	待读取的值。
default_value	无法安全归一时返回的默认值。

返回：bool 值。

结构：

• value: 期望可表示 bool 的 Variant 值。

to_int

• API：public

static func to_int(value: Variant, default_value: int = 0) -> int:

将 Variant 安全归一为 int。

参数：

名称	说明
value	待读取的值。
default_value	无法安全归一时返回的默认值。

返回：int 值。

结构：

• value: 期望可表示 int 的 Variant 值。

is_exact_integer

• API：public
• 首次版本：9.0.0

static func is_exact_integer(value: Variant) -> bool:

检查 Variant 是否为可无损解释为整数的数值。 接受 int，以及 JSON 解析产生的有限、无小数且位于安全整数范围内的 float。 不接受 bool、字符串、NaN、Infinity 或带小数的 float。

参数：

名称	说明
value	待检查的值。

返回：可无损解释为整数时返回 true。

结构：

• value: Variant expected to be an int or an exact JSON integer number.

to_exact_int

• API：public
• 首次版本：9.0.0

static func to_exact_int(value: Variant, default_value: int = 0) -> int:

将精确整数 Number 转为 int。 与宽松 to_int() 不同，该方法不会接受 bool 或文本，也不会截断小数。

参数：

名称	说明
value	待转换的精确整数 Number。
default_value	输入不满足精确整数约束时返回的值。

返回：精确整数或 default_value。

结构：

• value: Variant accepted by is_exact_integer().

to_float

• API：public

static func to_float(value: Variant, default_value: float = 0.0) -> float:

将 Variant 安全归一为 float。

参数：

名称	说明
value	待读取的值。
default_value	无法安全归一时返回的默认值。

返回：float 值。

结构：

• value: 期望可表示 float 的 Variant 值。

to_text

• API：public

static func to_text(value: Variant, default_value: String = "") -> String:

将 Variant 归一为 String。

参数：

名称	说明
value	待读取的值。
default_value	value 为 null 时返回的默认值。

返回：String 值。

结构：

• value: 期望可表示文本的 Variant 值。

to_string_name

• API：public

static func to_string_name(value: Variant, default_value: StringName = &"") -> StringName:

将 Variant 归一为 StringName。

参数：

名称	说明
value	待读取的值。
default_value	value 为 null 时返回的默认值。

返回：StringName 值。

结构：

• value: 期望可表示 StringName 的 Variant 值。

to_vector2

• API：public

static func to_vector2(value: Variant, default_value: Vector2 = Vector2.ZERO) -> Vector2:

将 Variant 归一为 Vector2。

参数：

名称	说明
value	待读取的值。
default_value	无法安全归一时返回的默认值。

返回：Vector2 值。

结构：

• value: 期望可表示 Vector2 的 Variant 值。

to_vector3

• API：public

static func to_vector3(value: Variant, default_value: Vector3 = Vector3.ZERO) -> Vector3:

将 Variant 归一为 Vector3。

参数：

名称	说明
value	待读取的值。
default_value	无法安全归一时返回的默认值。

返回：Vector3 值。

结构：

• value: 期望可表示 Vector3 的 Variant 值。

to_string_array

• API：public

static func to_string_array(value: Variant, default_value: Array[String] = []) -> Array[String]:

将 Variant 归一为 String 数组副本。

参数：

名称	说明
value	待读取的值。
default_value	无法安全归一时返回的默认数组。

返回：String 数组副本。

结构：

• value: 期望可表示 String 值集合的 Variant。
• default_value: value 无法收窄时复制的默认 Array[String]。
• return: 收窄后的 Array[String] 结果。

to_string_name_array

• API：public

static func to_string_name_array(value: Variant, default_value: Array[StringName] = []) -> Array[StringName]:

将 Variant 归一为 StringName 数组副本。

参数：

名称	说明
value	待读取的值。
default_value	无法安全归一时返回的默认数组。

返回：StringName 数组副本。

结构：

• value: 期望可表示 StringName 值集合的 Variant。
• default_value: value 无法收窄时复制的默认 Array[StringName]。
• return: 收窄后的 Array[StringName] 结果。

to_int_array

• API：public

static func to_int_array(value: Variant, default_value: Array[int] = []) -> Array[int]:

将 Variant 归一为 int 数组副本。

参数：

名称	说明
value	待读取的值。
default_value	无法安全归一时返回的默认数组。

返回：int 数组副本。

结构：

• value: 期望可表示 int 值集合的 Variant。
• default_value: value 无法收窄时复制的默认 Array[int]。
• return: 收窄后的 Array[int] 结果。

duplicate_metadata

• API：public

static func duplicate_metadata(metadata: Dictionary) -> Dictionary:

复制元数据字典。

参数：

名称	说明
metadata	待复制的元数据。

返回：元数据副本。

结构：

• metadata: 调用方元数据 Dictionary。
• return: 复制后的元数据 Dictionary。

values_equal

• API：public
• 首次版本：6.0.0

static func values_equal(left: Variant, right: Variant, options: Dictionary = {}) -> bool:

安全比较两个 Variant 值是否等价。 默认只在类型相同或 int/float 数值类型互比时返回 true。需要容忍浮点误差时可传入 numeric_epsilon。

参数：

名称	说明
left	左值。
right	右值。
options	比较选项。支持 numeric_epsilon 和 match_string_names。

返回：两个值按 GF 通用 Variant 语义等价时返回 true。

结构：

• left: Variant comparison value.
• right: Variant comparison value.
• options: Dictionary，可选字段：numeric_epsilon 为 int/float 误差，默认 0；match_string_names 为 true 时 String 与 StringName 按文本比较。

merge_dictionary

• API：public

static func merge_dictionary( target: Dictionary, source: Dictionary, overwrite: bool = true, recursive: bool = true ) -> Dictionary:

将 source 合并到 target。 String 与 StringName 等价键会复用 target 中已有字段，避免重复键。

参数：

名称	说明
target	会被原地修改的目标字典。
source	来源字典。
overwrite	为 true 时覆盖已有字段。
recursive	为 true 时递归合并嵌套 Dictionary。

返回：已合并的 target 字典。

结构：

• target: 会被原地修改的目标 Dictionary。
• source: 会复制到目标中的来源 Dictionary 值。
• return: 合并后的目标 Dictionary。

merge_metadata

• API：public

static func merge_metadata( target: Dictionary, source: Dictionary, overwrite: bool = true, recursive: bool = true ) -> Dictionary:

将 source 元数据合并到 target 元数据。

参数：

名称	说明
target	会被原地修改的目标元数据。
source	来源元数据。
overwrite	为 true 时覆盖已有字段。
recursive	为 true 时递归合并嵌套 Dictionary。

返回：已合并的 target 元数据。

结构：

• target: 会被原地修改的元数据 Dictionary。
• source: 会复制到目标中的元数据 Dictionary。
• return: 合并后的元数据 Dictionary。

deep_merge_defaults

• API：public

static func deep_merge_defaults(base: Dictionary, defaults: Dictionary) -> Dictionary:

将 defaults 中缺失的字段递归合并到 base。

参数：

名称	说明
base	会被原地补齐的目标字典。
defaults	默认值字典。

返回：已补齐的 base 字典。

结构：

• base: 会被原地修改的目标 Dictionary。
• defaults: 会合并到 base 中的默认 Dictionary 值。
• return: 合并后的 base Dictionary。

diff_variant

• API：public

static func diff_variant(before: Variant, after: Variant, options: Dictionary = {}) -> Dictionary:

对比两个 Variant 并返回结构化差异报告。 该方法只比较纯 Variant 数据形状，不读取文件、不实例化脚本，也不解释业务字段。

参数：

名称	说明
before	变更前的 Variant 值。
after	变更后的 Variant 值。
options	可选项。支持 max_changes、copy_values。

返回：差异报告。包含 changed、change_count、truncated、max_changes 与 changes。

结构：

• before: 待比较的 Variant 值。
• after: 待比较的 Variant 值。
• options: Dictionary，可选字段：max_changes 为最多记录差异数，默认 1024，<=0 表示不限；copy_values 默认为 true。
• return: Dictionary；changes 每项包含 kind、path、path_segments、old_value、new_value、old_type、new_type。kind 为 added、removed、changed 或 type_changed。

get_option_value

• API：public

static func get_option_value(options: Dictionary, key: Variant, default_value: Variant = null) -> Variant:

读取 options 字典中的原始值，支持 String 与 StringName 键互查。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：读取到的值或默认值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。
• default_value: Variant 默认值。
• return: Variant 选项值或默认值。

get_option_bool

• API：public

static func get_option_bool(options: Dictionary, key: Variant, default_value: bool = false) -> bool:

读取 bool 选项。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：bool 值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。

get_option_int

• API：public

static func get_option_int(options: Dictionary, key: Variant, default_value: int = 0) -> int:

读取 int 选项。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：int 值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。

get_option_float

• API：public

static func get_option_float(options: Dictionary, key: Variant, default_value: float = 0.0) -> float:

读取 float 选项。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：float 值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。

get_option_string

• API：public

static func get_option_string(options: Dictionary, key: Variant, default_value: String = "") -> String:

读取 String 选项。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：String 值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。

get_option_string_name

• API：public

static func get_option_string_name(options: Dictionary, key: Variant, default_value: StringName = &"") -> StringName:

读取 StringName 选项。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：StringName 值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。

get_option_vector2

• API：public

static func get_option_vector2(options: Dictionary, key: Variant, default_value: Vector2 = Vector2.ZERO) -> Vector2:

读取 Vector2 选项。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：Vector2 值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。

get_option_vector3

• API：public

static func get_option_vector3(options: Dictionary, key: Variant, default_value: Vector3 = Vector3.ZERO) -> Vector3:

读取 Vector3 选项。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：Vector3 值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。

get_option_dictionary

• API：public

static func get_option_dictionary(options: Dictionary, key: Variant, default_value: Dictionary = {}) -> Dictionary:

读取 Dictionary 选项副本。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：Dictionary 副本。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。
• default_value: 选项不是 Dictionary 时复制的默认 Dictionary。
• return: Dictionary 选项值。

get_option_array

• API：public

static func get_option_array(options: Dictionary, key: Variant, default_value: Array = []) -> Array:

读取 Array 选项副本。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：Array 副本。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。
• default_value: 选项不是 Array 时复制的默认 Array。
• return: Array 选项值。

get_option_string_array

• API：public

static func get_option_string_array( options: Dictionary, key: Variant, default_value: Array[String] = [] ) -> Array[String]:

读取 String 数组选项副本。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认数组。

返回：String 数组副本。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。
• default_value: 选项无法收窄时复制的默认 Array[String]。
• return: Array[String] 选项值。

get_option_string_name_array

• API：public

static func get_option_string_name_array( options: Dictionary, key: Variant, default_value: Array[StringName] = [] ) -> Array[StringName]:

读取 StringName 数组选项副本。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认数组。

返回：StringName 数组副本。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。
• default_value: 选项无法收窄时复制的默认 Array[StringName]。
• return: Array[StringName] 选项值。

get_option_int_array

• API：public

static func get_option_int_array( options: Dictionary, key: Variant, default_value: Array[int] = [] ) -> Array[int]:

读取 int 数组选项副本。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认数组。

返回：int 数组副本。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。
• default_value: 选项无法收窄时复制的默认 Array[int]。
• return: Array[int] 选项值。

get_option_packed_string_array

• API：public

static func get_option_packed_string_array( options: Dictionary, key: Variant, default_value: PackedStringArray = PackedStringArray() ) -> PackedStringArray:

读取 PackedStringArray 选项。

参数：

名称	说明
options	可选项字典。
key	字段名，可传 String 或 StringName。
default_value	缺少字段时返回的默认值。

返回：PackedStringArray 值。

结构：

• options: 选项载荷 Dictionary。
• key: Variant 选项键。