Godot SDK

Addon GDScript cho Godot 4.2+ với các dịch vụ giống Unity SDK.

Chú thích trong mã và tên API được giữ nguyên tiếng Anh để khớp với SDK.

Trên trang này

Yêu cầu
Cài đặt
Cài đặt dự án
Kiểm tra kết nối
Cấu hình bằng mã
MajacloudResult
Signal
Lưu trữ trên thiết bị
Xuất bản cho web

Yêu cầu#

Godot 4.2 trở lên, GDScript. Hỗ trợ xuất cho desktop, di động và Web.
Không phụ thuộc thư viện: chỉ dùng HTTPRequest, Crypto và FileAccess của Godot.

Cài đặt#

Tải file .zip của Godot SDK từ trang dự án hoặc trang tải xuống.
Giải nén vào dự án sao cho thư mục là res://addons/majacloud (giữ nguyên tên).
Project ▸ Project Settings ▸ Plugins: bật Majacloud. Plugin sẽ thêm autoload Majacloud.

Cài đặt dự án#

Plugin thêm các mục sau vào Project Settings ▸ General ▸ Majacloud:

Cài đặt	Mặc định	Ý nghĩa
`connection/base_url`		Địa chỉ của bản cài đặt này.
`connection/project_id`		Bảng điều khiển ▸ Khóa API.
`connection/client_key`		Khóa công khai `pk_live_…`.
`connection/config_public_key`		Được điền bởi Test connection; ghim việc xác minh cấu hình từ xa.
`advanced/timeout_seconds`	`15`	Số giây trước khi yêu cầu thất bại với `timeout`.
`advanced/max_retries`	`2`	Số lần thử lại các yêu cầu an toàn khi gặp lỗi mạng và lỗi máy chủ.
`advanced/fetch_config_on_start`	`true`	Tải cấu hình từ xa khi game khởi động.
`advanced/log_requests`	`false`	In mọi yêu cầu ra Output.

Kiểm tra kết nối#

Project ▸ Tools ▸ Majacloud: Test connection gọi API với cài đặt của bạn, hiển thị tên dự án và gói, rồi lưu khóa công khai của cấu hình từ xa vào majacloud/connection/config_public_key.

Cấu hình bằng mã#

Gọi configure() để chuyển môi trường bằng mã. Lệnh này thay thế cài đặt cho phần còn lại của phiên:

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#

Mọi lệnh gọi đều được await và trả về một MajacloudResult. Game không bao giờ bị crash khi gặp lỗi mạng hay lỗi máy chủ.

Trường	Ý nghĩa
`ok`	`true` khi lệnh gọi thành công.
`value`	Phản hồi REST dưới dạng Dictionary (xem tài liệu tham khảo REST); số nguyên được trả về dưới dạng `int`.
`error`	Rỗng khi thành công, nếu không là một mã ổn định như `conflict` hoặc `network` (xem mã lỗi).
`message`	Lời giải thích dễ đọc.
`status`	Mã trạng thái HTTP, `0` khi không kết nối được máy chủ.
`request_id`	Tìm giá trị này trên trang Nhật ký.
`details`	Dữ liệu bổ sung từ máy chủ, ví dụ `next_claim_at`.
	`is_retryable()` và `is_not_found()`.

Signal#

Kết nối với các signal sau để cập nhật 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", "")

Lưu trữ trên thiết bị#

Phiên khách được lưu mã hóa trong user://majacloud/<project id>.session và khôi phục ở lần mở game tiếp theo. Cấu hình từ xa đã xác minh được lưu đệm ngay bên cạnh để chơi offline, và user://majacloud/device.id chứa một ID cài đặt ngẫu nhiên (không dựa trên phần cứng).

Xuất bản cho web#

Phục vụ bản xuất qua HTTPS; API gửi các header CORS mà trình duyệt cần.
user:// được lưu trong bộ nhớ của trình duyệt, nên phiên vẫn còn sau khi tải lại trang.
Gọi link_account() từ một sự kiện nhập (ví dụ khi nhấn nút) để trình duyệt cho phép mở tab mới.