مرجع تقني

SDK للعميل من PlayDrop لألعاب المتصفح

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

SDK الخاص بـ PlayDrop اختياري: الألعاب التي لا تستخدمه تعمل على PlayDrop. أضفه للحصول على ميزات المنصة مثل تسجيل دخول اللاعب والحفظ والإنجازات ولوحات المتصدرين والمشتريات بالرصيد والإعلانات والأصدقاء وبطاقات الألعاب في دردشة PlayDrop وروابط المشاركة وإيقاف اللعبة مؤقتًا والتحكم بالصوت عبر المضيف ومدخلات وحدات التحكم واللعب الجماعي المستضاف والإنشاء بالذكاء الاصطناعي. يدمجه PlayDrop Cloud نيابةً عنك؛ ومع PlayDrop Connector يضيف وكيلك وسم script واحدًا.

أضف SDK واتبع دورة حياة المضيف

html

<script src="https://assets.playdrop.ai/sdk/playdrop.js"></script>
<script type="module">
  const sdk = await playdrop.init();
  // Render the game and prepare input, then:
  sdk.host.ready();
  sdk.host.onPause(() => pauseGame());
  sdk.host.onResume(() => resumeGame());
  sdk.host.onAudioPolicyChange(({ enabled }) => setAudioEnabled(enabled));
</script>

حمّل SDK من CDN الخاص بـ PlayDrop؛ ولا حاجة إلى تثبيت أي حزمة. اعرض أول إطار قابل للعب وجهّز المدخلات قبل استدعاء sdk.host.ready(). أوقف المحاكاة عند إيقاف المضيف مؤقتًا، واستأنف دون تكرار الحلقات، واتبع سياسة الصوت للمضيف.

الهوية والحفظ واللغة

يوفّر sdk.me هوية اللاعب ويخزّن sdk.me.appData عمليات الحفظ الخاصة؛ ويتولى sdk.achievements وsdk.leaderboards الإنجازات والنتائج. تعمل عمليات الحفظ والإنجازات ولوحات المتصدرين دون فحص مسبق لتسجيل الدخول. استخدم sdk.me.isLoggedIn للميزات التي تتطلب حسابًا حقيقيًا، مثل المشتريات أو اللعب الجماعي. يجب ألا تكتب أوضاع المعاينة والتقاط الشاشة تقدم اللاعب. يعطي sdk.host.language لغة اللاعب: قدّم الإنجليزية إضافة إلى لغتك إن اختلفت. ترجمة صفحة اللعبة لا تترجم محتوى اللعبة. عند توقف طبيعي، مثل الفوز، يتيح sdk.host.requestReview() أن يطلب PlayDrop من اللاعب تقييمًا، مرة واحدة كحد أقصى لكل لعبة؛ ولا تعرف لعبتك الإجابة أبدًا، لذا لا تكافئ عليها.

المكتبات والأصول واللعب الجماعي

يحمّل sdk.libs إصدارات مدعومة من Three.js وPhaser وRapier وnipplejs وColyseus. يوفّر sdk.assets مراجع الكتالوج والحزم والأصول؛ ويوفّر sdk.social الأصدقاء وبطاقات الألعاب وإجراءات المشاركة. للعب الجماعي المستضاف، تعيد sdk.multiplayer.getConnection() عنوان الخادم ورمز اللاعب المسجّل الدخول؛ انضم عبر عميل Colyseus. تغطي صفحة SDK للخادم الخوادم المستضافة؛ والخادم الذي تشغّله بنفسك لا يحتاج إلى شيء من SDK. واجهات غرف الترحيل القديمة أُوقفت.

جرّب مع SDK قبل أن تنشر

