개발 문서

<script src="/__neko/sdk.js"></script>
<script>
  const { sdk, NekoSdkError } = window.Nekoland;
</script>

npm i @launchercapital/nekoland-sdk

import { NekoSDK, NekoSdkError } from "@launchercapital/nekoland-sdk";

const sdk = new NekoSDK();

// payments·storage·player 는 init 을 기다린 뒤에 (안 그러면 NOT_INITIALIZED)
// on()·track() 은 먼저 불러도 된다. init 이 끝나면 플랫폼 로딩 화면이 닫힌다
const player = await sdk.init({ gameId: "gem-rush" }); // nekogame.json 의 gameId

sdk.on("pause", () => { /* 게임 루프를 멈추고 소리를 끈다 */ });
sdk.on("resume", () => { /* 소리를 되돌린다 */ });
sdk.on("player.changed", () => { /* 로그인·계정 전환 → 저장을 다시 불러온다 */ });

await sdk.init({ gameId: "gem-rush", manualReady: true });

for (let i = 0; i < assets.length; i++) {
  await load(assets[i]);
  sdk.loadingProgress((i + 1) / assets.length); // 0..1
}
await sdk.gameReady(); // 첫 화면이 떴다 → 로딩 화면이 닫힌다

sdk.gameplayStart(); // 메뉴를 벗어나 실제 플레이 시작, 일시정지 해제
sdk.gameplayStop();  // 메뉴·일시정지·게임 오버

// 플랫폼 메뉴 버튼(왼쪽 위)을 피해 HUD 배치
layoutHud(sdk.insets.menu); // { x, y, width, height } 또는 null
sdk.on("insets.changed", (i) => layoutHud(i.menu));

// Esc·메뉴 버튼 → 게임 일시정지 (pause + menu.open)
sdk.on("menu.open", () => showPausedOverlay());
sdk.on("menu.close", () => hidePausedOverlay());

// Esc 를 직접 쓰면 끄고, 게임의 일시정지 화면에서 메뉴 열기
await sdk.init({ gameId: "my-game", escapeMenu: false });
pauseScreen.onMenuClick = () => sdk.openMenu();

const { playerId, displayName, avatarUrl, isGuest, locale } = sdk.player;

if (sdk.player.isGuest) {
  try {
    await sdk.login(); // 플랫폼의 로그인·가입 창
  } catch {
    // 게스트로 남았다
  }
}

const CONSUMABLES = new Set(["gems_500"]); // 구매 기록에는 type 이 없다
const owned = new Set();                   // 영구 상품

async function grant(p) {
  if (!CONSUMABLES.has(p.productId)) { owned.add(p.productId); return; } // 영구 상품: 열어 주기만, consume 하지 않는다
  if (p.state !== "completed") return;                                   // 이미 지급 끝
  if (!save.grantedIds.includes(p.purchaseId)) {
    save.gems += 500;
    save.grantedIds = [...save.grantedIds, p.purchaseId].slice(-50);
    await sdk.storage.set({ save: JSON.stringify(save) });               // ① 지급을 먼저 저장
  }
  await sdk.payments.consume(p.purchaseId);                              // ② 그다음 consume
}

// 시작할 때마다: 결제됐지만 아직 지급하지 않은 것
for (const p of await sdk.payments.getPurchases()) await grant(p);

// 구매 버튼
try {
  await grant(await sdk.payments.purchase({ productId: "gems_500" }));
} catch (e) {
  if (e instanceof NekoSdkError && e.code === "USER_CANCELLED") return;
  // NOT_LOGGED_IN · INSUFFICIENT_COINS · ALREADY_OWNED · PURCHASE_PENDING · PRICE_CHANGED · INVALID_PRICE · PRODUCT_NOT_FOUND · TIMEOUT
}

const products = await sdk.payments.getProducts(); // 특정 상품만: getProducts(["gems_500"])
// [{ productId, type, title, description, priceCoins, variablePrice?, iconUrl? }]

// 값은 문자열이라 JSON 으로 저장
const raw = (await sdk.storage.get(["save"])).save; // 없는 키는 null
const save = raw ? JSON.parse(raw) : { gems: 0, grantedIds: [] };

save.gems += 10;
await sdk.storage.set({ save: JSON.stringify(save) }); // 다른 키는 그대로 두고 합쳐진다

