跳转至

GFPlatformAdapter

API Reference / Standard / 类索引

  • 路径：addons/gf/standard/platform/gf_platform_adapter.gd
  • 模块：Standard
  • 继承：RefCounted
  • API：public
  • 类别：协议与扩展点 (protocol)
  • 首次版本：9.0.0

外部平台 adapter 协议。 Steam、微信小游戏、主机平台或自建平台实现应继承该类型，把具体 SDK 回调 转换为 GF 的上下文、生命周期事件和桥接结果。该基类不依赖任何平台 SDK。

成员概览

类型 名称 签名
信号 state_changed signal state_changed(previous_state: State, current_state: State)
信号 context_changed signal context_changed(context: GFPlatformRuntimeContext)
信号 lifecycle_event signal lifecycle_event(event: GFPlatformLifecycleEvent)
枚举 State enum State
方法 configure func configure( adapter_id: StringName, platform_id: StringName, contract_ids: PackedStringArray, initial_context: GFPlatformRuntimeContext = null ) -> bool:
方法 get_adapter_id func get_adapter_id() -> StringName:
方法 get_platform_id func get_platform_id() -> StringName:
方法 get_contract_ids func get_contract_ids() -> PackedStringArray:
方法 supports_contract func supports_contract(contract_id: StringName) -> bool:
方法 get_state func get_state() -> State:
方法 is_ready func is_ready() -> bool:
方法 initialize func initialize(options: Dictionary = {}) -> GFAsyncCompletion:
方法 get_context func get_context() -> GFPlatformRuntimeContext:
方法 invoke func invoke(request: GFPlatformBridgeRequest) -> GFPlatformRequestHandle:
方法 poll func poll(delta: float) -> void:
方法 shutdown func shutdown() -> void:
方法 get_debug_snapshot func get_debug_snapshot() -> Dictionary:
方法 _initialize func _initialize(_options: Dictionary) -> void:
方法 _dispatch func _dispatch(_request: GFPlatformBridgeRequest, _handle: GFPlatformRequestHandle) -> bool:
方法 _poll func _poll(_delta: float) -> void:
方法 _cancel_request func _cancel_request(_handle: GFPlatformRequestHandle, _reason: StringName) -> void:
方法 _shutdown func _shutdown() -> void:
方法 _complete_initialization func _complete_initialization(context: GFPlatformRuntimeContext) -> bool:
方法 _fail_initialization func _fail_initialization(error: String, metadata: Dictionary = {}) -> bool:
方法 _publish_context func _publish_context(context: GFPlatformRuntimeContext) -> bool:
方法 _publish_lifecycle_event func _publish_lifecycle_event(event: GFPlatformLifecycleEvent) -> bool:
方法 _succeed_request func _succeed_request( handle: GFPlatformRequestHandle, value: Variant = null, status: StringName = &"ok", metadata: Dictionary = {} ) -> bool:
方法 _fail_request func _fail_request( handle: GFPlatformRequestHandle, status: StringName, error: String, metadata: Dictionary = {} ) -> bool:

信号

state_changed

  • API：public
  • 首次版本：9.0.0
signal state_changed(previous_state: State, current_state: State)

Adapter 状态变化后发出。

参数：

名称 说明
previous_state 变化前状态。
current_state 变化后状态。

context_changed

  • API：public
  • 首次版本：9.0.0
signal context_changed(context: GFPlatformRuntimeContext)

平台运行时上下文变化后发出。

参数：

名称 说明
context 新上下文副本。

lifecycle_event

  • API：public
  • 首次版本：9.0.0
signal lifecycle_event(event: GFPlatformLifecycleEvent)

收到平台生命周期事件后发出。

参数：

名称 说明
event 生命周期事件副本。

枚举

State

  • API：public
  • 首次版本：9.0.0
enum State {
    ## 尚未初始化。
    CREATED,
    ## 正在执行 adapter 初始化。
    INITIALIZING,
    ## 可接受平台请求。
    READY,
    ## 初始化失败。
    FAILED,
    ## 已关闭且不可重新使用。
    SHUTDOWN,
}

Adapter 生命周期状态。

方法

configure

  • API：public
  • 首次版本：9.0.0
func configure( adapter_id: StringName, platform_id: StringName, contract_ids: PackedStringArray, initial_context: GFPlatformRuntimeContext = null ) -> bool:

配置 adapter 身份和支持的桥接契约。 配置只允许在 CREATED 状态执行，防止运行期间改变路由身份。

参数：

名称 说明
adapter_id Adapter 稳定标识。
platform_id 平台稳定标识。
contract_ids 支持的桥接契约 ID。
initial_context 可选初始上下文。

返回：配置成功返回 true。

get_adapter_id

  • API：public
  • 首次版本：9.0.0
func get_adapter_id() -> StringName:

获取 adapter ID。

返回：Adapter ID。

get_platform_id

  • API：public
  • 首次版本：9.0.0
func get_platform_id() -> StringName:

获取平台 ID。

返回：平台 ID。

get_contract_ids

  • API：public
  • 首次版本：9.0.0
func get_contract_ids() -> PackedStringArray:

获取支持的桥接契约 ID 副本。

返回：排序去重后的契约 ID。

supports_contract

  • API：public
  • 首次版本：9.0.0
func supports_contract(contract_id: StringName) -> bool:

检查 adapter 是否支持桥接契约。

参数：

名称 说明
contract_id 桥接契约 ID。

返回：已声明支持时返回 true。

get_state

  • API：public
  • 首次版本：9.0.0
func get_state() -> State:

获取当前状态。

返回：Adapter 状态。

is_ready

  • API：public
  • 首次版本：9.0.0
func is_ready() -> bool:

检查 adapter 是否可接受请求。

