HovermateHovermateदस्तावेज़
हिन्दी

गेम इवेंट SDK · संदर्भ

प्रोटोकॉल v1

गेम और Hovermate के बीच अनुबंध। यह पेज SDK डाउनलोड में मौजूद PROTOCOL.md से बनाया जाता है।

लक्ष्य: किसी गेम या मॉड को Hovermate में इवेंट भेजने देना, जो अंतर्निहित गेम कार्ड की तरह टाइमलाइन मार्कर और स्वचालित हाइलाइट बनाता है। तीन ट्रांसपोर्ट नेटवर्क, केवल फ़ाइल और केवल लॉग वाली मॉड परिस्थितियों को संभालते हैं।

1. कनेक्शन खोजना

SDK चालू होने पर Engine %LOCALAPPDATA%\Hovermate\Sdk\connection.json लिखता है (सेटिंग › क्लिप › गेम इवेंट 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 से अस्वीकार होते हैं, इसलिए ब्राउज़र इवेंट नहीं भेज सकते।
  • बॉडी में एक इवेंट ऑब्जेक्ट या अधिकतम 100 इवेंट वाला { "events": [ ... ] } होता है। अधिकतम बॉडी 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 इनबॉक्स (मॉड जो फ़ाइल लिख सकते हैं, नेटवर्क नहीं)

  • {inbox}\<game.id>.jsonl में UTF-8 पंक्तियाँ जोड़ें, हर पंक्ति में एक इवेंट ऑब्जेक्ट, बिना BOM।
  • टोकन नहीं चाहिए: फ़ोल्डर उपयोगकर्ता का है।
  • शुरुआत में Engine इनबॉक्स की हर *.jsonl फ़ाइल को उसके अंत से पढ़ना शुरू करता है। मॉड सेशन शुरू होने पर अपनी फ़ाइल खाली कर सकता है।

2.3 लॉग पंक्ति का नियम (स्क्रिप्ट मॉड जो केवल गेम लॉग में लिखते हैं)

  • पंक्ति में [HOVERMATE] मार्कर के बाद एक JSON इवेंट ऑब्जेक्ट होना चाहिए। मार्कर से पहले का सब, जैसे समय और चैनल नाम, अनदेखा होता है।
  • SDK कार्ड में «फ़ाइल से इवेंट पढ़ें» सूची है जहाँ खिलाड़ी लॉग का पथ जोड़ता है। दूसरे ट्रांसपोर्ट से मिला hello इवेंट (§4) भी उसे सुझा सकता है। Engine मौजूदा लॉग-टेल एडेप्टर से फ़ाइल पढ़ता है।
  • ज्ञात स्क्रिप्ट लॉग वाले गेम में Hovermate गेम चलने तक उन्हें अपने-आप पढ़ता है। सूची गेम कैटलॉग (sdkLogs) में है, जैसे Documents\The Witcher 3\scriptslog.txt और Skyrim/Fallout के Papyrus लॉग। इन मॉड में उपयोगकर्ता को केवल गेम का स्क्रिप्ट लॉग चालू करना होता है।

2.4 मॉड फ़ोल्डर इवेंट फ़ाइल (केवल अपने फ़ोल्डर में लिखने वाले सैंडबॉक्स)

  • Cyber Engine Tweaks Lua मॉड जैसे कुछ वातावरण केवल मॉड फ़ोल्डर में लिखने देते हैं। ऐसे मॉड उसी फ़ोल्डर के hovermate-events.jsonl में JSONL पंक्तियाँ (§2.2) जोड़ते हैं।
  • उपयोगकर्ता 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}। reverse-DNS या छोटा पहचानकर्ता, मॉड संस्करणों में स्थिर।
  • game.name — सेशन के पहले इवेंट या hello में आवश्यक; अधिकतम 64 अक्षर।
  • game.exe — वैकल्पिक, केवल फ़ाइल नाम। इवेंट को पहचाने गेम फ़ोल्डर से जोड़ता है और उस executable को रीप्ले बफ़र शुरू करने देता है।
  • 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 आगमन का समय लिखता है; उससे ±5 सेकंड के भीतर का time उसे सुधारता है, अन्य मान अनदेखे होते हैं।
  • अनजान फ़ील्ड अनदेखे होते हैं, इसलिए भविष्य के संस्करण केवल फ़ील्ड जोड़ते हैं।
  • अक्षर सीमा UTF-16 कोड इकाइयों में गिनी जाती है, जैसे JavaScript का length और .NET का string.Length। पैटर्न पूरे मान से मेल खाना चाहिए; अंत का नया लाइन अक्षर गलत है। खाली या केवल खाली जगह वाला पाठ गायब माना जाता है।
  • निजी डेटा न भेजें। लेबल और संदर्भ क्लिप शीर्षक और फ़ाइल नामों में दिख सकते हैं।
{ "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 का व्यवहार

  • नए game.id का पहला सही इवेंट या hello, «SDK» गेम कार्ड बनाता है। इसमें नाम, exe, इंस्टॉल गेम से मेल होने पर उसका फ़ोल्डर और कवर, हर घोषित या मिले प्रकार का टॉगल और इवेंट के पहले/बाद का समय होता है। उपयोगकर्ता के प्रकार चालू करने तक हाइलाइट बंद रहते हैं; मार्कर हमेशा लिखते हैं।
  • इवेंट अंतर्निहित कार्ड जैसा प्रवाह लेते हैं: जर्नल, क्लिप और सेशन मार्कर, हाइलाइट विंडो तथा सूचनाएँ।
  • game.exe पहचाने गए सामने के गेम से मिले तो इवेंट उसी के होते हैं। अन्यथा केवल रिकॉर्डिंग या बफ़र चलने पर स्वीकार होते हैं और SDK गेम का नाम पाते हैं।
  • सीमाएँ:
    • हर गेम के लिए 20 इवेंट/सेकंड;
    • हर गेम में 200 कस्टम प्रकार;
    • 4 KB से बड़ी इनबॉक्स पंक्तियाँ हटा दी जाती हैं;
    • गलत पंक्तियाँ गिनकर कार्ड में «N अमान्य इवेंट» दिखते हैं; उनका मूल पाठ कभी लॉग नहीं किया जाता।