GFDialogueRunner¶
API Reference / Dialogue / 类索引
- 路径：
addons/gf/extensions/dialogue/runtime/gf_dialogue_runner.gd - 模块：
Dialogue - 继承：
RefCounted - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
通用对话资源执行器。 Runner 只沿 GFDialogueResource 的行、响应、跳转、条件和 mutation 推进， 并发出结构化事件。显示、输入、存档和业务状态由项目层决定。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | dialogue_started |
signal dialogue_started(resource: GFDialogueResource) |
| 信号 | line_reached |
signal line_reached(line: GFDialogueLine) |
| 信号 | mutation_requested |
signal mutation_requested(mutation_id: StringName, payload: Variant, line: GFDialogueLine) |
| 信号 | dialogue_ended |
signal dialogue_ended(resource: GFDialogueResource) |
| 信号 | line_blocked |
signal line_blocked(line_id: StringName, reason: StringName) |
| 常量 | SNAPSHOT_SCHEMA_VERSION |
const SNAPSHOT_SCHEMA_VERSION: int = 4 |
| 属性 | max_steps_per_advance |
var max_steps_per_advance: int = 1024 |
| 属性 | skip_blocked_lines |
var skip_blocked_lines: bool = true |
| 方法 | start |
func start( resource: GFDialogueResource, start_line_id: StringName = &"", context: GFDialogueContext = null ) -> GFDialogueLine: |
| 方法 | advance |
func advance(response_id: StringName = &"") -> GFDialogueLine: |
| 方法 | choose_response |
func choose_response(response_id: StringName) -> GFDialogueLine: |
| 方法 | stop |
func stop() -> void: |
| 方法 | get_current_line |
func get_current_line() -> GFDialogueLine: |
| 方法 | get_available_responses |
func get_available_responses() -> Array[GFDialogueResponse]: |
| 方法 | is_running |
func is_running() -> bool: |
| 方法 | create_runtime_snapshot |
func create_runtime_snapshot() -> Dictionary: |
| 方法 | restore_runtime_snapshot |
func restore_runtime_snapshot( resource: GFDialogueResource, snapshot: Dictionary, context: GFDialogueContext = null ) -> GFDialogueLine: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
信号¶
dialogue_started¶
- API：
public
对话开始时发出。
参数：
| 名称 | 说明 |
|---|---|
resource |
对话资源。 |
line_reached¶
- API：
public
到达可展示文本行时发出。
参数：
| 名称 | 说明 |
|---|---|
line |
当前行。 |
mutation_requested¶
- API：
public
请求执行 mutation 时发出。
参数：
| 名称 | 说明 |
|---|---|
mutation_id |
mutation ID。 |
payload |
mutation 载荷。 |
line |
当前行。 |
结构：
payload: mutation 处理器接收的任意项目载荷；框架只透传。
dialogue_ended¶
- API：
public
对话结束时发出。
参数：
| 名称 | 说明 |
|---|---|
resource |
对话资源。 |
line_blocked¶
- API：
public
推进被阻止时发出。
参数：
| 名称 | 说明 |
|---|---|
line_id |
被阻止的行 ID。 |
reason |
原因。 |
常量¶
SNAPSHOT_SCHEMA_VERSION¶
- API：
public - 首次版本：
5.0.0
对话运行快照结构版本。
属性¶
max_steps_per_advance¶
- API：
public
最多连续推进的非展示行数量，避免错误资源无限循环。
skip_blocked_lines¶
- API：
public
条件不通过且没有 fallback 时，是否尝试跳到默认后继。
方法¶
start¶
- API：
public
func start( resource: GFDialogueResource, start_line_id: StringName = &"", context: GFDialogueContext = null ) -> GFDialogueLine:
开始对话。
参数：
| 名称 | 说明 |
|---|---|
resource |
对话资源。 |
start_line_id |
可选起始行 ID。 |
context |
可选上下文。 |
返回：到达的第一条可展示行；结束或失败时返回 null。
advance¶
- API：
public
推进对话。
参数：
| 名称 | 说明 |
|---|---|
response_id |
可选响应 ID；非空时从当前行选择响应后推进。 |
返回：到达的下一条可展示行；结束或失败时返回 null。
choose_response¶
- API：
public
选择当前行响应并推进。
参数：
| 名称 | 说明 |
|---|---|
response_id |
响应 ID。 |
返回：到达的下一条可展示行；结束或失败时返回 null。
stop¶
- API：
public
结束当前对话。
get_current_line¶
- API：
public
获取当前行。
返回：当前可展示行；没有时返回 null。
get_available_responses¶
- API：
public
获取当前可用响应。
返回：响应列表。
is_running¶
- API：
public
检查是否正在运行。
返回：运行中返回 true。
create_runtime_snapshot¶
- API：
public - 首次版本：
5.0.0
创建可存档的运行快照。 快照只保存 Runner 的当前位置和上下文值，不保存对话资源本体。 恢复时由调用方重新提供 GFDialogueResource，避免框架绑定项目存档结构。
返回：运行快照。
结构：
return: 包含 schema_version、is_running、current_line_id、resource_fingerprint 和 context_values 字段的 Dictionary。
restore_runtime_snapshot¶
- API：
public - 首次版本：
5.0.0
func restore_runtime_snapshot( resource: GFDialogueResource, snapshot: Dictionary, context: GFDialogueContext = null ) -> GFDialogueLine:
从运行快照恢复到当前可展示行。 恢复不会重新触发 dialogue_started、line_reached 或 mutation_requested， 也不会重新执行 mutation。调用方可使用返回行刷新自己的 UI。
参数：
| 名称 | 说明 |
|---|---|
resource |
快照对应的对话资源。 |
snapshot |
create_runtime_snapshot() 生成的快照。 |
context |
可选上下文；为空时创建新上下文并恢复快照中的 context_values。 |
返回：恢复后的当前可展示行；快照无效、已结束或资源不匹配时返回 null。
结构：
snapshot: 包含 schema_version、is_running、current_line_id、resource_fingerprint 和 context_values 字段的 Dictionary。
get_debug_snapshot¶
- API：
public
获取运行快照。
返回：调试快照。
结构：
return: 包含 is_running、current_line_id、has_resource 和 context_values 字段的 Dictionary。