@oyna360/lobby-sdk 0.1.0

package/docs/03-modes.md

@@ -0,0 +1,70 @@
+# حالت‌های اجرا
+
+## 1) Production — iframe پلتفرم
+
+```text
+بازیکن → /play/{slug} → iframe بازی → game-sdk init → lobby-sdk
+```
+
+- سشن توسط پلتفرم ساخته می‌شود.
+- `platform:init` شامل `avatar` و `lobby` است.
+- امتیاز/جِم بعداً از game-sdk در iframe در دسترس است.
+
+```ts
+await PlatformSDK.init();
+const lobby = await PlatformLobby.create({
+  canvas,
+  platformInit: PlatformSDK.getInitPayload()!,
+  roomId: PlatformSDK.getInitPayload()!.lobby!.roomId,
+  wsUrl: PlatformSDK.getInitPayload()!.lobby!.wsUrl,
+});
+```
+
+---
+
+## 2) Direct Development — بدون iframe
+
+```text
+npm run dev → origin شما → game-sdk Authorize → Context واقعی → lobby-sdk → WS واقعی
+```
+
+مناسب وقتی پلتفرم را لوکال ندارید ولی سرور oyna360 در دسترس است.
+
+1. game-sdk را طبق [09-direct-development](../../game-sdk/docs/09-direct-development.md) تنظیم کنید.
+2. همان `PlatformLobby.create({ platformInit })`.
+3. Origin توسعه را allowlist کنید.
+
+`createDev()` را اینجا استفاده نکنید.
+
+---
+
+## 3) `createDev()` — Fake / Offline
+
+```ts
+await PlatformLobby.createDev({
+  canvas,
+  roomId: 'game:my-game',
+  config: { enableMultiplayer: false },
+  mockUser: { displayName: 'Tester' },
+});
+```
+
+- سشن ساختگی (`dev-token`) — سرور لابی آن را برای مالتی‌پلیر واقعی قبول نمی‌کند.
+- برای چیدمان صحنه، UI، پورتال بدون شبکه.
+- با Direct Development اشتباه نشود.
+
+---
+
+## مقایسه سریع
+
+| | Production | Direct Dev | createDev |
+|--|:----------:|:----------:|:---------:|
+| اکانت واقعی | ✅ | ✅ | ❌ |
+| سشن واقعی | ✅ | ✅ | ❌ |
+| remote players | ✅ | ✅ | ❌ |
+| نیاز به پلتفرم لوکال | نه* | نه | نه |
+| نیاز به iframe | ✅ | ❌ | ❌ |
+
+\* مگر خودتان همه stack را لوکال بالا آورده باشید.
+
+بعدی: [04-api.md](./04-api.md)

package/docs/04-api.md

