HovermateHovermateالتوثيق
العربية

SDK أحداث الألعاب · المرجع

البروتوكول v1

العقد بين الألعاب وHovermate. تولد هذه الصفحة من PROTOCOL.md المرفق بتنزيل SDK.

الهدف: تمكين الألعاب والتعديلات من إرسال أحداث إلى Hovermate، لتحويلها إلى علامات زمنية ولقطات بارزة تلقائية مثل البطاقات المدمجة. تغطي ثلاث وسائل نقل البيئات التي تدعم الشبكة أو الملفات فقط أو السجلات فقط.

1. اكتشاف الاتصال

يكتب Engine الملف %LOCALAPPDATA%\Hovermate\Sdk\connection.json عندما يكون SDK مفعّلًا (الإعدادات › المقاطع › SDK أحداث الألعاب، مفعّل افتراضيًا):

{
  "version": 1,
  "url": "http://local.hovermate.gg/hovermate/v1/events",
  "token": "<random, base64url, 32 bytes>",
  "inbox": "C:\\Users\\<user>\\AppData\\Local\\Hovermate\\Sdk\\Inbox"
}
  • url هو المكان الذي تُرسل إليه الأحداث. اقرأه من هذا الملف واستخدمه كما هو مكتوب تمامًا؛ لا تثبّت المضيف أو المنفذ أو المسار في الشيفرة ولا تغيّرها أبدًا. يكتب Hovermate حاليًا http://local.hovermate.gg/hovermate/v1/events؛ ويكتب خادم الاختبار في SDK عنوان اختبار خاصًا به.
  • يقرأ العملاء الملف عند البدء وبعد كل استجابة 401. قد يتغير رمز المصادقة.
  • يغير HOVERMATE_SDK_CONNECTION=<path> موقع الملف للاختبارات والأدوات ومجلدات البيانات المعزولة. يأخذ العملاء مجلد الاستقبال دائمًا من حقل inbox ولا يستنتجون مساره بأنفسهم.
  • غياب الملف يعني أن Hovermate غير مثبت أو أن SDK متوقف. يظل العملاء صامتين ولا يمررون استثناءات إلى اللعبة.

2. وسائل النقل

