ZUKU Game Cloud

레거시 ZCloud(Economy · ZVM · ZASE · Pay · WebFunc) 개념을 zuku v1 API로 재정립한 온라인 게임 백엔드입니다.

목차

1. 개요
2. 프로젝트
3. Economy (지갑)
4. Vars (클라우드 변수)
5. Saves (클라우드 세이브)
6. Pay (IAP)
7. Functions (서버 함수)
8. 대시보드

---

1. 개요

인증: 모든 엔드포인트는 Authorization: Bearer <session_token> 필요.

Base URL: https://zuzunza.com/api/v1/cloud

---

2. 프로젝트

게임 클라우드는 프로젝트 단위로 격리됩니다.

프로젝트 생성

POST /api/v1/cloud/projects
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "내 RPG",
  "description": "온라인 멀티 RPG",
  "jump_content_id": "cnt_jump_abc123"
}

프로젝트 목록

GET /api/v1/cloud/projects
Authorization: Bearer <token>

---

3. Economy (지갑)

GET /api/v1/cloud/economy/balance?projectId=<uuid>
Authorization: Bearer <token>

응답:

{
  "success": true,
  "data": {
    "POINT": 1500,
    "CASH_KRW": 0
  }
}

• POINT: 게임 내 재화
• CASH_KRW: 원화 잔액 (Pay confirm 시 grant)

---

4. Vars (클라우드 변수)

레거시 ZVM과 동일한 개념. currency scope는 클라이언트에서 변경 불가 (자기 mint 방지).

읽기

POST /api/v1/cloud/vars/get
Content-Type: application/json

{
  "projectId": "<uuid>",
  "scope": "user",
  "key": "high_score"
}

변경

POST /api/v1/cloud/vars/mutate
Content-Type: application/json

{
  "projectId": "<uuid>",
  "scope": "user",
  "key": "high_score",
  "op": "max",
  "num": 9999
}

op: set · incr · decr · max · min · cas

scope: global (전체 공유) · user (플레이어별)

---

5. Saves (클라우드 세이브)

레거시 ZASE. 인라인 JSON, 슬롯당 256KB 한도.

저장

POST /api/v1/cloud/saves/save

{
  "projectId": "<uuid>",
  "slot": "slot1",
  "data": { "level": 5, "inventory": ["sword", "potion"] }
}

로드

POST /api/v1/cloud/saves/load

{
  "projectId": "<uuid>",
  "slot": "slot1"
}

슬롯 목록

GET /api/v1/cloud/saves/list?projectId=<uuid>

---

6. Pay (IAP)

상품 목록

GET /api/v1/cloud/pay/products?projectId=<uuid>

구매 세션 생성

POST /api/v1/cloud/pay/session

{
  "projectId": "<uuid>",
  "productId": "<product-uuid>"
}

세션 TTL: 10분. status: pending → paid (confirm 후).

결제 확인

POST /api/v1/cloud/pay/confirm

{
  "sessionId": "<session-uuid>"
}

---

7. Functions (서버 함수)

레거시 WebFunc. Deno 런타임 연동은 로드맵.

함수 등록/수정

POST /api/v1/cloud/functions

{
  "projectId": "<uuid>",
  "name": "grantReward",
  "sourceCode": "// Deno function source"
}

함수 호출 (published 상태)

POST /api/v1/cloud/functions/<id>/invoke

{
  "projectId": "<uuid>",
  "input": { "amount": 100 }
}

---

8. 대시보드

GET /api/v1/cloud/dashboard/summary?projectId=<uuid>&days=30

프로젝트 소유자만 조회. 이벤트별 사용량 breakdown 반환.

---

Jump SDK 연동

브라우저 Jump 게임에서:

import { ZukuCloud } from '@zuku/cloud-sdk';

const cloud = new ZukuCloud({ projectId: '...', getToken: () => sessionToken });

// 변수
await cloud.vars.mutate({ scope: 'user', key: 'score', op: 'max', num: 1000 });

// 세이브
await cloud.saves.save({ slot: 'default', data: gameState });

샘플: samples/cloud-rpg/ 참고.