GFDecisionContext¶
API Reference / Decision / 类索引
- 路径：
addons/gf/extensions/decision/runtime/gf_decision_context.gd - 模块：
Decision - 继承：
RefCounted - API：
public - 类别：领域模型 (
domain_model) - 首次版本：
4.3.0
通用决策上下文。 组合黑板、主体/目标快照视图和元数据，供决策候选与考虑项读取状态。 赋值时先主动捕获可见值；缺失 key 可由对象的 get_decision_value() 按需提供并写入当前上下文缓存。 该类型只用弱引用暴露当前对象，不通过上下文延长对象生命周期。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 常量 | DEFAULT_MAX_SNAPSHOT_ENTRIES |
const DEFAULT_MAX_SNAPSHOT_ENTRIES: int = 1024 |
| 常量 | DEFAULT_MAX_REFLECTION_PROPERTIES |
const DEFAULT_MAX_REFLECTION_PROPERTIES: int = 256 |
| 属性 | blackboard |
var blackboard: GFDecisionBlackboard = null |
| 属性 | subject |
var subject: Object: |
| 属性 | target |
var target: Object: |
| 属性 | subject_values |
var subject_values: Dictionary = {} |
| 属性 | target_values |
var target_values: Dictionary = {} |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 属性 | capture_options |
var capture_options: Dictionary = {} |
| 方法 | set_value |
func set_value(key: StringName, value: Variant) -> void: |
| 方法 | get_value |
func get_value(key: StringName, default_value: Variant = null) -> Variant: |
| 方法 | has_value |
func has_value(key: StringName) -> bool: |
| 方法 | set_metadata_value |
func set_metadata_value(key: StringName, value: Variant) -> void: |
| 方法 | get_metadata_value |
func get_metadata_value(key: StringName, default_value: Variant = null) -> Variant: |
| 方法 | get_subject_value |
func get_subject_value(key: StringName, fallback: Variant = null) -> Variant: |
| 方法 | get_target_value |
func get_target_value(key: StringName, fallback: Variant = null) -> Variant: |
| 方法 | get_subject_or_null |
func get_subject_or_null() -> Object: |
| 方法 | get_target_or_null |
func get_target_or_null() -> Object: |
| 方法 | duplicate_context |
func duplicate_context() -> GFDecisionContext: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
常量¶
DEFAULT_MAX_SNAPSHOT_ENTRIES¶
- API：
public - 首次版本：
8.0.0
主体或目标主动捕获的默认最大条目数。
DEFAULT_MAX_REFLECTION_PROPERTIES¶
- API：
public - 首次版本：
8.0.0
反射属性捕获的默认最大条目数。
属性¶
blackboard¶
- API：
public
决策黑板。
subject¶
- API：
public - 首次版本：
7.0.0
决策主体，例如当前 agent、系统或导演对象。
target¶
- API：
public - 首次版本：
7.0.0
可选决策目标。
subject_values¶
- API：
public - 首次版本：
7.0.0
主体决策值快照视图。容器会复制，但其中的 Object/Resource 身份保持共享；缺失 key 可被懒缓存补充。
结构：
subject_values: Dictionary[StringName, Variant] eagerly captured at assignment and optionally extended by bounded lazy reads.
target_values¶
- API：
public - 首次版本：
7.0.0
目标决策值快照视图。容器会复制，但其中的 Object/Resource 身份保持共享；缺失 key 可被懒缓存补充。
结构：
target_values: Dictionary[StringName, Variant] eagerly captured at assignment and optionally extended by bounded lazy reads.
metadata¶
- API：
public
项目自定义上下文元数据。
结构：
metadata: Dictionary[StringName, Variant] project-defined decision metadata.
capture_options¶
- API：
public - 首次版本：
8.0.0
捕获预算选项。
结构：
capture_options: Dictionary with optional max_snapshot_entries and max_reflection_properties integer fields.
方法¶
set_value¶
- API：
public
设置黑板值。
参数：
| 名称 | 说明 |
|---|---|
key |
值键。 |
value |
要写入或修改的值。 |
结构：
value: 要写入黑板的任意项目值。
get_value¶
- API：
public
获取黑板值。
参数：
| 名称 | 说明 |
|---|---|
key |
值键。 |
default_value |
缺失时返回的默认值。 |
返回：黑板值或默认值。
结构：
default_value: 黑板缺失时返回的任意默认值。return: 黑板中的项目值，或传入的 default_value。
has_value¶
- API：
public
检查黑板值是否存在。
参数：
| 名称 | 说明 |
|---|---|
key |
值键。 |
返回：存在返回 true。
set_metadata_value¶
- API：
public
设置元数据值。
参数：
| 名称 | 说明 |
|---|---|
key |
元数据键。 |
value |
元数据值。 |
结构：
value: 要写入元数据的任意项目值。
get_metadata_value¶
- API：
public
获取元数据值。
参数：
| 名称 | 说明 |
|---|---|
key |
元数据键。 |
default_value |
缺失时返回的默认值。 |
返回：元数据值或默认值。
结构：
default_value: 元数据缺失时返回的任意默认值。return: 元数据中的项目值，或传入的 default_value。
get_subject_value¶
- API：
public - 首次版本：
7.0.0
从主体快照视图读取决策值；缺失 key 可触发一次受预算约束的 provider 懒读取并缓存。
参数：
| 名称 | 说明 |
|---|---|
key |
值键或属性名。 |
fallback |
读取失败时的兜底值。 |
返回：主体值或兜底值。
结构：
fallback: 读取失败时返回的任意项目值。return: 从主体读取的项目值，或传入的 fallback。
get_target_value¶
- API：
public - 首次版本：
7.0.0
从目标快照视图读取决策值；缺失 key 可触发一次受预算约束的 provider 懒读取并缓存。
参数：
| 名称 | 说明 |
|---|---|
key |
值键或属性名。 |
fallback |
读取失败时的兜底值。 |
返回：目标值或兜底值。
结构：
fallback: 读取失败时返回的任意项目值。return: 从目标读取的项目值，或传入的 fallback。
get_subject_or_null¶
- API：
public - 首次版本：
7.0.0
获取当前主体对象；对象已释放时返回 null。
返回：当前主体对象或 null。
get_target_or_null¶
- API：
public - 首次版本：
7.0.0
获取当前目标对象；对象已释放时返回 null。
返回：当前目标对象或 null。
duplicate_context¶
- API：
public - 首次版本：
7.0.0
创建上下文副本。 默认复用 subject 与 target 弱引用；复制黑板、快照容器、捕获诊断和元数据，嵌套 Object/Resource 身份保持共享。
返回：新上下文实例。
get_debug_snapshot¶
- API：
public - 首次版本：
4.3.0
获取调试快照。
返回：调试快照字典。
结构：
return: JSON-safe Dictionary，包含 blackboard、metadata、subject_class、target_class、subject_values、target_values 和 capture_diagnostics 字段。