GFContentPackageManifest¶
API Reference / Extensions / Content Package / 类索引
- 路径：
addons/gf/extensions/content_package/resources/gf_content_package_manifest.gd - 模块：
Extensions / Content Package - 继承：
Resource - API：
public - 类别：资源定义 (
resource_definition) - 首次版本：
4.4.0
通用内容包 manifest。 描述一个内容包的稳定包 ID、版本、依赖和资源键映射。GF 只校验结构、路径安全和依赖关系， 不解释内容类型的业务语义，也不负责下载、启用策略或具体玩法规则。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 常量 | FILE_NAME |
const FILE_NAME: String = "gf_content_package.json" |
| 常量 | SCHEMA_VERSION |
const SCHEMA_VERSION: int = 1 |
| 常量 | SAFETY_KIND_DATA_ONLY |
const SAFETY_KIND_DATA_ONLY: StringName = &"data_only" |
| 常量 | SAFETY_KIND_TRUSTED_DEVELOPER |
const SAFETY_KIND_TRUSTED_DEVELOPER: StringName = &"trusted_developer" |
| 属性 | schema_version |
var schema_version: int = SCHEMA_VERSION |
| 属性 | package_id |
var package_id: StringName = &"" |
| 属性 | display_name |
var display_name: String = "" |
| 属性 | version |
var version: String = "" |
| 属性 | content_types |
var content_types: PackedStringArray = PackedStringArray() |
| 属性 | dependencies |
var dependencies: PackedStringArray = PackedStringArray() |
| 属性 | safety_kind |
var safety_kind: StringName = SAFETY_KIND_DATA_ONLY |
| 属性 | forbidden_resource_extensions |
var forbidden_resource_extensions: PackedStringArray = PackedStringArray() |
| 属性 | resources |
var resources: Array[Dictionary] = [] |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 属性 | root_path |
var root_path: String = "" |
| 属性 | source_path |
var source_path: String = "" |
| 方法 | configure |
func configure( p_package_id: StringName, p_version: String, p_resources: Array[Dictionary] = [], p_display_name: String = "", p_content_types: PackedStringArray = PackedStringArray(), p_dependencies: PackedStringArray = PackedStringArray(), p_metadata: Dictionary = {}, p_root_path: String = "", p_source_path: String = "", p_safety_kind: StringName = SAFETY_KIND_DATA_ONLY, p_forbidden_resource_extensions: PackedStringArray = PackedStringArray() ) -> GFContentPackageManifest: |
| 方法 | apply_dictionary |
func apply_dictionary(data: Dictionary, p_root_path: String = "", p_source_path: String = "") -> void: |
| 方法 | to_dictionary |
func to_dictionary() -> Dictionary: |
| 方法 | to_report_dictionary |
func to_report_dictionary(options: Dictionary = {}) -> Dictionary: |
| 方法 | duplicate_manifest |
func duplicate_manifest() -> GFContentPackageManifest: |
| 方法 | is_valid |
func is_valid(options: Dictionary = {}) -> bool: |
| 方法 | get_validation_report |
func get_validation_report(options: Dictionary = {}) -> Dictionary: |
| 方法 | get_validation_errors |
func get_validation_errors(options: Dictionary = {}) -> Array[String]: |
| 方法 | get_normalized_resources |
func get_normalized_resources() -> Array[Dictionary]: |
| 方法 | get_resource_keys |
func get_resource_keys() -> PackedStringArray: |
| 方法 | from_dictionary |
static func from_dictionary( data: Dictionary, p_root_path: String = "", p_source_path: String = "" ) -> GFContentPackageManifest: |
| 方法 | load_from_path |
static func load_from_path(path: String) -> GFContentPackageManifest: |
常量¶
FILE_NAME¶
- API：
public
内容包 JSON manifest 默认文件名。
SCHEMA_VERSION¶
- API：
public
当前 manifest schema 版本。
SAFETY_KIND_DATA_ONLY¶
- API：
public - 首次版本：
6.0.0
只允许数据资源的内容包安全分类。
SAFETY_KIND_TRUSTED_DEVELOPER¶
- API：
public - 首次版本：
6.0.0
允许开发者代码资源的内容包安全分类。
属性¶
schema_version¶
- API：
public - 首次版本：
6.0.0
manifest schema 版本。JSON manifest 必须显式声明当前支持的版本。
package_id¶
- API：
public
稳定内容包 ID。
display_name¶
- API：
public
编辑器或诊断显示名。
version¶
- API：
public
内容包版本字符串。
content_types¶
- API：
public
内容类型标签。GF 只做归一化和诊断，不解释业务语义。
dependencies¶
- API：
public
依赖内容包 ID 列表。
safety_kind¶
- API：
public - 首次版本：
6.0.0
内容包安全分类。data_only 默认拒绝脚本、shader、GDExtension 和可执行文件。
forbidden_resource_extensions¶
- API：
public - 首次版本：
6.0.0
调用方额外禁止的资源扩展名，不需要前导点。
resources¶
- API：
public
资源键映射列表。
结构：
resources: Array[Dictionary]，每项包含 key、path、可选 type_hint、priority 和 metadata。
metadata¶
- API：
public
项目自定义元数据。GF 不解释其中业务字段。
结构：
metadata: Dictionary project-defined content package metadata.
root_path¶
- API：
public
manifest 所在内容包根目录。通常由加载路径推导。
source_path¶
- API：
public
manifest 文件路径。通常指向 gf_content_package.json。
方法¶
configure¶
- API：
public - 首次版本：
6.0.0
func configure( p_package_id: StringName, p_version: String, p_resources: Array[Dictionary] = [], p_display_name: String = "", p_content_types: PackedStringArray = PackedStringArray(), p_dependencies: PackedStringArray = PackedStringArray(), p_metadata: Dictionary = {}, p_root_path: String = "", p_source_path: String = "", p_safety_kind: StringName = SAFETY_KIND_DATA_ONLY, p_forbidden_resource_extensions: PackedStringArray = PackedStringArray() ) -> GFContentPackageManifest:
配置 manifest。
参数：
| 名称 | 说明 |
|---|---|
p_package_id |
稳定内容包 ID。 |
p_version |
内容包版本。 |
p_resources |
资源键映射列表。 |
p_display_name |
可选显示名。 |
p_content_types |
内容类型标签。 |
p_dependencies |
依赖内容包 ID 列表。 |
p_metadata |
项目自定义元数据。 |
p_root_path |
内容包根目录。 |
p_source_path |
manifest 文件路径。 |
p_safety_kind |
内容包安全分类。 |
p_forbidden_resource_extensions |
调用方额外禁止的资源扩展名。 |
返回：当前 manifest。
结构：
p_resources: Array[Dictionary]，每项包含 key、path、可选 type_hint、priority 和 metadata。p_metadata: Dictionary project-defined content package metadata.p_forbidden_resource_extensions: PackedStringArray extension names without leading dots.
apply_dictionary¶
- API：
public - 首次版本：
4.4.0
func apply_dictionary(data: Dictionary, p_root_path: String = "", p_source_path: String = "") -> void:
从字典应用 manifest 字段。
参数：
| 名称 | 说明 |
|---|---|
data |
manifest 字典。 |
p_root_path |
内容包根目录。 |
p_source_path |
manifest 文件路径。 |
结构：
data: Dictionary，支持 package_id/id、display_name/name、version、content_types、dependencies、safety_kind、forbidden_resource_extensions、resources 和 metadata；字段类型必须与 manifest schema 一致，不执行字符串、数组或字典宽松转换。
to_dictionary¶
- API：
public
转换为内容包 manifest 字典。
返回：manifest 字典副本。
结构：
return: Dictionary，包含 schema_version、package_id、display_name、version、content_types、dependencies、resources 和 metadata。
to_report_dictionary¶
- API：
public - 首次版本：
8.0.0
转换为 JSON-safe 报告字典。
参数：
| 名称 | 说明 |
|---|---|
options |
传给 GFReportValueCodec 的编码选项。 |
返回：manifest 报告字典。
结构：
options: Dictionary with GFReportValueCodec encoding options.return: JSON-safe Dictionary based on to_dictionary().
duplicate_manifest¶
- API：
public
创建 manifest 深拷贝。
返回：新 manifest。
is_valid¶
- API：
public - 首次版本：
4.4.0
检查 manifest 是否有效。
参数：
| 名称 | 说明 |
|---|---|
options |
校验选项。可启用文件存在性与传递依赖安全扫描。 |
返回：无 error issue 时返回 true。
结构：
options: Dictionary，可包含 check_resource_exists: bool、check_resource_dependencies: bool 和 dependency_options: Dictionary。
get_validation_report¶
- API：
public - 首次版本：
4.4.0
获取 manifest 校验报告。
参数：
| 名称 | 说明 |
|---|---|
options |
校验选项。可启用文件存在性与传递依赖安全扫描。 |
返回：GFValidationReportDictionary 兼容报告。
结构：
options: Dictionary，可包含 check_resource_exists: bool、check_resource_dependencies: bool 和 dependency_options: Dictionary。return: GFValidationReportDictionary.finalize_report() 生成的 Dictionary，包含 ok、healthy、summary、issues、next_action、error_count、warning_count、issue_count、package_id、source_path 和 resource_count。
get_validation_errors¶
- API：
public - 首次版本：
4.4.0
获取校验错误文本列表。
参数：
| 名称 | 说明 |
|---|---|
options |
校验选项。可启用文件存在性与传递依赖安全扫描。 |
返回：错误文本列表。
结构：
options: Dictionary，可包含 check_resource_exists: bool、check_resource_dependencies: bool 和 dependency_options: Dictionary。
get_normalized_resources¶
- API：
public
获取归一化资源键映射。
返回：资源映射副本。
结构：
return: Array[Dictionary]，每项包含 key、path、type_hint、priority、metadata 和 package_id。
get_resource_keys¶
- API：
public
获取 manifest 中声明的资源键列表。
返回：排序后的资源键列表。
from_dictionary¶
- API：
public - 首次版本：
4.4.0
static func from_dictionary( data: Dictionary, p_root_path: String = "", p_source_path: String = "" ) -> GFContentPackageManifest:
从字典创建 manifest。
参数：
| 名称 | 说明 |
|---|---|
data |
manifest 字典。 |
p_root_path |
内容包根目录。 |
p_source_path |
manifest 文件路径。 |
返回：新 manifest。
结构：
data: Dictionary，支持 package_id/id、display_name/name、version、content_types、dependencies、safety_kind、forbidden_resource_extensions、resources 和 metadata；字段类型必须与 manifest schema 一致。
load_from_path¶
- API：
public
从 JSON manifest 文件加载内容包。
参数：
| 名称 | 说明 |
|---|---|
path |
manifest 文件路径。 |
返回：加载成功返回 manifest；解析失败返回 null。