---
type: reference
title: مرجع SDK اللعبة
summary: السطح الكامل لـ @caputchin/game-sdk الذي يكتب مؤلّف لعبة مقابله، ودالة register، والجسر الدافع-فقط، وسياق كل جولة، وأنواع التهيئات.
---

‏`@caputchin/game-sdk` هو العقد الذي يكتب مؤلّف لعبة مقابله: مساعد `register`، وجسر `Bridge` دافع-فقط، وسياق `GameContext` لكل جولة، وأنواع TypeScript لكتل تهيئات البيان. يُنشَر منفصلًا عن الأداة المواجِهة للمستخدم كي لا تحزم الألعاب أبدًا زمن تشغيل الأداة بالتعدّي. ألعاب الطرف الأول تستخدم هذا الـ API العام نفسه؛ لا عقد خاصّ.

لبناء موجَّه، انظر [ابنِ لعبة المتجر](/docs/marketplace-game-development/build-a-marketplace-game). للبيان الذي يعلن التهيئات التي يكشفها هذا الـ SDK، انظر [بيان caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest).

## `register(factory)`

نقطة دخول التسجيل الوحيدة. مرّر مصنع لعبتك؛ **لا** تمرّر البيان (يقرأ الخادم `caputchin.json` وقت الفهرسة ويشحن التهيئات المحلولة كسياق المصنع). التسجيل مرّتين يسجّل تنبيهًا في الطرفية والكتابة الأخيرة تفوز؛ لا فرض من المنصّة.

```ts
register(factory: GameFactory): void
```

## مصنع اللعبة

```ts
type GameFactory = (
  container: HTMLElement,
  bridge: Bridge,
  ctx?: GameContext,
) => (() => void) | void
```