// [{ playerId, displayName, avatarUrl?, online, inGame, hasPlayed }] — 게스트는 빈 목록
const friends = await sdk.friends.list();
const playingNow = friends.filter((f) => f.inGame);

// 플랫폼 친구 선택 창 → 고른 친구의 네코랜드 채팅에 초대 카드
try {
  const { sent } = await sdk.friends.invite({ data: roomCode }); // data: 500자까지
} catch (e) {
  // USER_CANCELLED: 창을 닫음 · NOT_LOGGED_IN: 게스트가 로그인하지 않음
}

// 같이 플레이한 사람에게 친구 신청 (플랫폼이 확인 창을 띄움)
const { status } = await sdk.friends.add(otherPlayerId); // "sent"(상대 수락 대기) 또는 "friends"

// 친구의 초대로 열렸는지
if (sdk.invite) {
  const { fromPlayerId, fromName, data } = sdk.invite; // data 를 안 보냈으면 null
  joinRoom(data);
}

sdk.track("level_complete", { level: 3, stars: 2 });
sdk.track("tutorial_complete");

// 게임에서
const { token, expiresAt } = await sdk.getPlayerToken(); // 1시간 유효
await fetch("https://api.example.com/session", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ token }),
});

import { NekoServer, NekoServerError } from "@launchercapital/nekoland-server";

const neko = new NekoServer({
  gameId: "gem-rush",                             // nekogame.json 의 gameId
  apiKey: process.env.NEKO_GAME_API_KEY,          // 개발자 콘솔 → 서버 연동 (서버에만!)
  webhookSecret: process.env.NEKO_WEBHOOK_SECRET, // `neko webhook set` 이 한 번 보여 준다
});

// 게임이 sdk.getPlayerToken() 으로 받아 보낸 토큰
const player = await neko.verifyPlayerToken(token);
// { playerId, displayName, isGuest, sandbox, expiresAt }

await neko.verifyReceipt(signedReceipt);              // 클라이언트가 보낸 영수증 검증
await neko.getPurchase(purchaseId);
await neko.listPlayerPurchases(player.playerId);      // 놓친 구매 따라잡기
await neko.refund(purchaseId, "Accidental purchase"); // 개발자가 직접 환불

neko webhook set https://api.example.com/nekoland  # 처음에 whsec_… 시크릿을 보여 준다
neko webhook test             # ping 을 보낸다
neko webhook                  # 주소와 최근 전송 기록
neko webhook secret --rotate  # 시크릿 다시 만들기

// JSON 으로 바꾸기 전의 본문 문자열을 그대로
const ev = await neko.verifyWebhook(rawBody, req.headers.get("nekoland-signature"));
switch (ev.type) {
  case "purchase.completed":
    // 지급을 저장하고(ev.data.purchaseId 로 중복 제거) consume
    await neko.consume(ev.data.purchaseId);
    break;
  case "purchase.refunded":  /* 지급한 것을 회수 */ break;
  case "player.suspended":   /* 접속 중이면 끊기 */ break;
  case "player.updated":     /* 닉네임·게스트 여부가 바뀜 */ break;
}

const player = await neko.verifyPlayerToken(token);
const friends = await neko.getFriends(player.playerId);
// [{ playerId, hasPlayed }] — 내 게임 기준 playerId

using Nekoland;

async void Start()
{
    var player = await NekoSDK.InitAsync();             // 항상 맨 먼저
    NekoSDK.OnPause  += () => Time.timeScale = 0;
    NekoSDK.OnResume += () => Time.timeScale = 1;
    NekoSDK.OnPlayerChanged += async p => await LoadSave();

    await LoadSave();
    foreach (var p in await NekoSDK.Payments.GetPurchasesAsync()) await Grant(p);
    await NekoSDK.GameReadyAsync();                     // 플랫폼 로딩 화면을 닫는다
    NekoSDK.GameplayStart();
}

func _ready():
	var res := await NekoSDK.init()                 # 항상 맨 먼저
	if not res.ok: return
	NekoSDK.paused.connect(func(): get_tree().paused = true)
	NekoSDK.resumed.connect(func(): get_tree().paused = false)
	NekoSDK.player_changed.connect(func(p): load_save())

	await load_save()
	for p in (await NekoSDK.payments_get_purchases()).data: await grant(p)
	NekoSDK.gameplay_start()