GFExtensionSettings¶
API Reference / Kernel / 类索引
- 路径：
addons/gf/kernel/extension/gf_extension_settings.gd - 模块：
Kernel - 继承：
RefCounted - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
GF 扩展启用状态与 ProjectSettings 桥接。 负责读取启用扩展 ID、解析扩展依赖、收集启用扩展 Installer，以及提供导出排除开关。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 常量 | ENABLED_EXTENSIONS_SETTING |
const ENABLED_EXTENSIONS_SETTING: String = "gf/extensions/enabled" |
| 常量 | AUTO_INSTALL_ENABLED_INSTALLERS_SETTING |
const AUTO_INSTALL_ENABLED_INSTALLERS_SETTING: String = "gf/extensions/auto_install_enabled_installers" |
| 常量 | EXPORT_EXCLUDE_DISABLED_SETTING |
const EXPORT_EXCLUDE_DISABLED_SETTING: String = "gf/extensions/export_exclude_disabled" |
| 常量 | EXPORT_FAIL_ON_DISABLED_REFERENCES_SETTING |
const EXPORT_FAIL_ON_DISABLED_REFERENCES_SETTING: String = "gf/extensions/export_fail_on_disabled_references" |
| 常量 | AUTO_INSTALL_ENABLED_INSTALLERS_DEFAULT |
const AUTO_INSTALL_ENABLED_INSTALLERS_DEFAULT: bool = true |
| 常量 | EXPORT_EXCLUDE_DISABLED_DEFAULT |
const EXPORT_EXCLUDE_DISABLED_DEFAULT: bool = true |
| 常量 | EXPORT_FAIL_ON_DISABLED_REFERENCES_DEFAULT |
const EXPORT_FAIL_ON_DISABLED_REFERENCES_DEFAULT: bool = true |
| 常量 | BUILT_IN_EXTENSION_IDS |
const BUILT_IN_EXTENSION_IDS: Array[String] = [ |
| 方法 | ensure_defaults |
static func ensure_defaults() -> bool: |
| 方法 | register_property_info |
static func register_property_info() -> void: |
| 方法 | get_default_enabled_extension_ids |
static func get_default_enabled_extension_ids() -> Array[String]: |
| 方法 | get_enabled_extension_ids |
static func get_enabled_extension_ids() -> Array[String]: |
| 方法 | set_enabled_extension_ids |
static func set_enabled_extension_ids(extension_ids: Array[String], include_dependencies: bool = true) -> void: |
| 方法 | should_auto_install_enabled_installers |
static func should_auto_install_enabled_installers() -> bool: |
| 方法 | set_auto_install_enabled_installers |
static func set_auto_install_enabled_installers(enabled: bool) -> void: |
| 方法 | should_export_exclude_disabled_extensions |
static func should_export_exclude_disabled_extensions() -> bool: |
| 方法 | set_export_exclude_disabled_extensions |
static func set_export_exclude_disabled_extensions(enabled: bool) -> void: |
| 方法 | should_fail_export_on_disabled_extension_references |
static func should_fail_export_on_disabled_extension_references() -> bool: |
| 方法 | set_fail_export_on_disabled_extension_references |
static func set_fail_export_on_disabled_extension_references(enabled: bool) -> void: |
| 方法 | get_all_manifests |
static func get_all_manifests() -> Array[GFExtensionManifest]: |
| 方法 | clear_manifest_cache |
static func clear_manifest_cache() -> void: |
| 方法 | get_manifest_by_id |
static func get_manifest_by_id(extension_id: String) -> GFExtensionManifest: |
| 方法 | has_extension |
static func has_extension(extension_id: String) -> bool: |
| 方法 | get_extension_resource_path |
static func get_extension_resource_path( extension_id: String, relative_path: String = "" ) -> String: |
| 方法 | is_extension_enabled |
static func is_extension_enabled( extension_id: String, include_dependencies: bool = true ) -> bool: |
| 方法 | load_enabled_extension_script |
static func load_enabled_extension_script( extension_id: String, relative_path: String, include_dependencies: bool = true ) -> Script: |
| 方法 | get_enabled_manifests |
static func get_enabled_manifests() -> Array[GFExtensionManifest]: |
| 方法 | get_disabled_manifests |
static func get_disabled_manifests() -> Array[GFExtensionManifest]: |
| 方法 | get_enabled_installer_paths |
static func get_enabled_installer_paths() -> Array[String]: |
| 方法 | get_enabled_editor_action_paths |
static func get_enabled_editor_action_paths() -> Array[String]: |
| 方法 | get_enabled_editor_dock_paths |
static func get_enabled_editor_dock_paths() -> Array[String]: |
| 方法 | get_enabled_editor_inspector_paths |
static func get_enabled_editor_inspector_paths() -> Array[String]: |
| 方法 | get_enabled_import_plugin_paths |
static func get_enabled_import_plugin_paths() -> Array[String]: |
| 方法 | get_enabled_export_plugin_paths |
static func get_enabled_export_plugin_paths() -> Array[String]: |
| 方法 | get_enabled_gltf_document_extension_paths |
static func get_enabled_gltf_document_extension_paths() -> Array[String]: |
| 方法 | get_enabled_access_generator_extension_paths |
static func get_enabled_access_generator_extension_paths() -> Array[String]: |
| 方法 | resolve_extension_dependencies |
static func resolve_extension_dependencies( extension_ids: Array[String], manifests: Array[GFExtensionManifest] = [] ) -> Array[String]: |
| 方法 | get_manifest_graph_report |
static func get_manifest_graph_report(manifests: Array[GFExtensionManifest] = []) -> Dictionary: |
| 方法 | get_extension_selection_report |
static func get_extension_selection_report() -> Dictionary: |
常量¶
ENABLED_EXTENSIONS_SETTING¶
- API：
public
项目设置：启用的 GF 扩展 ID 列表。
AUTO_INSTALL_ENABLED_INSTALLERS_SETTING¶
- API：
public
const AUTO_INSTALL_ENABLED_INSTALLERS_SETTING: String = "gf/extensions/auto_install_enabled_installers"
项目设置：是否自动执行启用扩展 manifest 中声明的 installer_paths。
EXPORT_EXCLUDE_DISABLED_SETTING¶
- API：
public
项目设置：导出时是否跳过禁用扩展目录。
EXPORT_FAIL_ON_DISABLED_REFERENCES_SETTING¶
- API：
public
const EXPORT_FAIL_ON_DISABLED_REFERENCES_SETTING: String = "gf/extensions/export_fail_on_disabled_references"
项目设置：导出审计发现项目仍引用禁用扩展时是否报告为错误。
AUTO_INSTALL_ENABLED_INSTALLERS_DEFAULT¶
- API：
public
默认自动执行启用扩展 Installer。
EXPORT_EXCLUDE_DISABLED_DEFAULT¶
- API：
public
默认导出时排除禁用扩展。
EXPORT_FAIL_ON_DISABLED_REFERENCES_DEFAULT¶
- API：
public
默认把禁用扩展引用作为导出错误，避免导出产物缺少被引用的扩展文件。
BUILT_IN_EXTENSION_IDS¶
- API：
public
内置依赖 ID。这些不是可启停扩展 manifest，但允许被扩展声明为基础依赖。
方法¶
ensure_defaults¶
- API：
public
确保扩展相关 ProjectSettings 存在。
返回：写入了默认值时返回 true。
register_property_info¶
- API：
public
注册扩展相关 ProjectSettings 显示信息。
get_default_enabled_extension_ids¶
- API：
public
获取默认启用的扩展 ID。
返回：默认启用扩展 ID 列表。
get_enabled_extension_ids¶
- API：
public
获取用户配置的启用扩展 ID。
返回：启用扩展 ID 列表。
set_enabled_extension_ids¶
- API：
public
static func set_enabled_extension_ids(extension_ids: Array[String], include_dependencies: bool = true) -> void:
保存启用扩展 ID，可选自动补齐依赖。
参数：
| 名称 | 说明 |
|---|---|
extension_ids |
要启用的扩展 ID 列表。 |
include_dependencies |
是否自动包含依赖扩展。 |
should_auto_install_enabled_installers¶
- API：
public
判断是否自动运行启用扩展 Installer。
返回：自动运行时返回 true。
set_auto_install_enabled_installers¶
- API：
public
设置是否自动运行启用扩展 Installer。
参数：
| 名称 | 说明 |
|---|---|
enabled |
是否自动运行。 |
should_export_exclude_disabled_extensions¶
- API：
public
判断导出时是否排除禁用扩展目录。
返回：排除禁用扩展时返回 true。
set_export_exclude_disabled_extensions¶
- API：
public
设置导出时是否排除禁用扩展目录。
参数：
| 名称 | 说明 |
|---|---|
enabled |
是否排除禁用扩展。 |
should_fail_export_on_disabled_extension_references¶
- API：
public
判断导出审计发现禁用扩展引用时是否报告为错误。
返回：报告为错误时返回 true。
set_fail_export_on_disabled_extension_references¶
- API：
public
设置导出审计发现禁用扩展引用时是否报告为错误。
参数：
| 名称 | 说明 |
|---|---|
enabled |
是否报告为错误。 |
get_all_manifests¶
- API：
public
获取所有 manifest。
返回：manifest 列表。
clear_manifest_cache¶
- API：
public
清空 manifest 发现缓存。编辑器或工具在扩展目录发生变化后可主动调用。
get_manifest_by_id¶
- API：
public
按 ID 获取 manifest。
参数：
| 名称 | 说明 |
|---|---|
extension_id |
扩展 ID。 |
返回：找到时返回 manifest，否则返回 null。
has_extension¶
- API：
public
判断扩展 manifest 是否存在。
参数：
| 名称 | 说明 |
|---|---|
extension_id |
扩展 ID。 |
返回：存在 manifest 时返回 true。
get_extension_resource_path¶
- API：
public
static func get_extension_resource_path( extension_id: String, relative_path: String = "" ) -> String:
获取扩展内资源路径。
参数：
| 名称 | 说明 |
|---|---|
extension_id |
扩展 ID。 |
relative_path |
相对扩展根目录的资源路径；传入 res:// 或 user:// 时会原样返回。 |
返回：扩展资源路径；扩展不存在时返回空字符串。
is_extension_enabled¶
- API：
public
static func is_extension_enabled( extension_id: String, include_dependencies: bool = true ) -> bool:
判断扩展当前是否启用。
参数：
| 名称 | 说明 |
|---|---|
extension_id |
扩展 ID。 |
include_dependencies |
是否把依赖补齐后的启用结果纳入判断。 |
返回：扩展存在且启用时返回 true。
load_enabled_extension_script¶
- API：
public
static func load_enabled_extension_script( extension_id: String, relative_path: String, include_dependencies: bool = true ) -> Script:
加载启用扩展内的脚本资源。
参数：
| 名称 | 说明 |
|---|---|
extension_id |
扩展 ID。 |
relative_path |
相对扩展根目录的脚本路径；传入 res:// 或 user:// 时会原样解析。 |
include_dependencies |
是否把依赖补齐后的启用结果纳入判断。 |
返回：扩展存在、已启用且脚本可加载时返回 Script，否则返回 null。
get_enabled_manifests¶
- API：
public
获取启用扩展的 manifest。
返回：启用 manifest 列表。
get_disabled_manifests¶
- API：
public
获取禁用扩展的 manifest。
返回：禁用 manifest 列表。
get_enabled_installer_paths¶
- API：
public
获取启用扩展声明的 Installer 路径。
返回：Installer 路径列表。
get_enabled_editor_action_paths¶
- API：
public
获取启用扩展声明的编辑器菜单动作路径。
返回：编辑器菜单动作脚本路径列表。
get_enabled_editor_dock_paths¶
- API：
public
获取启用扩展声明的编辑器工作区页面路径。
返回：编辑器工作区页面脚本路径列表。
get_enabled_editor_inspector_paths¶
- API：
public
获取启用扩展声明的 Inspector 扩展路径。
返回：EditorInspectorPlugin 脚本路径列表。
get_enabled_import_plugin_paths¶
- API：
public
获取启用扩展声明的导入插件路径。
返回：EditorImportPlugin 脚本路径列表。
get_enabled_export_plugin_paths¶
- API：
public
获取启用扩展声明的导出插件路径。
返回：EditorExportPlugin 脚本路径列表。
get_enabled_gltf_document_extension_paths¶
- API：
public
获取启用扩展声明的 glTF 文档扩展路径。
返回：GLTFDocumentExtension 脚本路径列表。
get_enabled_access_generator_extension_paths¶
- API：
public
获取启用扩展声明的访问器生成扩展路径。
返回：GFAccessGenerator 扩展脚本路径列表。
resolve_extension_dependencies¶
- API：
public
static func resolve_extension_dependencies( extension_ids: Array[String], manifests: Array[GFExtensionManifest] = [] ) -> Array[String]:
根据 manifest 依赖关系补齐启用扩展。
参数：
| 名称 | 说明 |
|---|---|
extension_ids |
原始启用扩展 ID。 |
manifests |
可选 manifest 列表。 |
返回：补齐依赖后的扩展 ID。
get_manifest_graph_report¶
- API：
public
获取 manifest 依赖图诊断。
参数：
| 名称 | 说明 |
|---|---|
manifests |
可选 manifest 列表；为空时扫描所有 GF 内置扩展。 |
返回：包含重复 ID、无效 manifest、缺失依赖和循环依赖的诊断字典。
结构：
return: Dictionary containing ok, extension_count, issue_count, duplicate_ids, invalid_manifests, missing_dependencies, and dependency_cycles.
get_extension_selection_report¶
- API：
public
获取启用状态诊断。
返回：诊断字典。
结构：
return: Dictionary containing configured_ids, resolved_ids, unknown_enabled_ids, graph status, and extension counts.