返回：READY 状态返回 true。

initialize

  • API：public
  • 首次版本：9.0.0
func initialize(options: Dictionary = {}) -> GFAsyncCompletion:

初始化 adapter。 同一次初始化期间重复调用会返回同一个 completion；READY 状态返回立即成功的 completion。FAILED 或 SHUTDOWN 状态不会隐式重试。

参数：

名称 说明
options Adapter 定义的初始化选项。

返回：初始化完成源，成功结果为 GFPlatformRuntimeContext。

结构：

  • options: Dictionary adapter-defined initialization options.

get_context

  • API：public
  • 首次版本：9.0.0
func get_context() -> GFPlatformRuntimeContext:

获取运行时上下文副本。

返回：平台运行时上下文副本。

invoke

  • API：public
  • 首次版本：9.0.0
func invoke(request: GFPlatformBridgeRequest) -> GFPlatformRequestHandle:

发起桥接请求。 该入口统一做状态、请求身份和契约支持检查，具体 adapter 只重写 _dispatch。

参数：

名称 说明
request 平台桥接请求。

返回：一次性请求句柄。

poll

  • API：public
  • 首次版本：9.0.0
func poll(delta: float) -> void:

推进需要 callback pump 的平台 SDK。

参数：

名称 说明
delta 未受游戏暂停和时间缩放影响的帧间隔。

shutdown

  • API：public
  • 首次版本：9.0.0
func shutdown() -> void:

关闭 adapter 并释放平台资源。 SHUTDOWN 为终态；需要重新连接时应创建新 adapter 实例。

get_debug_snapshot

  • API：public
  • 首次版本：9.0.0
func get_debug_snapshot() -> Dictionary:

获取 adapter 调试快照。

返回：Adapter 身份、状态、契约与上下文字典。

结构：

  • return: Dictionary with adapter_id, platform_id, state, state_name, contract_ids, and context.

_initialize

  • API：protected
  • 首次版本：9.0.0
func _initialize(_options: Dictionary) -> void:

执行平台初始化。 异步实现应在回调中调用 _complete_initialization 或 _fail_initialization； 基类实现立即使用当前上下文完成。

参数：

名称 说明
_options Adapter 初始化选项。

结构：

  • _options: Dictionary adapter-defined initialization options.

_dispatch

  • API：protected
  • 首次版本：9.0.0
func _dispatch(_request: GFPlatformBridgeRequest, _handle: GFPlatformRequestHandle) -> bool:

派发平台请求。 实现可同步或异步调用 _succeed_request / _fail_request。返回 false 表示请求 未被接受，基类会生成 dispatch_rejected 终态。

参数：

名称 说明
_request 请求副本。
_handle 由基类拥有的请求句柄。

返回：请求被接受时返回 true。

_poll

  • API：protected
  • 首次版本：9.0.0
func _poll(_delta: float) -> void:

推进底层平台 callback pump。

参数：

名称 说明
_delta 未缩放帧间隔。

_cancel_request

  • API：protected
  • 首次版本：9.0.0
func _cancel_request(_handle: GFPlatformRequestHandle, _reason: StringName) -> void:

处理请求取消或超时通知。

参数：

名称 说明
_handle 已进入取消或超时终态的句柄。
_reason 取消原因。

_shutdown

  • API：protected
  • 首次版本：9.0.0
func _shutdown() -> void:

释放底层平台资源。

_complete_initialization

  • API：protected
  • 首次版本：9.0.0
func _complete_initialization(context: GFPlatformRuntimeContext) -> bool:

完成 adapter 初始化。

参数：

名称 说明
context 已验证的平台上下文。

返回：首次成功完成返回 true。

_fail_initialization

  • API：protected
  • 首次版本：9.0.0
func _fail_initialization(error: String, metadata: Dictionary = {}) -> bool:

标记 adapter 初始化失败。

参数：

名称 说明
error 失败说明。
metadata Adapter 定义的失败元数据。

返回：首次失败完成返回 true。

结构：

  • metadata: Dictionary adapter-defined initialization failure metadata.

_publish_context

  • API：protected
  • 首次版本：9.0.0
func _publish_context(context: GFPlatformRuntimeContext) -> bool:

发布更新后的平台上下文。

参数：

名称 说明
context 新上下文。

返回：身份匹配且发布成功返回 true。

_publish_lifecycle_event

  • API：protected
  • 首次版本：9.0.0
func _publish_lifecycle_event(event: GFPlatformLifecycleEvent) -> bool:

发布平台生命周期事件。 基类会覆盖 adapter 提供的 sequence，确保每个 adapter 的事件严格单调。

参数：

名称 说明
event 生命周期事件。

返回：事件有效并已发布时返回 true。

_succeed_request

  • API：protected
  • 首次版本：9.0.0
func _succeed_request( handle: GFPlatformRequestHandle, value: Variant = null, status: StringName = &"ok", metadata: Dictionary = {} ) -> bool:

以成功结果完成请求。

参数：

名称 说明
handle 待完成句柄。
value Adapter 返回值。
status 成功状态。
metadata Adapter 结果元数据。

返回：首次完成成功返回 true。

结构：

  • value: Adapter-defined result value.
  • metadata: Dictionary adapter-defined result metadata.

_fail_request

  • API：protected
  • 首次版本：9.0.0
func _fail_request( handle: GFPlatformRequestHandle, status: StringName, error: String, metadata: Dictionary = {} ) -> bool:

以失败结果完成请求。

参数：

名称 说明
handle 待完成句柄。
status 稳定失败状态。
error 失败说明。
metadata Adapter 失败元数据。

返回：首次完成成功返回 true。

结构：

  • metadata: Dictionary adapter-defined failure metadata.