| المعامل | المعنى |
|---|---|
| `container` | عنصر داخل إطار iframe المعزول للّعبة. اعرض هنا. التنسيق محصور طبيعيًّا، فالإطار وثيقته الخاصة. |
| `bridge` | القناة الدافعة-فقط إلى المضيف (انظر [الجسر](#the-bridge)). تبثّ اللعبة إلى الأعلى؛ لا تشترك. نداء المصنع هو إشارة البدء. |
| `ctx` | [سياق](#the-context) كل جولة (البذرة إضافةً إلى التهيئات المحلولة). اختياري في النوع لأن الأداة قد تشغّل لعبة خارج جلسة متحقَّق منها. |
| return | دالة تنظيف اختيارية تناديها الأداة إن فكّكت لعبتك. |

## الجسر [#the-bridge]

الجسر دافع-فقط: تبلّغ اللعبة الأحداث للمضيف ولا تنصت أبدًا. أعضاؤه:

| العضو | الشكل | الأثر |
|---|---|---|
| `pass` | `pass(result: { trace: string }): void` | يشير إلى أن الجولة **نجحت**، مسلّمًا المضيف `trace` المعتم. يعيد الخادم تشغيل [`run`](/docs/marketplace-game-development/replay-contract) اللعبة تحت البذرة المُصدَرة لحساب الحُكم الموثوق، فاللعبة **لا** تبلّغ نتيجة هنا. أول نداء يطلق التحقّق المحبوس ويقفل الرمز؛ والنداءات اللاحقة تُتجاهَل. |
| `error` | `error(err: { code: string; message?: string }): void` | اللعبة نفسها فشلت (تحميل أصل، استثناء داخلي). يُظهر حدث `error` للمستخدم. متمايز عن خسارة لاعب، التي يُشار إليها بنداء لا شيء. |
| `setSize` | `setSize(width: number, height: number): void` | غيّر حجم الإطار صراحةً ليلائم المحتوى. ناده بعد أول رسم؛ تقيس الأداة أيضًا أول ابن للّعبة تلقائيًّا، فمعظم الألعاب لا تحتاجه أبدًا. |
| `layout` | `readonly layout: 'inline' \| 'modal' \| 'fullscreen' \| null` | العرض المحلول الذي تعمل اللعبة تحته، أو `null` حين يكون مجهولًا. |

لا `complete` عمدًا، ولا مُنصِت `start`، ولا طريقة `unmount` (أعِد دالة تنظيف بدلًا)، ولا إشارة فشل أبعد من الصمت.

## السياق [#the-context]

```ts
interface GameContext {
  seed:   Seed          | null
  locale: ResolvedLocale | null
  skin:   ResolvedSkin   | null
  config: ResolvedConfig | null
}
```

| الحقل | المعنى |
|---|---|
| `seed` | بذرة إعادة تشغيل كل جولة ([`Seed`](/docs/marketplace-game-development/replay-contract) من عقد إعادة التشغيل). ابذر كل عشوائية اللعبة منها. `null` حين تعمل اللعبة خارج جلسة متحقَّق منها. |
| `locale` | كائن اللغة المحلول: `_lang` (BCP-47)، و`_direction`، إضافةً إلى مفاتيح نصوصك المسطّحة. `null` إن لم يشحن بيانك كتلة `locales`. |
| `skin` | المظهر المحلول: `_theme` إضافةً إلى مفاتيح اللون/الأصل المسطّحة، وروابط الأصول مطلقة أصلًا. `_theme` دائمًا الوضع الملموس الذي حُلّ له المظهر، `light` أو `dark` (لا `any` أبدًا)، فتهيئة محايدة-السمة تبلّغ وضع الزائر الفعلي. `null` إن لا كتلة `skins`. |
| `config` | الإعداد المحلول: قياسياتك المكتوبة الأنواع المسطّحة. `null` إن لا كتلة `configurations`. |

كلٌّ `null` حين تغيب كتلة البيان المقابلة، فقدّم دائمًا ارتدادًا مدمجًا.

## أنواع التهيئات

يصدّر الـ SDK أنواع TypeScript لتأليف `caputchin.json` (وملفّات `.caputchin/` المقسّمة) بفحص الأنواع. تعكس هذه كتل [البيان](/docs/marketplace-game-development/the-caputchin-json-manifest):

| النوع | يصف |
|---|---|
| `GameManifest` | الـ `caputchin.json` كله. مصدر حقيقة المؤلّف + المفهرِس؛ لا يُقرَأ في المتصفّح أبدًا. |
| `LocalePreset` / `ResolvedLocale` | تهيئة لغة مُعلَنة / الكائن المحلول الذي تستقبله اللعبة. |
| `SkinPreset` / `ResolvedSkin` / `SkinSchemaEntry` / `SkinValueType` | تهيئات المظهر، والمظهر المحلول، ومخطّط النوع لكل مفتاح. |
| `ConfigPreset` / `ResolvedConfig` / `ConfigSchemaEntry` / `ConfigValueType` | تهيئات الإعداد، والإعداد المحلول، ومخطّط النوع لكل مفتاح. |
| `LocalesFile` / `SkinsFile` / `ConfigurationsFile` | الكائن الأعلى لكل ملفّ مقسّم `.caputchin/<axis>.json`. |
| `MarketplaceMetadata` / `PreferredPresentation` | كتلة `marketplace` وتلميح بصمة `preferred`. |

ألّف ملفًّا مقسّمًا باستيراد `satisfies` كي يفحصه المصرّف:

```ts
import type { LocalesFile } from "@caputchin/game-sdk";
export default { schema: { /* ... */ }, presets: { /* ... */ } } satisfies LocalesFile;
```

## ما الذي غائب عمدًا

- لا `sessionId` ولا معرّفات منصّة تبلغ اللعبة.
- لا خطّافات دورة حياة `start` / `pause` / `resume`؛ نداء المصنع هو البدء.
- لا `maxScore` ولا مدى نتيجة منصّة؛ نتيجة الحُكم هي أيًّا تعيد `run` خاصتك.

العقد ضئيل عمدًا كي يبقى ثابتًا عبر سنوات نموّ الكتالوج.

## انظر أيضًا

- [ابنِ لعبة المتجر](/docs/marketplace-game-development/build-a-marketplace-game): الدرس الذي يستخدم هذا السطح.
- [عقد إعادة التشغيل](/docs/marketplace-game-development/replay-contract): الـ `Seed`، والأثر، والحُكم التي يشير إليها الجسر والسياق.
- [بيان caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest): إعلان التهيئات التي يحلّها السياق.