@oyna360/game-sdk 0.5.1

package/dist/types.d.ts

@@ -0,0 +1,112 @@
+/** Public SDK contract — keep in sync with platform `@platform/types` when protocol changes. */
+export declare const SDK_VERSION = "0.5.1";
+export type AvatarPresetKind = 'procedural' | 'glb';
+export interface SdkLobbyAvatar {
+    presetId: string;
+    presetKey: string;
+    presetKind: AvatarPresetKind;
+    customConfig: Record<string, unknown>;
+}
+export interface SdkUser {
+    id: string;
+    username: string;
+    displayName: string;
+    avatarUrl: string | null;
+}
+export interface SdkSession {
+    id: string;
+    token: string;
+}
+export interface SdkGameInfo {
+    slug: string;
+    name: string;
+}
+/** Same shape as platform `platform:init` / lobby SdkInitPayload. */
+export interface SdkInitPayload {
+    session: SdkSession;
+    user: SdkUser;
+    game: SdkGameInfo;
+    avatar: SdkLobbyAvatar;
+    avatarBases?: Array<{
+        id: string;
+        glbUrl: string;
+    }>;
+    lobby?: {
+        wsUrl: string;
+        roomId: string;
+        strictRoom?: boolean;
+    };
+}
+export interface PlatformInitMessage extends SdkInitPayload {
+    type: 'platform:init';
+    version: string;
+}
+export interface PlatformSdkInitOptions {
+    /** Iframe wait timeout (ms). Direct mode uses a short probe then bootstrap. */
+    timeout?: number;
+    /**
+     * Platform API base including `/api`, e.g. `https://oyna360.ir/api`.
+     * Required for Direct Development Mode.
+     */
+    platformUrl?: string;
+    /**
+     * Platform web origin for the authorize page, e.g. `https://oyna360.ir`.
+     * Defaults to origin of `platformUrl` without `/api`.
+     */
+    platformWebUrl?: string;
+    /** Published game slug. Required for Direct Development Mode. */
+    gameSlug?: string;
+}
+export interface LeaderboardEntry {
+    rank: number;
+    score: number;
+    achievedAt: string;
+    user: {
+        displayName: string;
+        username: string;
+        avatarUrl: string | null;
+    };
+}
+export interface LeaderboardResponse {
+    gameSlug: string;
+    entries: LeaderboardEntry[];
+}
+export interface SubmitScoreResponse {
+    score: number;
+    previousBest: number | null;
+    isNewBest: boolean;
+    rank: number;
+}
+export interface AchievementItem {
+    key: string;
+    title: string;
+    description: string | null;
+    iconUrl: string | null;
+    sortOrder: number;
+    unlocked: boolean;
+    unlockedAt: string | null;
+}
+export interface AchievementsResponse {
+    gameSlug: string;
+    achievements: AchievementItem[];
+}
+export interface UnlockAchievementResponse {
+    key: string;
+    title: string;
+    unlocked: boolean;
+    unlockedAt: string;
+    alreadyUnlocked: boolean;
+}
+export interface WalletBalanceResponse {
+    gems: number;
+    coinsPerGem: number;
+    gameSlug: string;
+}
+export interface ConvertGemsResponse {
+    gemsSpent: number;
+    coinsReceived: number;
+    coinsPerGem: number;
+    gemsRemaining: number;
+    gameSlug: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/** Public SDK contract — keep in sync with platform `@platform/types` when protocol changes. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+exports.SDK_VERSION = '0.5.1';
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,gGAAgG;;;AAEnF,QAAA,WAAW,GAAG,OAAO,CAAC"}

package/docs/00-overview.md

@@ -0,0 +1,71 @@
+# نمای کلی — `@oyna360/game-sdk`
+
+این سند برای **بازی‌سازی** است که می‌خواهد بازی‌اش را به oyna360 وصل کند.
+
+---
+
+## این SDK چه کار می‌کند؟
+
+پل رسمی بین **بازی** و **پلتفرم oyna360**:
+
+- گرفتن کاربر، سشن، اطلاعات بازی
+- در صورت وجود: آواتار لابی و اطلاعات اتصال لابی (`lobby.wsUrl`, `roomId`)
+- ثبت امتیاز، لیدربورد، دستاورد، کیف‌پول جِم (در حالت iframe / Production)
+
+بازی را مجبور نمی‌کند موتور خاصی (Three، Babylon، Unity Web، …) داشته باشد.
+
+---
+
+## این SDK چه کار نمی‌کند؟
+
+| کار | کجا |
+|-----|-----|
+| لابی ۳D، آواتار متحرک، چت لابی، WebSocket بازیکنان | `@oyna360/lobby-sdk` |
+| سرور اختصاصی گیم‌پلی شما | سرور خودتان |
+| ذخیره پسورد یا توکن دائمی داخل بازی | نباید انجام شود |
+
+دو پکیج را قاطی یا fork-merge نکنید.
+
+---
+
+## معماری
+
+```text
+                    oyna360 Platform
+                           │
+           ┌───────────────┴───────────────┐
+           │                               │
+      Production                      Direct Dev
+   /play/{slug} + iframe            بازی روی origin شما
+           │                               │
+           └───────────────┬───────────────┘
+                           ▼
+                  @oyna360/game-sdk
+                           │
+                    SdkInitPayload
+                           │
+              ┌────────────┴────────────┐
+              ▼                         ▼
+     گیم‌پلی / امتیاز            @oyna360/lobby-sdk
+     (score, wallet, …)          (لابی ۳D اختیاری)
+```
+
+---
+
+## چه زمانی فقط game-sdk؟ چه زمانی هر دو؟
+
+| نوع بازی | game-sdk | lobby-sdk |
+|----------|:--------:|:---------:|
+| امتیاز / سشن / جِم بدون لابی ۳D | لازم | نه |
+| لابی ۳D قبل از مسابقه + بعداً گیم‌پلی | لازم | لازم |
+| فقط تست UI بدون شبکه | — | `createDev()` لابی (Fake) |
+
+---
+
+## نسخه و سازگاری
+
+- نسخه پکیج با `PlatformSDK.version` خوانده می‌شود.
+- در ادمین بازی فیلد `minSdkVersion` را طوری بگذارید که با SDK نصب‌شده شما سازگار باشد.
+- Semantic Versioning: تغییر breaking در major.
+
+بعدی: [01-shoro.md](./01-shoro.md)

package/docs/01-shoro.md

@@ -0,0 +1,80 @@
+# نصب و پیش‌نیاز
+
+## نصب
+
+```bash
+npm install github:mamadjavadrasti/oyna360-game-sdk#v0.5.0
+```
+
+Import:
+
+```ts
+import { PlatformSDK } from '@oyna360/game-sdk';
+// یا
+import { init, getUser, submitScore } from '@oyna360/game-sdk';
+```
+
+---
+
+## پیش‌نیاز ثبت بازی در ادمین oyna360
+
+| فیلد | توضیح |
+|------|--------|
+| `slug` | شناسه یکتای بازی در URL: `/play/{slug}` |
+| `entryUrl` | آدرس باندل بازی (Production یا در Dev مثلاً `http://localhost:5180`) |
+| `allowedOrigins` | لیست originهای مجاز بازی به‌صورت `scheme://host:port` |
+| `minSdkVersion` | حداقل نسخه game-sdk (مثلاً `0.5.0`) |
+| وضعیت | بازی باید Published باشد |
+
+### مثال Origin
+
+درست:
+
+- `https://games.example.com`
+- `http://localhost:5180`
+- `http://127.0.0.1:5173`
+- `http://192.168.1.20:5180`
+
+غلط:
+
+- فقط `localhost` بدون scheme
+- `*`
+- path مثل `http://localhost:5180/game/` به‌جای origin (origin همان `http://localhost:5180` است)
+
+---
+
+## Production — جریان بازیکن
+
+1. بازیکن در oyna360 لاگین می‌کند.
+2. به `/play/{slug}` می‌رود.
+3. پلتفرم سشن بازی می‌سازد و بازی را در iframe از `entryUrl` لود می‌کند.
+4. game-sdk با `platform:ready` اعلام آمادگی می‌کند.
+5. پلتفرم `platform:init` می‌فرستد.
+6. `PlatformSDK.init()` resolve می‌شود.
+
+بازی را **مستقیم** با باز کردن `entryUrl` در تب خالی تست Production نکنید؛ بدون parent، مسیر iframe کار نمی‌کند (مگر Direct Development را پیکربندی کرده باشید).
+
+---
+
+## Development — دو راه
+
+### الف) Direct Development (پیشنهادی اگر پلتفرم لوکال ندارید)
+
+بازی روی Vite؛ اتصال به سرور واقعی oyna360.  
+راهنما: [09-direct-development.md](./09-direct-development.md)
+
+### ب) iframe با entryUrl لوکال
+
+1. در ادمین موقتاً `entryUrl` = `http://localhost:PORT`
+2. `allowedOrigins` شامل همان origin
+3. از `/play/{slug}` روی سرور (یا پلتفرم لوکال) وارد شوید
+
+---
+
+## امنیت برای بازی‌ساز
+
+- `session.token` را در localStorage / Git نگذارید.
+- USER/PASS پلتفرم را در `.env` بازی نگذارید.
+- در Direct Mode از Authorize رسمی استفاده کنید؛ توکن یک‌بارمصرف است.
+
+بعدی: [02-init.md](./02-init.md)

package/docs/02-init.md

@@ -0,0 +1,136 @@
+# `init()` و Platform Context
+
+اولین فراخوانی تقریباً همیشه `PlatformSDK.init()` است.
+
+## امضا
+
+```ts
+function init(options?: PlatformSdkInitOptions): Promise<SdkInitPayload>;
+
+interface PlatformSdkInitOptions {
+  /** حداکثر انتظار (ms). در iframe پیش‌فرض ~10s؛ در Direct برای authorize می‌توانید بیشتر بدهید. */
+  timeout?: number;
+  /** پایه API با `/api` — الزامی در Direct Development */
+  platformUrl?: string;
+  /** origin وب پلتفرم برای صفحه Authorize — در Direct اگر API و Web جدا باشند الزامی */
+  platformWebUrl?: string;
+  /** slug بازی published — الزامی در Direct Development */
+  gameSlug?: string;
+}
+```
+
+جایگزین تنظیمات Direct:
+
+```ts
+window.__OYNA360_DEV__ = {
+  platformUrl: 'https://oyna360.ir/api',
+  platformWebUrl: 'https://oyna360.ir',
+  gameSlug: 'my-game',
+};
+```
+
+---
+
+## خروجی — `SdkInitPayload`
+
+همان Context استاندارد Production (`platform:init`):
+
+```ts
+interface SdkInitPayload {
+  user: SdkUser;
+  session: SdkSession;
+  game: SdkGameInfo;
+  avatar: SdkLobbyAvatar;
+  avatarBases?: Array<{ id: string; glbUrl: string }>;
+  lobby?: {
+    wsUrl: string;      // مثلاً https://oyna360.ir/lobby
+    roomId: string;     // مثلاً game:my-game
+    strictRoom?: boolean;
+  };
+}
+```
+
+| فیلد | کاربرد |
+|------|--------|
+| `user` | نمایش نام، id |
+| `session` | `{ id, token }` — سشن بازی ephemeral |
+| `game` | `slug` / `name` |
+| `avatar` | ظاهر لابی برای lobby-sdk |
+| `avatarBases` | کاتالوگ GLB مشترک (اختیاری) |
+| `lobby` | آدرس WebSocket و اتاق — **هاردکد نکنید** |
+
+---
+
+## رفتار بر اساس محیط
+
+### 1) داخل iframe پلتفرم (Production)
+
+1. SDK در صورت embed بودن، `platform:ready` به parent می‌فرستد.
+2. منتظر `platform:init` می‌ماند.
+3. Context را ذخیره می‌کند و همان را روی `window` هم برای lobby-sdk منتشر می‌کند.
+
+```ts
+const ctx = await PlatformSDK.init({ timeout: 15_000 });
+```
+
+### 2) تب مستقیم / بدون parent (Direct Development)
+
+1. اگر `platformUrl` + `gameSlug` نباشد → خطای واضح.
+2. صفحه `/dev/game-auth` (popup یا redirect) باز می‌شود.
+3. با اکانت واقعی لاگین می‌کنید.
+4. code یک‌بارمصرف → `exchange` → همان `SdkInitPayload`.
+
+```ts
+const ctx = await PlatformSDK.init({
+  platformUrl: 'https://oyna360.ir/api',
+  platformWebUrl: 'https://oyna360.ir',
+  gameSlug: 'my-game',
+  timeout: 120_000,
+});
+```
+
+### 3) Idempotent
+
+اگر قبلاً init شده باشد، فراخوانی بعدی همان Promise/payload را می‌دهد.
+
+---
+
+## بعد از init
+
+```ts
+PlatformSDK.isReady();           // true
+PlatformSDK.getUser();           // SdkUser | null
+PlatformSDK.getSession();        // SdkSession | null
+PlatformSDK.getInitPayload();    // SdkInitPayload | null  (کامل)
+```
+
+---
+
+## تحویل به lobby-sdk
+
+روش توصیه‌شده:
+
+```ts
+const init = await PlatformSDK.init({ /* … */ });
+await PlatformLobby.create({
+  canvas,
+  platformInit: init,
+  roomId: init.lobby!.roomId,
+  wsUrl: init.lobby!.wsUrl,
+});
+```
+
+یا بعد از `init()` می‌توانید `PlatformLobby.createFromPlatform(canvas)` را بزنید (SDK لابی از Context منتشرشده روی window استفاده می‌کند).
+
+---
+
+## خطاهای رایج
+
+| پیام / وضعیت | معنی |
+|--------------|------|
+| `init timeout — is the game running inside the platform?` | iframe هستید ولی parent `platform:init` نفرستاده (یا دیر) |
+| `requires platformUrl + gameSlug` | Direct Mode بدون تنظیم |
+| `Development origin not allowed` | origin بازی در allowlist سرور نیست |
+| Authorize timeout | لاگین تمام نشد / popup بلاک شد |
+
+بعدی: [03-user-session.md](./03-user-session.md) · Direct: [09-direct-development.md](./09-direct-development.md)

package/docs/03-user-session.md

@@ -0,0 +1,33 @@
+# User و Session
+
+بعد از `init()` موفق.
+
+## خواندن sync
+
+```ts
+const user = PlatformSDK.getUser();
+// { id, username, displayName, avatarUrl }
+
+const session = PlatformSDK.getSession();
+// { id, token }
+```
+
+قبل از init هر دو `null` هستند.
+
+## نکات session
+
+- `token` برای هویت سشن بازی است (با JWT لاگین کاربر فرق دارد).
+- عمر سشن محدود است و با activity تمدید می‌شود؛ آن را دائمی فرض نکنید.
+- در Git / `.env` / localStorage ذخیره نکنید.
+- برای lobby-sdk همان `session.token` از Context کافی است؛ خودتان به سوکت وصل نشوید مگر عمداً کلاینت سفارشی بنویسید.
+
+## نمایش در UI
+
+```ts
+const { user, game } = await PlatformSDK.init();
+title.textContent = `${user.displayName} — ${game.name}`;
+```
+
+`avatarUrl` ممکن است `null` باشد؛ آواتار ۳D لابی از فیلد `avatar` در `getInitPayload()` می‌آید نه لزوماً از `avatarUrl`.
+
+بعدی: [04-end-session.md](./04-end-session.md)

package/docs/04-end-session.md

@@ -0,0 +1,22 @@
+# `endSession()`
+
+سشن بازی را می‌بندد تا در آمار/idle پلتفرم باز نماند.
+
+```ts
+await PlatformSDK.endSession();
+```
+
+## رفتار
+
+- **Production (iframe):** پیام `platform:session:end` به parent فرستاده می‌شود؛ پلتفرم سشن را می‌بندد.
+- **Direct Development:** `POST {platformUrl}/sessions/end` با همان session token.
+
+## کی صدا بزنید؟
+
+- وقتی بازیکن از بازی خارج می‌شود
+- قبل از unload صفحه (در iframe)
+- بعد از اتمام مسابقه اگر سشن دیگری نمی‌سازید
+
+چندبار صدا زدن نباید بازی را خراب کند؛ اگر سشن از قبل بسته شده باشد parent نادیده می‌گیرد.
+
+بعدی: [05-scores.md](./05-scores.md)

package/docs/05-scores.md

@@ -0,0 +1,30 @@
+# امتیاز — `submitScore`
+
+بهترین امتیاز بازیکن برای این بازی را ثبت می‌کند (keep-best).
+
+```ts
+const result = await PlatformSDK.submitScore(4200);
+// { score, previousBest, isNewBest, rank }
+```
+
+## پیش‌نیاز
+
+- `init()` موفق
+- سشن فعال
+- **Production:** از طریق iframe parent · **Direct Dev:** REST مستقیم به `platformUrl` (همان session token)
+
+## قوانین
+
+- `score` باید عدد نامنفی و finite باشد؛ اعشار truncate می‌شود.
+- امتیاز بدتر از بهترین قبلی، best را عوض نمی‌کند (`isNewBest: false`).
+
+## مثال
+
+```ts
+await PlatformSDK.init();
+// … پایان مسابقه
+const { isNewBest, rank } = await PlatformSDK.submitScore(finalScore);
+if (isNewBest) showToast(`رکورد جدید! رتبه ${rank}`);
+```
+
+بعدی: [06-leaderboard.md](./06-leaderboard.md)

package/docs/06-leaderboard.md

@@ -0,0 +1,19 @@
+# لیدربورد — `getLeaderboard`
+
+```ts
+const board = await PlatformSDK.getLeaderboard(20);
+// { gameSlug, entries: [{ rank, score, achievedAt, user: { displayName, username, avatarUrl } }] }
+```
+
+- `limit` پیش‌فرض ۲۰
+- نیاز به `init()` دارد
+- **Production** و **Direct Dev** هر دو کار می‌کنند (iframe یا REST)
+
+```ts
+const { entries } = await PlatformSDK.getLeaderboard(10);
+for (const row of entries) {
+  console.log(row.rank, row.user.displayName, row.score);
+}
+```
+
+بعدی: [07-postmessage-protocol.md](./07-postmessage-protocol.md)

package/docs/07-postmessage-protocol.md

@@ -0,0 +1,45 @@
+# پروتکل postMessage (Production)
+
+در Production، بازی داخل iframe است و با **صفحهٔ parent پلتفرم** حرف می‌زند — نه مستقیم با REST برای این عملیات.
+
+## از بازی → پلتفرم
+
+| `type` | نقش |
+|--------|-----|
+| `platform:ready` | SDK لود شد؛ لطفاً init بفرست |
+| `platform:session:end` | بستن سشن |
+| `platform:score:submit` | ثبت امتیاز (+ `requestId`, `sessionToken`, `score`) |
+| `platform:leaderboard:get` | درخواست لیدربورد |
+| `platform:achievement:unlock` / `platform:achievements:get` | دستاورد |
+| `platform:wallet:get` / `platform:gems:exchange` | کیف‌پول |
+| `platform:lobby:ready` | (از lobby-sdk) درخواست مجدد init |
+
+## از پلتفرم → بازی
+
+| `type` | نقش |
+|--------|-----|
+| `platform:init` | Context کامل |
+| `platform:score:result` و بقیه `*:result` | پاسخ RPC با همان `requestId` |
+
+## `platform:init` (شکل)
+
+```ts
+{
+  type: 'platform:init',
+  version: string,
+  session: { id, token },
+  user: { id, username, displayName, avatarUrl },
+  game: { slug, name },
+  avatar: { presetId, presetKey, presetKind, customConfig },
+  avatarBases?: [{ id, glbUrl }],
+  lobby?: { wsUrl, roomId, strictRoom? }
+}
+```
+
+بازی‌ساز معمولاً لازم نیست این پیام‌ها را دستی بسازد؛ `PlatformSDK` و parent پلتفرم این کار را می‌کنند.
+
+## Direct Development
+
+به‌جای parent، Authorize HTTP استفاده می‌شود؛ ولی **شکل نهایی Context همان `SdkInitPayload` است** تا lobby-sdk و کد بازی یکسان بمانند.
+
+بعدی: [08-wallet.md](./08-wallet.md)

package/docs/08-wallet.md

@@ -0,0 +1,32 @@
+# کیف‌پول جِم — `getWallet` / `convertGems`
+
+جِم ارز پلتفرم است. تبدیل به «سکه داخل بازی» با نرخ `coinsPerGem` همان بازی انجام می‌شود.
+
+```ts
+const wallet = await PlatformSDK.getWallet();
+// { gems, coinsPerGem, gameSlug }
+
+const result = await PlatformSDK.convertGems(5);
+// { gemsSpent, coinsReceived, coinsPerGem, gemsRemaining, gameSlug }
+```
+
+## مسئولیت بازی
+
+پلتفرم جِم را کم می‌کند و `coinsReceived` را برمی‌گرداند.  
+**اعتبار سکه داخل اقتصاد خودتان** با شماست (در سرور/کلاینت بازی اعمال کنید).
+
+## نکات
+
+- `gems` باید عدد صحیح مثبت باشد.
+- در **Production** و **Direct Dev** هر دو کار می‌کند (iframe یا REST با session token).
+
+```ts
+try {
+  const { coinsReceived } = await PlatformSDK.convertGems(amount);
+  await creditLocalCoins(coinsReceived);
+} catch (e) {
+  showError(e);
+}
+```
+
+بعدی: [09-direct-development.md](./09-direct-development.md) · [10-achievements.md](./10-achievements.md)