@@ -0,0 +1,106 @@
+# API — `PlatformLobby`
+
+## ساخت نمونه
+
+### `PlatformLobby.create(options)`
+
+```ts
+interface PlatformLobbyCreateOptions {
+  canvas: HTMLCanvasElement;
+  platformInit: SdkInitPayload | PlatformInitMessage;
+  roomId: string;
+  wsUrl?: string;          // پیش‌فرض از platformInit.lobby.wsUrl
+  strictRoom?: boolean;    // دعوت دوست؛ بدون spillover ظرفیت
+  config?: PlatformLobbyConfig;
+}
+```
+
+### `PlatformLobby.createFromPlatform(canvas, config?)`
+
+منتظر Context روی window / `platform:init` می‌ماند، سپس `create` را صدا می‌زند.
+
+### `PlatformLobby.createDev(options)`
+
+Mock Context + معمولاً `enableMultiplayer: false`.
+
+---
+
+## `PlatformLobbyConfig` (مهم‌ترین‌ها)
+
+| فیلد | پیش‌فرض | توضیح |
+|------|---------|--------|
+| `enableMultiplayer` | `true` | اتصال سوکت |
+| `enableChat` | `true` | overlay چت |
+| `enableVoice` | `true` | voice WebRTC |
+| `enablePresenceUi` | با مالتی‌پلیر | toast ورود/خروج |
+| `enableConnectionUi` | با مالتی‌پلیر | قطع اتصال |
+| `enableOrientationUi` | `true` | اعلان landscape موبایل |
+| `locale` | `'fa'` | `'fa'` \| `'en'` |
+| `spawnPoint` / `spawnPoints` | — | محل اسپان |
+| `playerSpeed` / `runMultiplier` | داخلی | حرکت |
+| `cameraDistance` / `cameraHeight` | داخلی | دوربین |
+| `quality` | `'auto'` | کیفیت رندر |
+| `avatarBases` | — | کاتالوگ GLB |
+| `preloadAvatarBases` | true | گرم کردن کش GLB |
+
+---
+
+## متدهای پرکاربرد
+
+```ts
+lobby.getUser();
+lobby.getSession();
+lobby.getAvatar();
+lobby.getPlayers();
+
+lobby.applyPlazaLayout({ onRoomStart, /* … */ });
+lobby.applyStarterLayout({ /* … */ });
+
+lobby.addZone({ id, bounds, onEnter, onExit });
+lobby.addPortal({ id, /* … */ });
+
+lobby.sendChat('سلام');
+lobby.sendData('my-channel', payloadString); // کانال data جدا از چت
+
+lobby.playEmote('wave');
+lobby.attachChat();
+lobby.destroy();
+```
+
+### رویدادها
+
+```ts
+lobby.on('chat', ({ displayName, text }) => {});
+lobby.on('playerJoin', (player) => {});
+lobby.on('playerLeave', ({ userId }) => {});
+// و سایر رویدادهای LobbyEventMap
+```
+
+### Plugin
+
+```ts
+import { ShopZonePlugin, defineLobbyPlugin } from '@oyna360/lobby-sdk';
+lobby.use(ShopZonePlugin);
+```
+
+---
+
+## چیدمان
+
+- **`applyPlazaLayout` (متد):** میدان، اتاق‌ها، برخورد — برای اکثر بازی‌ها.
+- **`applyStarterLayout`:** چیدمان ساده‌تر استارتر.
+- تابع‌های export هم‌نام را به‌جای متد صدا نزنید؛ برخورد به‌درستی اعمال نمی‌شود.
+
+---
+
+## چرخه عمر
+
+1. create  
+2. layout / zones  
+3. بازیکن در لابی  
+4. شروع مسابقه → **`destroy()`**  
+5. موتور گیم‌پلی خودتان (مثلاً Three.js روی canvas دیگر)
+
+دو موتور روی یک canvas توصیه نمی‌شود.
+
+بعدی: [05-features.md](./05-features.md)

package/docs/05-features.md

@@ -0,0 +1,55 @@
+# امکانات — آواتار، چت، voice، data
+
+## آواتار
+
+از `platformInit.avatar` ساخته می‌شود (procedural یا GLB).
+
+- رنگ / لباس / اکسسوری از `customConfig`
+- `avatarBases` برای پیش‌بارگذاری چند بدنهٔ GLB مشترک
+- انیمیشن راه رفتن / دویدن / پرش داخل SDK
+
+بازی معمولاً لازم نیست `AvatarFactory` را مستقیم صدا بزند مگر ابزار سفارشی بسازید.
+
+URL تکسچر و GLB باید از پلتفرم **مطلق** باشند تا از origin بازی cross-origin لود شوند (CORS روی `/uploads` سمت پلتفرم فعال است).
+
+---
+
+## چت
+
+- زنده، بدون ذخیره دائمی
+- `enableChat: false` برای خاموش کردن UI پیش‌فرض
+- `sendChat(text)` / رویداد `chat`
+
+برای فریم‌های کنترلی بازی (مثلاً matchmaking) از چت استفاده نکنید → کانال data.
+
+---
+
+## Voice
+
+- با `enableVoice` (پیش‌فرض روشن وقتی مالتی‌پلیر باشد)
+- محدودیت تعداد peer نزدیک روی سرور تنظیم می‌شود
+- نیاز به مجوز میکروفون مرورگر
+
+---
+
+## کانال `lobby:data`
+
+پیام‌های باینری/متنی کوتاه برای منطق بازی، جدا از چت.
+
+```ts
+lobby.sendData('fc.pad-room', frameString);
+
+lobby.on('data', ({ channel, payload, fromUserId }) => {
+  if (channel === 'fc.pad-room') handleFrame(payload);
+});
+```
+
+محدودیت اندازه و نرخ از سمت سرور اعمال می‌شود. چت را sanitize نکنید روی data — فرمت خودتان را validate کنید.
+
+---
+
+## Presence / اتصال
+
+UIهای آماده برای ورود بازیکن و قطع شبکه را می‌توان با فلگ‌های config خاموش کرد و UI خودتان را گذاشت.
+
+بعدی: [06-controls.md](./06-controls.md)

package/docs/06-controls.md

