GFArchitecture¶
API Reference / Kernel / 类索引
- 路径：
addons/gf/kernel/core/gf_architecture.gd - 模块：
Kernel - 继承：
Object - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
管理 Model、System 和 Utility 的注册与生命周期的容器。 生命周期遵循三阶段初始化协议： 阶段一 (init) ：所有模块执行自身内部变量初始化。 阶段二 (async_init) ：所有模块串行执行异步初始化（可使用 await）。 阶段三 (ready) ：所有模块均已完成 init，可安全进行跨模块依赖获取。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | initialization_finished |
signal initialization_finished |
| 信号 | initialization_failed |
signal initialization_failed(reason: String) |
| 信号 | project_installers_finished |
signal project_installers_finished |
| 常量 | HOOK_GET_REQUIRED_DEPENDENCIES |
const HOOK_GET_REQUIRED_DEPENDENCIES: StringName = &"get_required_dependencies" |
| 常量 | HOOK_GET_REQUIRED_MODELS |
const HOOK_GET_REQUIRED_MODELS: StringName = &"get_required_models" |
| 常量 | HOOK_GET_REQUIRED_SYSTEMS |
const HOOK_GET_REQUIRED_SYSTEMS: StringName = &"get_required_systems" |
| 常量 | HOOK_GET_REQUIRED_UTILITIES |
const HOOK_GET_REQUIRED_UTILITIES: StringName = &"get_required_utilities" |
| 常量 | HOOK_GET_REQUIRED_FACTORIES |
const HOOK_GET_REQUIRED_FACTORIES: StringName = &"get_required_factories" |
| 属性 | module_async_init_timeout_seconds |
var module_async_init_timeout_seconds: float = 0.0: |
| 属性 | module_lifecycle_max_stage_passes |
var module_lifecycle_max_stage_passes: int = 256: |
| 属性 | strict_dependency_lookup |
var strict_dependency_lookup: bool = false |
| 属性 | last_initialization_error |
var last_initialization_error: String = "" |
| 方法 | _init |
func _init(parent_architecture: GFArchitecture = null) -> void: |
| 方法 | is_inited |
func is_inited() -> bool: |
| 方法 | has_initialization_failed |
func has_initialization_failed() -> bool: |
| 方法 | is_lifecycle_active |
func is_lifecycle_active() -> bool: |
| 方法 | is_module_ready |
func is_module_ready(instance: Object) -> bool: |
| 方法 | fail_initialization |
func fail_initialization(reason: String) -> void: |
| 方法 | get_parent_architecture |
func get_parent_architecture() -> GFArchitecture: |
| 方法 | set_parent_architecture |
func set_parent_architecture(parent_architecture: GFArchitecture) -> void: |
| 方法 | has_project_installers_applied |
func has_project_installers_applied() -> bool: |
| 方法 | is_project_installers_running |
func is_project_installers_running() -> bool: |
| 方法 | begin_project_installers |
func begin_project_installers() -> bool: |
| 方法 | mark_project_installers_applied |
func mark_project_installers_applied() -> void: |
| 方法 | finish_project_installers |
func finish_project_installers() -> void: |
| 方法 | create_binder |
func create_binder() -> GFBinder: |
| 方法 | init |
func init() -> void: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | tick |
func tick(delta: float) -> void: |
| 方法 | physics_tick |
func physics_tick(delta: float) -> void: |
| 方法 | send_command |
func send_command(command: Object) -> Variant: |
| 方法 | send_query |
func send_query(query: Object) -> Variant: |
| 方法 | send_event |
func send_event(event_instance: Object) -> void: |
| 方法 | register_event |
func register_event(event_type: Script, on_event: Callable, priority: int = 0) -> void: |
| 方法 | register_event_owned |
func register_event_owned(owner: Object, event_type: Script, on_event: Callable, priority: int = 0) -> void: |
| 方法 | register_assignable_event |
func register_assignable_event(base_event_type: Script, on_event: Callable, priority: int = 0) -> void: |
| 方法 | register_assignable_event_owned |
func register_assignable_event_owned( owner: Object, base_event_type: Script, on_event: Callable, priority: int = 0 ) -> void: |
| 方法 | unregister_event |
func unregister_event(event_type: Script, on_event: Callable) -> void: |
| 方法 | unregister_assignable_event |
func unregister_assignable_event(base_event_type: Script, on_event: Callable) -> void: |
| 方法 | register_simple_event |
func register_simple_event(event_id: StringName, on_event: Callable) -> void: |
| 方法 | register_simple_event_owned |
func register_simple_event_owned(owner: Object, event_id: StringName, on_event: Callable) -> void: |
| 方法 | unregister_simple_event |
func unregister_simple_event(event_id: StringName, on_event: Callable) -> void: |
| 方法 | unregister_owner_events |
func unregister_owner_events(owner: Object) -> void: |
| 方法 | send_simple_event |
func send_simple_event(event_id: StringName, payload: Variant = null) -> void: |
| 方法 | get_event_debug_stats |
func get_event_debug_stats() -> Dictionary: |
| 方法 | configure_event_debugging |
func configure_event_debugging( max_dispatch_depth: int = GFTypeEventSystem.DEFAULT_MAX_DISPATCH_DEPTH, trace_enabled: bool = false, max_trace_entries: int = 64 ) -> void: |
| 方法 | get_event_dispatch_trace |
func get_event_dispatch_trace() -> Array[Dictionary]: |
| 方法 | clear_event_dispatch_trace |
func clear_event_dispatch_trace() -> void: |
| 方法 | register_system |
func register_system(script_cls: Script, instance: Object) -> void: |
| 方法 | register_model |
func register_model(script_cls: Script, instance: Object) -> void: |
| 方法 | register_utility |
func register_utility(script_cls: Script, instance: Object) -> void: |
| 方法 | replace_system |
func replace_system(script_cls: Script, instance: Object) -> void: |
| 方法 | replace_model |
func replace_model(script_cls: Script, instance: Object) -> void: |
| 方法 | replace_utility |
func replace_utility(script_cls: Script, instance: Object) -> void: |
| 方法 | register_factory |
func register_factory( script_cls: Script, factory: Callable, lifetime: int = GFBindingLifetimesBase.Lifetime.TRANSIENT ) -> void: |
| 方法 | register_factory_instance |
func register_factory_instance(script_cls: Script, instance: Object) -> void: |
| 方法 | replace_factory |
func replace_factory( script_cls: Script, factory: Callable, lifetime: int = GFBindingLifetimesBase.Lifetime.TRANSIENT ) -> void: |
| 方法 | replace_factory_instance |
func replace_factory_instance(script_cls: Script, instance: Object) -> void: |
| 方法 | unregister_factory |
func unregister_factory(script_cls: Script) -> void: |
| 方法 | has_factory |
func has_factory(script_cls: Script) -> bool: |
| 方法 | register_system_alias |
func register_system_alias(alias_cls: Script, target_cls: Script) -> void: |
| 方法 | register_model_alias |
func register_model_alias(alias_cls: Script, target_cls: Script) -> void: |
| 方法 | register_utility_alias |
func register_utility_alias(alias_cls: Script, target_cls: Script) -> void: |
| 方法 | register_system_instance |
func register_system_instance(instance: Object) -> void: |
| 方法 | register_model_instance |
func register_model_instance(instance: Object) -> void: |
| 方法 | register_utility_instance |
func register_utility_instance(instance: Object) -> void: |
| 方法 | register_system_instance_as |
func register_system_instance_as(instance: Object, alias_cls: Script) -> void: |
| 方法 | register_model_instance_as |
func register_model_instance_as(instance: Object, alias_cls: Script) -> void: |
| 方法 | register_utility_instance_as |
func register_utility_instance_as(instance: Object, alias_cls: Script) -> void: |
| 方法 | unregister_system |
func unregister_system(script_cls: Script) -> void: |
| 方法 | unregister_model |
func unregister_model(script_cls: Script) -> void: |
| 方法 | unregister_utility |
func unregister_utility(script_cls: Script) -> void: |
| 方法 | get_system |
func get_system(script_cls: Script, require_ready: bool = false) -> Object: |
| 方法 | get_model |
func get_model(script_cls: Script, require_ready: bool = false) -> Object: |
| 方法 | get_utility |
func get_utility(script_cls: Script, require_ready: bool = false) -> Object: |
| 方法 | get_local_system |
func get_local_system(script_cls: Script, require_ready: bool = false) -> Object: |
| 方法 | get_local_model |
func get_local_model(script_cls: Script, require_ready: bool = false) -> Object: |
| 方法 | get_local_utility |
func get_local_utility(script_cls: Script, require_ready: bool = false) -> Object: |
| 方法 | create_instance |
func create_instance(script_cls: Script) -> Object: |
| 方法 | inject_object |
func inject_object(instance: Object) -> void: |
| 方法 | inject_node_tree |
func inject_node_tree(node: Node) -> void: |
| 方法 | get_all_models_state |
func get_all_models_state() -> Dictionary: |
| 方法 | restore_all_models_state |
func restore_all_models_state(data: Dictionary) -> void: |
| 方法 | get_global_snapshot |
func get_global_snapshot() -> Dictionary: |
| 方法 | restore_global_snapshot |
func restore_global_snapshot(data: Dictionary, command_builder: Callable = Callable()) -> void: |
| 方法 | get_debug_lifecycle_state |
func get_debug_lifecycle_state() -> Dictionary: |
| 方法 | get_dependency_diagnostics |
func get_dependency_diagnostics(options: Dictionary = {}) -> Dictionary: |
| 方法 | _on_init |
func _on_init() -> void: |
| 方法 | _on_dispose |
func _on_dispose() -> void: |
信号¶
initialization_finished¶
- API：
public
当一次初始化流程完成或被 dispose() 中断后发出。
initialization_failed¶
- API：
public
当一次初始化流程因为框架级保护失败后发出。
参数：
| 名称 | 说明 |
|---|---|
reason |
初始化失败原因。 |
project_installers_finished¶
- API：
public
当项目级 Installer 应用完成或被 dispose() 中断后发出。
常量¶
HOOK_GET_REQUIRED_DEPENDENCIES¶
- API：
public
声明式依赖聚合 Hook 名称。
HOOK_GET_REQUIRED_MODELS¶
- API：
public
声明式 Model 依赖 Hook 名称。
HOOK_GET_REQUIRED_SYSTEMS¶
- API：
public
声明式 System 依赖 Hook 名称。
HOOK_GET_REQUIRED_UTILITIES¶
- API：
public
声明式 Utility 依赖 Hook 名称。
HOOK_GET_REQUIRED_FACTORIES¶
- API：
public
声明式工厂依赖 Hook 名称。
属性¶
module_async_init_timeout_seconds¶
- API：
public
单个模块 async_init() 的最长等待时间。小于等于 0 时不启用超时。 默认关闭；项目可按自身加载预算显式启用。
module_lifecycle_max_stage_passes¶
- API：
public
单个生命周期阶段最多扫描模块注册表的次数，避免模块在生命周期中无限注册新模块。
strict_dependency_lookup¶
- API：
public
严格依赖查询模式。开启后本架构查询不到本地模块时不会回退父级架构。
last_initialization_error¶
- API：
public
最近一次初始化失败原因；没有失败时为空字符串。
方法¶
_init¶
- API：
public
创建架构容器，可选择指定父级架构作为依赖回退来源。
参数：
| 名称 | 说明 |
|---|---|
parent_architecture |
父级架构；为空时不启用回退。 |
is_inited¶
- API：
public
检查架构是否已初始化。
返回：已初始化返回 true，否则返回 false。
has_initialization_failed¶
- API：
public
检查最近一次初始化是否因为框架级保护失败。
返回：最近一次初始化失败返回 true。
is_lifecycle_active¶
- API：
public
检查当前架构生命周期是否仍处于可安全继续异步写回的活动状态。
返回：正在初始化或已完成初始化，且未被 dispose() 或失败保护中断时返回 true。
is_module_ready¶
- API：
public
检查指定模块实例是否已经完成 ready 阶段。
参数：
| 名称 | 说明 |
|---|---|
instance |
由当前架构注册的模块实例。 |
返回：模块完成 ready 阶段时返回 true。
fail_initialization¶
- API：
public
将当前架构标记为初始化失败，并唤醒等待初始化或 Installer 的调用方。
参数：
| 名称 | 说明 |
|---|---|
reason |
初始化失败原因。 |
get_parent_architecture¶
- API：
public
获取父级架构。Scoped 架构会在本地未找到依赖时回退到父级架构查询。
返回：父级架构实例；未设置时返回 null。
set_parent_architecture¶
- API：
public
设置父级架构。不会接管父级生命周期。
参数：
| 名称 | 说明 |
|---|---|
parent_architecture |
要作为依赖回退来源的父级架构。 |
has_project_installers_applied¶
- API：
public
检查项目级 Installer 是否已经应用到当前架构。
返回：已应用返回 true。
is_project_installers_running¶
- API：
public
检查项目级 Installer 是否正在应用。
返回：正在应用返回 true。
begin_project_installers¶
- API：
public
标记项目级 Installer 已开始应用。
返回：成功开始返回 true；已经完成或正在运行时返回 false。
mark_project_installers_applied¶
- API：
public
标记项目级 Installer 已应用。由 Gf 启动入口调用。
finish_project_installers¶
- API：
public
标记项目级 Installer 应用完成并唤醒等待方。
create_binder¶
- API：
public
创建一个声明式装配器，便于 Installer 使用 fluent API 注册模块与工厂。
返回：绑定到当前架构的装配器。
结构：
return: GFBinder owned by this architecture.
init¶
- API：
public
初始化架构及所有注册的组件（三阶段）。 阶段一：调用所有模块的 init()，用于初始化自身内部变量。 阶段二：串行 await 所有模块的 async_init()，用于异步资源加载等操作。 阶段三：调用所有模块的 ready()，此时跨模块依赖获取是安全的。
dispose¶
- API：
public
销毁架构及所有注册的组件。
tick¶
- API：
public
驱动所有参与 tick 的 System 与 Utility 的每帧更新。 在架构初始化完成后方可生效。 若已注册 GFTimeProvider，则自动将 delta 经过时间缩放/暂停处理后再传递给参与 tick 的模块。 设置了 ignore_pause 的模块在暂停时将接收原始 delta。 设置了 ignore_time_scale 的模块在未暂停时将跳过 time_scale。
参数：
| 名称 | 说明 |
|---|---|
delta |
距上一帧的时间（秒）。 |
physics_tick¶
- API：
public
驱动所有参与 physics_tick 的 System 与 Utility 的每物理帧更新。 在架构初始化完成后方可生效。 若已注册 GFTimeProvider，则自动将 delta 经过时间缩放/暂停处理后再传递给参与 physics_tick 的模块。 设置了 ignore_pause 的模块在暂停时将接收原始 delta。 设置了 ignore_time_scale 的模块在未暂停时将跳过 time_scale。
参数：
| 名称 | 说明 |
|---|---|
delta |
距上一物理帧的时间（秒）。 |
send_command¶
- API：
public
执行命令实例。支持 await：'await send_command(MyCommand.new())'。 command 缺少 execute() 方法时会输出 warning 并返回 null。
参数：
| 名称 | 说明 |
|---|---|
command |
要执行的命令实例。 |
返回：命令 execute() 的返回值；空对象或缺少 execute() 时返回 null。
结构：
return: Variant command result returned by command.execute().
send_query¶
- API：
public
执行查询实例并返回结果。 query 缺少 execute() 方法时会输出 warning 并返回 null。
参数：
| 名称 | 说明 |
|---|---|
query |
要执行的查询实例。 |
返回：查询 execute() 的返回值；空对象或缺少 execute() 时返回 null。
结构：
return: Variant query result returned by query.execute().
send_event¶
- API：
public
通过事件系统发送类型事件实例。
参数：
| 名称 | 说明 |
|---|---|
event_instance |
要分发的事件实例。 |
register_event¶
- API：
public
为脚本类型注册事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_type |
要监听的脚本类型。 |
on_event |
回调函数。 |
priority |
回调优先级，数值越大越先执行，默认为 0。 |
register_event_owned¶
- API：
public
func register_event_owned(owner: Object, event_type: Script, on_event: Callable, priority: int = 0) -> void:
为脚本类型注册带拥有者的事件监听器。 拥有者注销或释放后，可通过 unregister_owner_events() 一次性清理相关监听。
参数：
| 名称 | 说明 |
|---|---|
owner |
监听器拥有者。 |
event_type |
要监听的脚本类型。 |
on_event |
回调函数。 |
priority |
回调优先级，数值越大越先执行，默认为 0。 |
register_assignable_event¶
- API：
public
func register_assignable_event(base_event_type: Script, on_event: Callable, priority: int = 0) -> void:
为脚本类型注册可赋值事件监听器。 监听基类事件时，也会收到继承自该脚本类型的事件实例。
参数：
| 名称 | 说明 |
|---|---|
base_event_type |
要监听的基类脚本类型。 |
on_event |
回调函数。 |
priority |
回调优先级，数值越大越先执行，默认为 0。 |
register_assignable_event_owned¶
- API：
public
func register_assignable_event_owned( owner: Object, base_event_type: Script, on_event: Callable, priority: int = 0 ) -> void:
为脚本类型注册带拥有者的可赋值事件监听器。
参数：
| 名称 | 说明 |
|---|---|
owner |
监听器拥有者。 |
base_event_type |
要监听的基类脚本类型。 |
on_event |
回调函数。 |
priority |
回调优先级，数值越大越先执行，默认为 0。 |
unregister_event¶
- API：
public
为脚本类型注销事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_type |
要注销的脚本类型。 |
on_event |
要移除的回调函数。 |
unregister_assignable_event¶
- API：
public
注销可赋值类型事件监听器。
参数：
| 名称 | 说明 |
|---|---|
base_event_type |
注册时使用的基类脚本类型。 |
on_event |
要移除的回调函数。 |
register_simple_event¶
- API：
public
注册轻量级 StringName 事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
on_event |
回调函数，签名为 func(payload: Variant)。 |
register_simple_event_owned¶
- API：
public
注册带拥有者的轻量级 StringName 事件监听器。
参数：
| 名称 | 说明 |
|---|---|
owner |
监听器拥有者。 |
event_id |
StringName 事件标识符。 |
on_event |
回调函数，签名为 func(payload: Variant)。 |
unregister_simple_event¶
- API：
public
注销轻量级 StringName 事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
on_event |
要移除的回调函数。 |
unregister_owner_events¶
- API：
public
注销某个拥有者注册过的所有事件监听器。
参数：
| 名称 | 说明 |
|---|---|
owner |
要清理监听器的拥有者。 |
send_simple_event¶
- API：
public
发送轻量级 StringName 事件，避免高频 new() 带来的 GC 压力。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
payload |
可选的事件附加数据。 |
结构：
payload: Variant payload passed unchanged to simple event listeners.
get_event_debug_stats¶
- API：
public
获取事件系统诊断统计。
返回：包含各事件轨道监听数量与 pending 操作数量的字典。
结构：
return: Dictionary produced by GFTypeEventSystem.get_debug_stats().
configure_event_debugging¶
- API：
public
func configure_event_debugging( max_dispatch_depth: int = GFTypeEventSystem.DEFAULT_MAX_DISPATCH_DEPTH, trace_enabled: bool = false, max_trace_entries: int = 64 ) -> void:
配置事件系统调试与保护选项。
参数：
| 名称 | 说明 |
|---|---|
max_dispatch_depth |
最大嵌套派发深度；小于等于 0 表示不限制。 |
trace_enabled |
是否记录派发追踪。 |
max_trace_entries |
最多保留的追踪条目数。 |
get_event_dispatch_trace¶
- API：
public
获取最近事件派发追踪条目。
返回：从旧到新的追踪条目副本。
结构：
return: Array of Dictionary trace entries with event, listener, owner, and dispatch metadata.
clear_event_dispatch_trace¶
- API：
public
清空事件派发追踪。
register_system¶
- API：
public
注册 System 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
系统的脚本类。 |
instance |
系统实例。 |
register_model¶
- API：
public
注册 Model 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
模型的脚本类。 |
instance |
模型实例。 |
register_utility¶
- API：
public
注册 Utility 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
工具的脚本类。 |
instance |
工具实例。 |
replace_system¶
- API：
public
替换 System 实例。若旧实例存在，会先调用 dispose() 并移除相关别名。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
系统的脚本类。 |
instance |
新系统实例。 |
replace_model¶
- API：
public
替换 Model 实例。若旧实例存在，会先调用 dispose() 并移除相关别名。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
模型的脚本类。 |
instance |
新模型实例。 |
replace_utility¶
- API：
public
替换 Utility 实例。若旧实例存在，会先调用 dispose() 并移除相关别名。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
工具的脚本类。 |
instance |
新工具实例。 |
register_factory¶
- API：
public
func register_factory( script_cls: Script, factory: Callable, lifetime: int = GFBindingLifetimesBase.Lifetime.TRANSIENT ) -> void:
注册短生命周期对象工厂。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
要创建的脚本类型。 |
factory |
返回对象实例的工厂回调。 |
lifetime |
工厂生命周期，默认每次 create_instance() 都创建新对象。 |
register_factory_instance¶
- API：
public
注册已有实例作为短生命周期工厂入口。该实例以单例方式返回。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
要创建的脚本类型。 |
instance |
要暴露的实例。 |
replace_factory¶
- API：
public
func replace_factory( script_cls: Script, factory: Callable, lifetime: int = GFBindingLifetimesBase.Lifetime.TRANSIENT ) -> void:
替换短生命周期对象工厂。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
要创建的脚本类型。 |
factory |
新工厂回调。 |
lifetime |
工厂生命周期。 |
replace_factory_instance¶
- API：
public
替换已有实例工厂入口。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
要创建的脚本类型。 |
instance |
要暴露的实例。 |
unregister_factory¶
- API：
public
注销短生命周期对象工厂。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
要移除的脚本类型。 |
has_factory¶
- API：
public
检查当前架构或父级架构是否注册了指定工厂。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
要查询的脚本类型。 |
返回：工厂存在时返回 true。
register_system_alias¶
- API：
public
为已注册 System 增加一个额外查询别名。 适合把具体实现以抽象基类或接口式脚本暴露给调用方。
参数：
| 名称 | 说明 |
|---|---|
alias_cls |
调用 get_system() 时使用的别名脚本类。 |
target_cls |
已注册 System 的实际脚本类。 |
register_model_alias¶
- API：
public
为已注册 Model 增加一个额外查询别名。
参数：
| 名称 | 说明 |
|---|---|
alias_cls |
调用 get_model() 时使用的别名脚本类。 |
target_cls |
已注册 Model 的实际脚本类。 |
register_utility_alias¶
- API：
public
为已注册 Utility 增加一个额外查询别名。
参数：
| 名称 | 说明 |
|---|---|
alias_cls |
调用 get_utility() 时使用的别名脚本类。 |
target_cls |
已注册 Utility 的实际脚本类。 |
register_system_instance¶
- API：
public
便捷注册 System 实例，自动从实例获取脚本类作为注册键。
参数：
| 名称 | 说明 |
|---|---|
instance |
系统实例，必须附加有 GDScript 脚本。 |
register_model_instance¶
- API：
public
便捷注册 Model 实例，自动从实例获取脚本类作为注册键。
参数：
| 名称 | 说明 |
|---|---|
instance |
模型实例，必须附加有 GDScript 脚本。 |
register_utility_instance¶
- API：
public
便捷注册 Utility 实例，自动从实例获取脚本类作为注册键。
参数：
| 名称 | 说明 |
|---|---|
instance |
工具实例，必须附加有 GDScript 脚本。 |
register_system_instance_as¶
- API：
public
便捷注册 System，并同时以 alias_cls 作为额外查询键。
参数：
| 名称 | 说明 |
|---|---|
instance |
System 实例。 |
alias_cls |
额外查询脚本类。 |
register_model_instance_as¶
- API：
public
便捷注册 Model，并同时以 alias_cls 作为额外查询键。
参数：
| 名称 | 说明 |
|---|---|
instance |
Model 实例。 |
alias_cls |
额外查询脚本类。 |
register_utility_instance_as¶
- API：
public
便捷注册 Utility，并同时以 alias_cls 作为额外查询键。
参数：
| 名称 | 说明 |
|---|---|
instance |
Utility 实例。 |
alias_cls |
额外查询脚本类。 |
unregister_system¶
- API：
public
注销 System 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
系统的脚本类。 |
unregister_model¶
- API：
public
注销 Model 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
模型的脚本类。 |
unregister_utility¶
- API：
public
注销 Utility 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
工具的脚本类。 |
get_system¶
- API：
public
通过脚本类获取 System 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
脚本类。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：系统实例，如果未找到则返回 null。
get_model¶
- API：
public
通过脚本类获取 Model 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
脚本类。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：模型实例，如果未找到则返回 null。
get_utility¶
- API：
public
通过脚本类获取 Utility 实例。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
脚本类。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：工具实例，如果未找到则返回 null。
get_local_system¶
- API：
public
仅从当前架构获取 System，不回退父级架构。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
脚本类。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：当前架构中的系统实例，如果未找到则返回 null。
get_local_model¶
- API：
public
仅从当前架构获取 Model，不回退父级架构。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
脚本类。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：当前架构中的模型实例，如果未找到则返回 null。
get_local_utility¶
- API：
public
仅从当前架构获取 Utility，不回退父级架构。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
脚本类。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：当前架构中的工具实例，如果未找到则返回 null。
create_instance¶
- API：
public
通过已注册工厂创建短生命周期对象。
参数：
| 名称 | 说明 |
|---|---|
script_cls |
要创建的脚本类型。 |
返回：新对象实例；没有工厂或工厂返回非对象时返回 null。
inject_object¶
- API：
public
向任意对象注入当前架构依赖。
参数：
| 名称 | 说明 |
|---|---|
instance |
需要注入的对象。 |
inject_node_tree¶
- API：
public
递归向节点树中实现注入 Hook 的节点注入当前架构。
参数：
| 名称 | 说明 |
|---|---|
node |
节点树根节点。 |
get_all_models_state¶
- API：
public
收集所有已注册 Model 的状态快照。 遍历所有 Model，调用其 to_dict() 方法，以脚本类的全局类名为键汇聚成一个字典。
返回：包含所有 Model 状态的字典，可直接用于 JSON 序列化。
结构：
return: Dictionary keyed by stable model save key, storing each Model.to_dict() result.
restore_all_models_state¶
- API：
public
从状态字典恢复所有已注册 Model 的数据。
参数：
| 名称 | 说明 |
|---|---|
data |
由 get_all_models_state() 返回的状态字典。 |
结构：
data: Dictionary keyed by stable model save key, storing serialized model data.
get_global_snapshot¶
- API：
public
获取整个框架的全局快照，包含所有 Model 状态以及可选命令历史记录。
返回：包含全局快照数据的字典。可直接用于 JSON 序列化。
结构：
return: Dictionary with models and optional command_history fields.
restore_global_snapshot¶
- API：
public
从全局快照中恢复整个框架的状态，包含 Model 状态以及可选命令历史记录。 注意：恢复命令历史需要外部传入 CommandBuilder 进行控制反转，因为它涉及到具体的业务命令类实例化。
参数：
| 名称 | 说明 |
|---|---|
data |
由 get_global_snapshot() 导出的全局快照字典数据。 |
command_builder |
【可选】如果需要恢复历史记录，必须传入用于反序列化具体 Command 实例的 Callable。 |
结构：
data: Dictionary produced by get_global_snapshot().
get_debug_lifecycle_state¶
- API：
public
获取架构模块生命周期诊断快照。
返回：包含 Model、System、Utility、Factory、Alias 与 Tick 缓存状态的字典。
结构：
return: Dictionary containing lifecycle flags, registered module summaries, factory summaries, alias counts, and tick cache counts.
get_dependency_diagnostics¶
- API：
public
获取架构中已注册模块的声明式依赖诊断报告。 模块可选择实现 get_required_dependencies() 或 get_required_models/systems/utilities/factories()。
参数：
| 名称 | 说明 |
|---|---|
options |
可选参数，支持 include_parent_lookup 与 include_factories。 |
返回：统一诊断报告字典。
结构：
options: Dictionary with optional bool keys include_parent_lookup and include_factories.return: Dictionary dependency diagnostics report with modules, resolved_dependencies, missing_dependencies, issue counts, and next_action.
_on_init¶
- API：
protected
内部初始化回调，子类可重写。
_on_dispose¶
- API：
protected
内部销毁回调，子类可重写。