Godot SDK

Unity SDK와 같은 서비스를 제공하는 Godot 4.2 이상용 GDScript 애드온입니다.

코드 주석과 API 이름은 SDK와 일치하도록 영어로 유지합니다.

이 페이지의 내용

요구 사항
설치
프로젝트 설정
연결 테스트
코드로 구성하기
MajacloudResult
시그널
기기 저장소
웹 내보내기

요구 사항#

Godot 4.2 이상, GDScript. 데스크톱, 모바일, 웹 내보내기를 지원합니다.
의존성 없음: 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(하드웨어 기반 아님)가 저장됩니다.

웹 내보내기#

내보낸 게임은 HTTPS로 제공하세요. API는 브라우저에 필요한 CORS 헤더를 보냅니다.
user://는 브라우저 저장소에 보관되므로 페이지를 새로고침해도 세션이 유지됩니다.
브라우저가 새 탭을 허용하도록 link_account()는 입력 이벤트(예: 버튼 누름)에서 호출하세요.