2.1 HTTP ‏(تعديلات لها شبكة: C# وC++ وJava وPython وJS)

  • POST {url}؛ والترويسات Authorization: Bearer <token> وContent-Type: application/json.
  • ترفض الطلبات ذات ترويسة Origin بالاستجابة 403، لمنع الإرسال من المتصفحات.
  • الجسم: كائن حدث واحد أو { "events": [ ... ] } يحتوي حتى 100 حدث. الحجم الأقصى 64 KB.
  • تقبل الدفعة كاملة أو ترفض. يتحقق Hovermate أولًا من جميع الأحداث؛ إذا فشل أحدها فلا يقبل شيء، ويذكر جسم 400 موقعه: { "error": "<code>", "detail": "...", "index": 3 }. للعبة الجديدة في الجلسة، يجب أن يظهر game.name في أول حدث يذكرها في الدفعة.
  • الاستجابات:
    • 202 مقبول؛
    • 400 غير صالح، والجسم { "error": "<code>", "detail": "...", "index": <n, batches only> }؛
    • 401 رمز خاطئ أو مفقود؛
    • 403 يحتوي الطلب على ترويسة Origin؛
    • 413 الجسم أكبر من المسموح. يقرأ حتى 1 MB ثم يتجاهل أولًا، ليصل رمز الحالة إلى العميل؛ وقد ترفض الأجسام الأكبر قبل قراءتها مع إغلاق الاتصال؛
    • 429 أكثر من 20 حدثًا/ثانية لكل لعبة؛
    • 405 و411 و415 تعني طريقة خاطئة أو طولًا مفقودًا أو نوع محتوى خاطئًا.
  • يرسل العملاء في الخلفية دون انتظار في خيط اللعبة. يستخدمون مهلة 250 ms أو أقل، وطابورًا محدودًا يحذف الأقدم، ومحاولة إضافية واحدة فقط.

2.2 مجلد استقبال JSONL ‏(تعديلات تكتب ملفات ولا تستخدم الشبكة)

  • أضف أسطر UTF-8 إلى {inbox}\<game.id>.jsonl، كائن حدث واحد لكل سطر، دون BOM.
  • لا يلزم رمز مصادقة؛ المجلد ملك للمستخدم.
  • يبدأ Engine عند التشغيل بمراقبة كل ملف *.jsonl في مجلد الاستقبال من نهايته. يمكن للتعديل تفريغ ملفه عند بدء جلسة.

2.3 صيغة أسطر السجل (تعديلات سكربت لا تكتب إلا في سجل اللعبة)

  • سطر يحتوي على العلامة [HOVERMATE] تليها قيمة JSON لكائن حدث واحد. يتجاهل كل ما قبل العلامة، بما فيه الأوقات وأسماء القنوات.
  • تضم بطاقة SDK قائمة «قراءة الأحداث من ملف» ليضيف المستخدم مسار السجل. ويمكن لحدث hello ‏(§4) وصل بوسيلة أخرى اقتراحه. يقرأ Engine الملف بمحوّل متابعة السجل الموجود.
  • يراقب Hovermate سجلات السكربت المعروفة تلقائيًا أثناء تشغيل اللعبة. توجد القائمة في كتالوج الألعاب (sdkLogs)، مثل Documents\The Witcher 3\scriptslog.txt وسجلات Papyrus لـSkyrim/Fallout. يكفي تفعيل تسجيل السكربتات في هذه الألعاب.

2.4 ملف أحداث مجلد التعديل (بيئات لا تكتب إلا في مجلدها)

  • بعض البيئات، مثل تعديلات Lua في Cyber Engine Tweaks، لا تسمح بالكتابة إلا في مجلد التعديل. يضيف التعديل أسطر JSONL ‏(§2.2) إلى hovermate-events.jsonl داخله.
  • يضيف المستخدم الملف إلى «قراءة الأحداث من ملف» في بطاقة SDK. يجب أن يوضح README التعديل موقعه. يتابعه Hovermate مثل ملف الاستقبال.
  • يمكن للتعديل أيضًا طباعة مساره مرة كسطر سجل [HOVERMATE] أو إرساله في hello.files، وهي مصفوفة مسارات، عند توفر وسيلة نقل أخرى. يقترح Hovermate إضافته بعد ذلك.

3. كائن الحدث

{
  "v": 1,
  "game": { "id": "com.example.mygame", "name": "My Game", "exe": "MyGame.exe" },
  "type": "kill",
  "label": "Double kill",
  "tags": ["headshot"],
  "context": "Act 2 · The City",
  "time": "2026-11-09T21:15:03.120Z"
}
  • v — مطلوب، 1.
  • game.id — مطلوب، [a-z0-9._-]{3,64}. اسم DNS معكوس أو معرّف قصير، ثابت بين إصدارات التعديل.
  • game.name — مطلوب في أول حدث أو hello لكل جلسة؛ بحد أقصى 64 محرفًا.
  • game.exe — اختياري، اسم ملف فقط. يربط الأحداث بمجلد اللعبة المكتشف ويتيح لملفها التنفيذي بدء مخزن الإعادة المؤقت.
  • type — مطلوب. نوع قياسي من القائمة المشتركة في Docs/CLIPS.md: kill, death, assist, multikill, roundWon, roundLost, matchWon, matchLost, mvp, objective, lap, bestLap, position, crash, incident, levelUp, bossKill, zone, achievement, goal, save, mission, fightWon, penalty, pit, finish, raceWon, landing, takeoff؛ أو "custom". القائمة في Docs/CLIPS.md هي المرجع وتزداد فقط. يرفض النوع المجهول بالاستجابة 400.
  • customType / customLabel — مطلوبان عندما تكون type هي "custom". يطابق customType النمط [a-z0-9_.-]{1,32}؛ وcustomLabel اسم المفتاح في البطاقة بحد أقصى 40 محرفًا.
  • label — نص عرض اختياري لهذا الحدث في تلميح العلامة وعنوان المقطع، حتى 80 محرفًا.
  • tags — اختياري، حتى 8 وسوم يطابق كل منها [a-z0-9_-]{1,24}.
  • context — خريطة أو مستوى أو منطقة اختيارية لعناوين اللقطات البارزة، حتى 64 محرفًا.
  • time — اختياري بصيغة ISO-8601 UTC. يسجل Engine وقت الوصول؛ تدققه قيمة time ضمن ±5 ثوانٍ، ويتجاهل غير ذلك.
  • تتجاهل الحقول المجهولة، لذا تضيف الإصدارات المستقبلية حقولًا فقط.
  • تحسب حدود النص بوحدات UTF-16، مثل length في JavaScript وstring.Length في .NET. يجب أن يطابق النمط القيمة كاملة؛ فالسطر الجديد في النهاية غير صالح. تعامل النصوص الفارغة أو المكونة من مسافات فقط كحقول مفقودة.
  • لا ترسل بيانات شخصية. قد تظهر التسميات والسياقات في عناوين المقاطع وأسماء الملفات.
{ "v": 1, "game": { "id": "com.example.mygame", "name": "My Game", "exe": "MyGame.exe" },
  "type": "hello",
  "offers": ["kill", "death", "bossKill", { "customType": "parry", "customLabel": "Parry" }],
  "log": "%LOCALAPPDATA%\\MyGame\\Saved\\Logs\\MyGame.log" }
  • يسمح لـHovermate بإنشاء بطاقة اللعبة ومفاتيح اللقطات البارزة قبل أول حدث فعلي.
  • يسرد offers الأنواع القياسية و/أو كائنات الأنواع المخصصة.
  • يقترح log الاختياري سجلًا لطريقة أسطر السجل؛ ويقترح files ملفات مجلد التعديل (§2.4). يطلب Hovermate إذن المستخدم قبل قراءة أي مسار مقترح.
  • يقبل hello عبر كل وسائل النقل، بما فيها سطر سجل [HOVERMATE].

5. سلوك Hovermate

  • ينشئ أول حدث صالح أو hello من game.id جديد بطاقة لعبة «SDK». تستخدم الاسم وexe ومجلد اللعبة وغلافها إن طابق exe لعبة مثبتة، ومفتاحًا لكل نوع معلن أو مستلم وإعدادات الزمن قبل الحدث وبعده. تظل اللقطات البارزة متوقفة حتى يفعّل المستخدم الأنواع؛ وتكتب العلامات دائمًا.
  • تمر الأحداث بالمسار نفسه للبطاقات المدمجة: السجل، وعلامات المقاطع والجلسات، ونافذة اللقطات البارزة، والإشعارات.
  • تنسب الأحداث للعبة المكتشفة في المقدمة عندما يطابقها game.exe. وإلا فلا تقبل إلا عند عمل التسجيل أو المخزن المؤقت، وتنسب إلى لعبة SDK.
  • الحدود:
    • 20 حدثًا/ثانية لكل لعبة؛
    • 200 نوع مخصص لكل لعبة؛
    • تتجاهل أسطر الاستقبال الأكبر من 4 KB؛
    • تحتسب الأسطر غير الصالحة وتعرض في حالة البطاقة («N أحداث غير صالحة»)، ولا يسجل محتواها الخام.