# المجموعات المحلية ووحدات التحكم الفعلية والهاتف في ألعاب PlayDrop

اقرأ وحدات التحكم الفعلية ووحدات تحكم الهاتف من PlayDrop عبر sdk.device، وتابع خانات اللاعبين المحليين، وصرّح بدعم وحدات التحكم وأحجام المجموعات المحلية.

Source: https://www.playdrop.ai/ar/create/learn/local-party

المجموعة المحلية هي عدة أشخاص يلعبون على شاشة واحدة، ولكل منهم وحدة تحكم: وحدة تحكم فعلية أو هاتف يحوّله PlayDrop إلى وحدة تحكم بمسح رمز. تقرأ لعبتك كل وحدات التحكم بالطريقة نفسها عبر SDK، على الموقع وفي التطبيقات.

## صرّح بوحدات التحكم وأحجام المجموعات

```json
{
  "types": ["solo", "party"],
  "party": { "local": [1, 2, 3, 4] },
  "controller": { "support": "optional", "type": "simpler" }
}
```

- قيمة `controller.support` هي `off` أو `optional` أو `required`. صرّح بها في كل لعبة، بما في ذلك `off`.
- يحدد `controller.type` الحد الأدنى من أدوات التحكم التي تحتاجها اللعبة: `any` (الاتجاهات وزر التأكيد وزر الإلغاء)، أو `simpler` (عصا واحدة وأربعة أزرار أمامية وزر Menu؛ وتفي وحدات تحكم الهاتف بذلك)، أو `standard` (لوحة اتجاهات وعصوان قابلتان للضغط وأربعة أزرار أمامية وزرّا كتف وزرّا زناد وزر Menu).
- تسرد `party.local` أعداد اللاعبين الدقيقة على شاشة واحدة؛ ويتطلب العدد `1` النوع `solo`. وعند تفعيل دعم وحدات التحكم، يجب أن يكون كل عدد مدرج قابلًا للعب بوحدات التحكم.

## اقرأ وحدات التحكم

```js
await sdk.device.enableControllerInput().catch(() => { /* keep keyboard and touch */ });

const stop = sdk.device.onButton(({ playerIndex, button, pressed }) => {
  if (button === "south" && pressed) jump(playerIndex);
});

function update() {
  for (const slot of sdk.device.localPlayers) {
    const pad = sdk.device.gamepad(slot.playerIndex);
    if (pad?.connected) move(slot.playerIndex, pad.axes[0], pad.axes[1]);
  }
  requestAnimationFrame(update);
}
update();
```

- استدعِ `enableControllerInput()` مرة واحدة بعد `init()`. تُرفض بالخطأ `controller_input_unavailable` أو `controller_input_timeout` عندما لا يستطيع المضيف توفير المدخلات؛ وتواصل اللعبة العمل.
- تعيد `gamepad(playerIndex)` لقطة بالتخطيط القياسي للمتصفح: `axes` (x/y لليسرى وx/y لليمنى من -1 إلى 1)، وسبعة عشر زرًا في `buttons`، و`source` (`physical` أو `virtual`)، و`id`. وتمثل قيمة `playerIndex` 0 اللاعب 1.
- للأزرار أسماء بحسب موضعها مثل `south` و`east`. تعطي `pad.label("south")` التلميح الذي يجب عرضه: «A» أو «Cross» أو «B» بحسب وحدة التحكم. وتبيّن `pad.has("dpad")` هل يوجد زر تحكم معين.
- زرّا Menu وHome مخصصان لـ PlayDrop ويُقرآن دائمًا غير مضغوطين.
- لا تستدعِ `navigator.getGamepads()` أبدًا: وحدات تحكم الهاتف لا تصل إلى الألعاب إلا عبر SDK، ويسجّل PlayDrop تحذيرًا.

## خانات اللاعبين المحليين

تسرد `sdk.device.localPlayers` الخانات التي اختارها اللاعبون، `{ playerIndex, gamepadKey }`، وتبلّغ `onLocalPlayersChange(callback)` عن التغييرات. تحتفظ وحدة التحكم المفصولة بخانتها. وعندما تتغير قائمة اللاعبين أو تصبح فارغة، ارجع إلى قائمة مناسبة بدل أن تتعطل اللعبة. ووحدة تحكم واحدة بمفردها مجرد وسيلة إدخال عادية، وليست مجموعة.

من زر في لعبتك، تفتح `sdk.social.openParty({ mode: "local" })` نافذة الإقران في PlayDrop مع رمز QR للهاتف ووحدات التحكم المتصلة. ولا تعرض إلا الأوضاع التي صرّحت بها.

## محلية أو عبر الإنترنت، لا الاثنتان معًا

يبدأ المضيف اللعبة إما بوصفها مجموعة محلية أو مجموعة عبر الإنترنت، ولا يجمع بينهما أبدًا: لا يستطيع اللاعبون المحليون الانضمام إلى الغرف عبر الإنترنت. وللعب مع الأصدقاء عبر الإنترنت راجع [المجموعات والصوت عبر الإنترنت](https://www.playdrop.ai/ar/create/learn/online-party).

## صمّم للعب الجماعي من الأريكة

اعرض لون كل لاعب وتلميح وحدة التحكم الخاص به، واسمح لأي شخص بالضغط على زر للانضمام، واجعل واجهة اللعب مقروءة من الأريكة. واحتفظ بأدوات التحكم باللمس ولوحة المفاتيح للعب الفردي.

## أدلة ذات صلة

- [المجموعات والصوت عبر الإنترنت](https://www.playdrop.ai/ar/create/learn/online-party): دع الأصدقاء يلعبون معًا عبر الإنترنت: صرّح بأحجام المجموعات، وافتح نافذة المجموعة، وانضم إلى الغرف المحجوزة عبر sdk.multiplayer.join، وتحكم بصوت الغرفة.
- [ملء الشاشة والمناطق الآمنة](https://www.playdrop.ai/ar/create/learn/viewport): اجعل لعبة PlayDrop تملأ الشاشة، وأبقِ واجهة اللعب داخل مناطق CSS الآمنة وبعيدًا عن أدوات تحكم المضيف باستخدام reservedCorners المقيسة من SDK.
- [catalogue.json](https://www.playdrop.ai/ar/create/learn/catalogue-json): حقول catalogue.json في ألعاب PlayDrop: الهوية وصفحة اللعبة وطرق اللعب والواجهات وتسجيل الدخول وInstant والتحميل المسبق والوسائط والترجمات والنقاط والخوادم.