@@ -0,0 +1,34 @@
+# کنترل‌ها و موبایل
+
+## دسکتاپ
+
+| ورودی | عمل |
+|-------|-----|
+| WASD (`event.code`) | حرکت |
+| Shift | دویدن |
+| Space | پرش |
+| E | تعامل / ایموجی |
+| ماوس | چرخش دوربین سوم‌شخص |
+
+## موبایل / لمسی
+
+- اهرک مجازی: راه رفتن
+- دکمه دویدن جدا
+- دکمه پرش
+- در portrait ممکن است overlay «افقی کنید» بیاید (`enableOrientationUi`)
+
+## کیفیت
+
+`config.quality = 'auto' | 'low' | 'medium' | 'high'`  
+روی موبایل‌های ضعیف auto معمولاً به low/medium می‌رود.
+
+## چند canvas
+
+اگر گیم‌پلی با Three.js / موتور دیگر است:
+
+1. canvas لابی برای `PlatformLobby`
+2. canvas جدا برای مسابقه بعد از `destroy()`
+
+همزمان دو رندرر WebGL سنگین روی موبایل ممکن است سفید/کرش شود.
+
+بعدی: [07-troubleshooting.md](./07-troubleshooting.md)

package/docs/07-troubleshooting.md

@@ -0,0 +1,39 @@
+# عیب‌یابی — lobby-sdk
+
+## Timed out waiting for platform:init
+
+- داخل iframe نیستید و `PlatformSDK.init()` را قبلش صدا نزده‌اید.
+- یا parent پلتفرم init نفرستاده.
+
+**راه:** اول game-sdk `init`، بعد `create({ platformInit })`.
+
+## صفحه سفید / HUD هست صحنه نیست
+
+اغلب سنگینی آواتار GLB یا WebGL context روی موبایل. کیفیت را `low` کنید، تعداد remote را کم کنید، مدل را سبک کنید.
+
+## بازیکن remote دیده نمی‌شود
+
+- `enableMultiplayer: true`
+- `session.token` واقعی است (نه `dev-token`)
+- `wsUrl` به همان محیطی اشاره می‌کند که سشن ساخته شده
+- فایروال / mixed content (https صفحه با ws ناامن)
+
+## آواتار نامرئی / منفجر
+
+مدل GLB ناسازگار؛ از presetهای تأییدشده پلتفرم استفاده کنید. مسیر bake/fallback داخل SDK برای بعضی مدل‌ها هست ولی مدل بسیار سنگین موبایل را می‌خواباند.
+
+## چت می‌آید ولی data نه
+
+کانال data جداست؛ فلگ/مجوز سرور و طول payload را چک کنید. متن را در چت نفرستید.
+
+## `applyPlazaLayout` برخورد ندارد
+
+متد روی instance را صدا بزنید نه تابع export خام.
+
+## ساخت از GitHub خراب است
+
+`dist` باید بدون import به `@platform/lobby-protocol` باشد. تگ را عوض کنید یا از maintainer بخواهید pack تازه بگذارد.
+
+## createDev به سرور وصل نمی‌شود
+
+عمدی است. برای مالتی‌پلیر واقعی Direct یا Production را استفاده کنید.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@oyna360/lobby-sdk",
+  "version": "0.1.0",
+  "description": "oyna360 3D Lobby SDK for game developers (Babylon.js). Protocol is bundled — do not install lobby-protocol.",
+  "license": "MIT",
+  "author": "oyna360",
+  "keywords": [
+    "oyna360",
+    "lobby-sdk",
+    "babylonjs",
+    "multiplayer",
+    "avatar"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "sync:protocol": "node ../../scripts/sync-lobby-protocol.mjs",
+    "prebuild": "node ../../scripts/sync-lobby-protocol.mjs",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"No lint configured for @oyna360/lobby-sdk\"",
+    "check:protocol": "node ../../scripts/sync-lobby-protocol.mjs --check"
+  },
+  "dependencies": {
+    "@babylonjs/loaders": "^7.44.0",
+    "socket.io-client": "^4.8.1"
+  },
+  "peerDependencies": {
+    "@babylonjs/core": "^7.0.0"
+  },
+  "devDependencies": {
+    "@babylonjs/core": "^7.44.0",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mamadjavadrasti/oyna360-lobby-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mamadjavadrasti/oyna360-lobby-sdk/issues"
+  },
+  "homepage": "https://github.com/mamadjavadrasti/oyna360-lobby-sdk#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}