شغّل خادم التطوير المعتاد لديك وافتح https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/ في Chrome للعب داخل إطار PlayDrop الحقيقي مع مضيف SDK. يعمل أي منفذ localhost أو رابط https. الميزات التي تحتاج إلى حساب، مثل الحفظ والمشتريات، تعمل بعد رفع اللعبة مرة واحدة؛ ويكفي رفع خاص. يعمل إنشاء الوسائط في المتصفح كعمليات غير متزامنة بتكلفة رصيد يؤكدها المضيف. راجع catalogue.json للبيانات الوصفية لصفحة اللعبة.

العب معًا

استخدم await sdk.multiplayer.join("game") في مرحلة اللعب. تنضم بشكل مستقل أو تستهلك حجز المجموعة لدى المضيف. يؤدي فشل المجموعة إلى رفض الطلب بدل تفريق اللاعبين بصمت في غرفة أخرى. تبقى getConnection() واجهة تفاصيل الاتصال الفورية للألعاب الموجودة. أبقِ الغرفة نفسها بين الجولات، وأبقِ الشبكة نشطة بينما تُوقف طبقات المضيف مدخلات اللعبة.

استخدم sdk.social.openParty() من إجراء للاعب لفتح نافذة المجموعة لدى المضيف. اقرأ العضوية بـ await sdk.social.getParty() أو sdk.social.onPartyChange(callback). لا يمكن للألعاب تعديل مجموعات المنصة أو التحكم بالميكروفونات. يعمل صوت المجموعة والغرفة في مضيف الويب أو التطبيق الأصلي ويبقى خاضعًا لموافقة اللاعب والكتم والحظر وأهلية الإطلاق التدريجي.

لتشغيل سلس في الغرفة، استدعِ sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] }) مستخدمًا متجهات { x, y, z } محدودة. تؤثر التلميحات في مستوى الصوت والتوزيع بين السماعتين، ولا تؤثر أبدًا في التفويض. يفرض الخادم أهلية الفرق والقرب.

استخدم sdk.device.localPlayers وsdk.device.onLocalPlayersChange(callback) لخانات وحدات التحكم المحلية المحددة { playerIndex, gamepadKey }. جرد وحدات التحكم المتصلة منفصل؛ والخانة المقطوعة تحتفظ بهويتها. لا يمكن للوضع المحلي الانضمام إلى غرف الإنترنت. توضح الوصفة القابلة للنسخ playdrop-metagame/recipes/play-together الوضعين ووجهتين وسياسات الغرف.

وحدات التحكم

اقرأ وحدات التحكم الفعلية ووحدات تحكم هاتف PlayDrop عبر sdk.device، بالطريقة نفسها على كل منصة. استدعِ enableControllerInput() مرة واحدة بعد init()، واقرأ gamepad(playerIndex) في حلقة اللعبة (0 هو P1)، واستخدم onButton للضغطات والإفلاتات. تتبع المحاور والأزرار ترتيب وحدة التحكم القياسي في المتصفح؛ ولها أسماء موضعية مثل south وeast، وتعيد pad.label("south") النص الظاهر لتلك الوحدة، مثل "A" أو "Cross". زر Menu يخص PlayDrop ويوقف اللعبة مؤقتًا.

await sdk.device.enableControllerInput();
const stop = sdk.device.onButton(({ playerIndex, button, pressed }) => {
  if (button === "south" && pressed) jump(playerIndex);
});
function update() {
  const pad = sdk.device.gamepad(0);
  if (pad?.connected) move(pad.axes[0], pad.axes[1]);
  requestAnimationFrame(update);
}
update();

لا تستدعِ navigator.getGamepads(): تصل وحدات تحكم الهاتف إلى الألعاب عبر SDK فقط، ويسجّل PlayDrop تحذيرًا عندما تقرأ لعبة واجهة المتصفح مباشرة. وإذا تعذّر على المضيف توفير مدخلات وحدات التحكم، ترفض enableControllerInput() بالقيمة controller_input_unavailable أو controller_input_timeout وتواصل اللعبة العمل. تخبرك pad.has("dpad") هل يوجد عنصر تحكم؛ وصرّح بعناصر التحكم التي تحتاجها لعبتك في catalogue.json.