Godot SDK

适用于 Godot 4.2+ 的 GDScript 插件，提供与 Unity SDK 相同的服务。

代码注释和 API 名称保留英文，以便与 SDK 保持一致。

本页内容

要求
安装
项目设置
测试连接
通过代码配置
MajacloudResult
信号
设备上的存储
Web 导出

要求#

Godot 4.2 或更高版本，GDScript。支持桌面、移动端和 Web 导出。
无依赖：仅使用 Godot 的 HTTPRequest、Crypto 和 FileAccess。

安装#

从项目页面或下载页面下载 Godot SDK 的 .zip。
将其解压到你的项目中，使文件夹为 res://addons/majacloud（保持名称不变）。
Project ▸ Project Settings ▸ Plugins：启用 Majacloud。插件会添加 Majacloud 自动加载。

项目设置#

插件会在 Project Settings ▸ General ▸ Majacloud 下添加以下设置项：

设置项	默认值	含义
`connection/base_url`		此安装的地址。
`connection/project_id`		控制台 ▸ API 密钥。
`connection/client_key`		公开的 `pk_live_…` 密钥。
`connection/config_public_key`		由 Test connection 自动填写；用于固定远程配置验证。
`advanced/timeout_seconds`	`15`	请求因 `timeout` 失败前等待的秒数。
`advanced/max_retries`	`2`	遇到网络和服务器错误时，安全请求的重试次数。
`advanced/fetch_config_on_start`	`true`	游戏启动时拉取远程配置。
`advanced/log_requests`	`false`	将每个请求打印到输出面板。

测试连接#

Project ▸ Tools ▸ Majacloud: Test connection 会用你的设置调用 API，显示项目名称和套餐，并将远程配置公钥保存到 majacloud/connection/config_public_key。

通过代码配置#

调用 configure() 可在代码中切换环境。它会在本次会话的剩余时间内替换原有设置：

GDScript

# Switch environments from code; the last argument pins the Remote Config key (PEM)
Majacloud.configure("https://staging.yourstudio.com", "<project id>", "pk_live_…", public_key_pem)

MajacloudResult#

每个调用都可以 await，并返回一个 MajacloudResult。遇到网络或服务器错误时它绝不会崩溃。

字段	含义
`ok`	调用成功时为 `true`。
`value`	以 Dictionary 形式返回的 REST 响应（参见 REST 参考）；整数以 `int` 类型返回。
`error`	成功时为空，否则为稳定的错误码，例如 `conflict` 或 `network`（参见错误码）。
`message`	可读的说明。
`status`	HTTP 状态码；未连接到服务器时为 `0`。
`request_id`	可在日志页面中搜索。
`details`	服务器返回的额外数据，例如 `next_claim_at`。
	`is_retryable()` 和 `is_not_found()`。

信号#

连接以下信号来更新你的 UI：

GDScript

func _ready() -> void:
	Majacloud.auth.player_changed.connect(_on_player_changed)
	Majacloud.auth.session_expired.connect(func(): show_sign_in_screen())
	Majacloud.remote_config.updated.connect(func(): apply_balance())

func _on_player_changed(player: Dictionary) -> void:
	$NameLabel.text = player.get("display_name", "")

设备上的存储#

游客会话以加密形式保存在 user://majacloud/<project id>.session 中，并在下次启动时恢复。经过验证的远程配置会缓存在同一位置，供离线游玩使用；user://majacloud/device.id 保存一个随机生成的安装 ID（不基于硬件）。

Web 导出#

请通过 HTTPS 提供导出内容；API 会发送浏览器所需的 CORS 头。
user:// 保存在浏览器存储中，因此会话在页面刷新后依然有效。
请在输入事件（例如按钮按下）中调用 link_account()，这样浏览器才会允许打开新标签页。