← Doku

Rich Presence

Eine Aktivität ist das, was jemand gerade tut: Spielt Tibia, darunter Jagt in Roshamuul, Level 412 Elite-Ritter, ein Bild und ein Timer. GameVox verwendet das Aktivitätsobjekt von Discord und die Wege, auf denen Discord es setzt, sodass Code, der für Discord Rich Presence geschrieben wurde, meist unverändert funktioniert. GameVox entscheidet, welcher Name angezeigt wird, und prüft alles andere.

Überblick

Es gibt vier Wege hinein und einen hinaus:

• Der eigene Status deines Bots: die presence beim Identify und Gateway-Op 3, genau wie bei Discord.
• Die Aktivität einer Person, gesetzt von deinem Server: ein REST-Aufruf mit deinem Bot-Token, für Personen, die deine App erlaubt haben (der Scope activities.write). Deine App braucht dafür eine Freigabe von GameVox.
• Die Aktivität einer Person, gesetzt von einem Programm auf ihrem Computer: der lokale RPC der Desktop-App, der das IPC-Protokoll von Discord RPC spricht.
• Die eigene Spielerkennung von GameVox, die du nicht steuerst, mit der deine Aktivität aber zusammengeführt werden kann.
• Hinaus: Bots mit dem Intent GUILD_PRESENCES erhalten PRESENCE_UPDATE, wenn sich Status oder Aktivität eines Mitglieds ändert.

Wo sie angezeigt wird: unter dem Namen in der Mitgliederliste eines Servers, auf der Profilkarte (Bild, Details, Zustand, Party, Timer, Buttons), in der DM-Kopfzeile und in der Freundesliste, auf Desktop, Web, iOS und Android.

Was angezeigt wird

Eine Person (oder ein Bot) zeigt höchstens einen benutzerdefinierten Status (Typ 4) und eine weitere Aktivität. Melden mehrere Quellen gleichzeitig etwas, gewinnt der lokale RPC vor einer App, eine App vor der eigenen Aktivität eines Bots und jede davon vor dem erkannten Spiel. Eine Aktivität für dasselbe Spiel, das GameVox erkannt hat, wird damit zusammengeführt: deine Details, dein Zustand und deine Bilder, dazu der Spielname von GameVox und dessen Startzeit, wenn du keine gesendet hast. Eine Aktivität für etwas anderes ersetzt das erkannte Spiel. Personen können noch keinen benutzerdefinierten Status setzen; Bots schon.

Das Aktivitätsobjekt

Die Felder sind die von Discord. Was du senden darfst, hängt davon ab, wer sendet (siehe die einzelnen Abschnitte). Alles wird bereinigt: Steuerzeichen und Zeichen zur Überschreibung der Schreibrichtung werden entfernt, Zeilenumbrüche werden zu Leerzeichen, mehrfache Leerräume werden zusammengefasst, und Text wird auf die unten genannten Grenzen gekürzt.

Die gesamte Aktivität muss nach der Bereinigung in 4096 Bytes JSON passen. Links (url, Button-URLs, details_url, state_url) müssen https sein, auf einem öffentlichen Hostnamen, ohne Benutzernamen, IP-Adresse oder Port. application_id, flags, instance, secrets, sync_id und alles andere, was du sendest, werden ersetzt oder verworfen.

Aktivitätstypen

Die einzeilige Form übersetzt GameVox in die Sprache der betrachtenden Person; deinen Text nicht.

Der Status deines Bots

Setz ihn wie bei Discord: das Feld presence beim Identify (Op 2) und Gateway-Op 3 (Presence Update), sobald er sich ändert. discord.js client.user.setPresence(), discord.py change_presence() und Ähnliches funktionieren unverändert.

{
  "op": 2,
  "d": {
    "token": "<bot token>",
    "intents": 513,
    "properties": { "os": "linux", "browser": "my-bot", "device": "my-bot" },
    "presence": {
      "since": null,
      "activities": [ { "name": "12 Tibia worlds", "type": 3 } ],
      "status": "online",
      "afk": false
    }
  }
}

{
  "op": 3,
  "d": {
    "since": null,
    "activities": [ { "name": "Custom Status", "type": 4, "state": "/help for commands" } ],
    "status": "dnd",
    "afk": false
  }
}

// discord.js
client.user.setPresence({
  activities: [{ name: 'raid signups', type: ActivityType.Watching }],
  status: 'idle',
});

# discord.py
await client.change_presence(activity=discord.Game(name="VALORANT"), status=discord.Status.online)

Was GameVox verwendet

• status: online, idle, dnd, invisible oder offline. Abwesend und Bitte nicht stören ändern den Punkt des Bots. Unsichtbar und offline zeigen den Bot als offline ohne Aktivität, während der Bot verbunden bleibt und weiterarbeitet. Ein fehlender Status bedeutet online; bei jedem anderen Wert wird das ganze Update ignoriert.
• activities: pro Aktivität nur name, type, state, url (Streaming) und der Emoji-Name (benutzerdefiniert). Alles andere wird verworfen. Die Liste wird auf einen benutzerdefinierten Status plus eine weitere Aktivität reduziert.
• Ein benutzerdefinierter Status (Typ 4) braucht einen state oder ein Emoji; sein Name kann beliebig sein (Discord sendet „Custom Status“).
• since und afk werden angenommen und ignoriert.
• Ein Identify ohne presence setzt den Bot auf den normalen Online-Status zurück. Ein Resume behält den bisherigen Status des Bots bei.

Grenzen

• Op 3 ist auf 5 pro 20 Sekunden pro Verbindung begrenzt. Wird das Limit überschritten, behält GameVox das neueste Update und wendet es an, sobald das Zeitfenster es erlaubt. Die Verbindung wird deswegen nie geschlossen.
• Mitglieder mit geöffnetem Client sehen eine Änderung innerhalb von 30 Sekunden: GameVox sendet höchstens ein Update pro Bot alle 30 Sekunden. Eine später geöffnete Mitgliederliste zeigt den aktuellen Status.
• Dieselbe Presence erneut zu senden, ändert nichts.

Der Status erscheint unter dem Namen des Bots in der Mitgliederliste und in seinem Profil, für die Mitglieder jedes Servers, auf dem der Bot ist, auch auf selbst gehosteten. Andere Bots erhalten ihn nicht.

Die Aktivität einer Person aus deiner App setzen

Dein Server kann zeigen, was eine Person in deinem Spiel tut, zum Beispiel anhand der Daten deines eigenen Spielservers, ohne dass auf dem Computer der Person etwas läuft. Das ist eine GameVox-Erweiterung: Discord hat keinen solchen Endpunkt.

Was es braucht

1. Freigabe. GameVox gibt Apps dafür von Hand frei. Bis deine freigegeben ist, antwortet jeder PUT mit 403 und Code 50001. Wende dich an den GameVox-Support. Die eigenen Apps von GameVox sind bereits freigegeben.
2. Die Zustimmung der Person. Die Person autorisiert deine App mit dem Scope activities.write über den normalen OAuth2-Zustimmungsbildschirm (Mit GameVox anmelden). Personen können das jederzeit in ihren Einstellungen widerrufen; ihre Aktivität aus deiner App verschwindet dann sofort.
3. Der Schalter der Person. Bei einer Person, die „Apps dürfen meine Aktivität festlegen“ ausgeschaltet hat, wird nichts angezeigt. Dein PUT antwortet trotzdem mit 204, du kannst es also nicht erkennen.

https://gamevox.com/oauth2/authorize/?client_id=1491200000000000000
    &response_type=code
    &scope=identify%20activities.write
    &redirect_uri=https%3A%2F%2Fexample.com%2Fgamevox%2Fcallback
    &state=8f2c1a

Setzen und löschen

Authentifiziere dich mit deinem Bot-Token. {user_id} ist die Snowflake der Person, so wie dein Bot sie überall sonst sieht.

PUT https://app-api.gamevox.com/api/v10/applications/@me/users/1491250000000000003/activity
Authorization: Bot <token>
Content-Type: application/json

{
  "activity": {
    "type": 0,
    "details": "Hunting in Roshamuul",
    "state": "Level 412 Elite Knight",
    "timestamps": { "start": 1761868000000 },
    "party": { "size": [2, 5] },
    "assets": {
      "large_image": "roshamuul", "large_text": "Roshamuul",
      "small_image": "knight", "small_text": "Elite Knight"
    },
    "buttons": [ { "label": "View character", "url": "https://example.com/characters/412" } ]
  },
  "ttl_seconds": 300
}

HTTP/1.1 204 No Content

DELETE https://app-api.gamevox.com/api/v10/applications/@me/users/1491250000000000003/activity
Authorization: Bot <token>

HTTP/1.1 204 No Content

Wie GameVox es liest

• ttl_seconds: wie lange die Aktivität ohne Auffrischung lebt, 60 bis 900 Sekunden (Standard 300; Werte außerhalb werden begrenzt). Sende den aktuellen Zustand per PUT erneut, bevor sie abläuft. Fällt dein Dienst aus, verschwindet die Aktivität von selbst.
• name wird ignoriert. GameVox zeigt den Namen des Spiels, mit dem deine App verknüpft ist, sonst den Namen deiner App, und fügt immer „über“ deine App hinzu.
• Typen 0, 1, 2, 3 und 5. Benutzerdefinierter Status (4) wird abgelehnt.
• Ein PUT ersetzt deine vorherige Aktivität für diese Person. Eine Auffrischung, die nichts ändert, verlängert nur die TTL. created_at bleibt gleich, solange Typ und Name gleich bleiben, damit die Karte nicht neu wirkt.
• Bildschlüssel müssen Assets deiner Anwendung sein. Unbekannte Schlüssel werden verworfen, und der Text wird trotzdem angezeigt.
• DELETE entfernt nur die Aktivität deiner App für diese Person und braucht keine Berechtigung. Die Antwort ist 204, unabhängig davon, ob eine solche Aktivität vorhanden war.

Fehler

HTTP/1.1 400 Bad Request

{
  "code": 50035,
  "message": "Invalid Form Body",
  "errors": {
    "activity": {
      "type": {
        "_errors": [
          { "code": "ACTIVITY_TYPE_INVALID",
            "message": "This activity type is not allowed for an application. Use 0, 1, 2, 3 or 5." }
        ]
      }
    }
  }
}

Grenzen

• 5 Anfragen pro 20 Sekunden pro Person, PUT und DELETE getrennt gezählt.
• 50 Anfragen pro Sekunde pro Anwendung über alle Personen hinweg.

Bilder

Lade Bilder im Tab Rich Presence deiner Anwendung hoch, jedes mit einem Schlüssel (1 bis 32 Zeichen, Buchstaben, Ziffern, _ und -, pro App eindeutig, Groß- und Kleinschreibung spielt keine Rolle). PNG, JPEG oder WebP bis zu 1 MB; jeder Upload wird geprüft, bevor er verwendet wird. Setz in einer Aktivität den Schlüssel in assets.large_image oder assets.small_image.

• GameVox sucht den Schlüssel unter den Assets der Anwendung, zu der die Aktivität gehört: deiner App beim REST-Endpunkt und bei einem Bot, der App, für die die lokale Client-ID steht, beim RPC. Auf nichts anderes kann verwiesen werden.
• Ohne großes Bild zeigt GameVox sein eigenes Artwork für das Spiel, sonst das Symbol deiner App. Das kleine Bild erscheint nur über einem großen.
• Ein gelöschtes Asset verschwindet innerhalb weniger Minuten von den Karten.
• Bild-URLs, Werte des Discord-Medienproxys mp: und Schlüssel anderer Apps werden verworfen.

Die Assets einer App auflisten

Die Asset-Liste ist öffentlich, wie bei Discord, damit Tools prüfen können, welche Schlüssel es gibt. Keine Authentifizierung.

GET https://app-api.gamevox.com/api/v10/oauth2/applications/1491200000000000000/assets

HTTP/1.1 200 OK
Cache-Control: public, max-age=300

[
  { "id": "6f1c2e3a-…", "name": "roshamuul", "type": 1 },
  { "id": "9b0d4c7e-…", "name": "knight", "type": 1 }
]

• Nur Bild-Assets, die ältesten zuerst. id ist die ID des Assets, name sein Schlüssel, type immer 1.
• Eine unbekannte Anwendung antwortet mit 404 und Code 10002.
• Antworten werden 5 Minuten zwischengespeichert, ein neuer Upload kann also so lange brauchen, bis er erscheint. 30 Anfragen pro Minute pro IP.

Lokaler RPC der Desktop-App

Ein Programm auf dem Computer der Person (ein Spiel, ein Launcher, ein Mediaplayer) kann die Aktivität der Person über die GameVox-Desktop-App (Windows, macOS, Linux) setzen. Sie spricht das IPC-Protokoll von Discord RPC, sodass das Framing des Discord Game SDK und der Rich-Presence-Bibliotheken der Community unverändert funktioniert. Die Web-, iOS- und Android-Apps haben keinen lokalen RPC.

Verbindungsziel

• Windows: die Named Pipe \\.\pipe\gamevox-ipc-0 (probiere -0 bis -9).
• macOS und Linux: der Unix-Socket gamevox-ipc-0 bis -9 in $XDG_RUNTIME_DIR, sonst in $TMPDIR/gamevox-<uid>/.
• Nur Programme, die unter demselben Betriebssystem-Benutzer laufen, können sich verbinden. Nichts lauscht im Netzwerk, und es gibt keinen WebSocket- oder HTTP-Transport.
• Personen können den lokalen RPC in den Einstellungen von GameVox ausschalten (standardmäßig ist er an).

Kompatibilitätsmodus für Programme, die für Discord RPC gebaut sind

Ein Programm, das nur die Pipe-Namen von Discord kennt, findet GameVox, wenn die Person in den Einstellungen von GameVox den Kompatibilitätsmodus einschaltet (standardmäßig aus). GameVox antwortet dann auch auf discord-ipc-0 bis -9, aber nur, solange Discord nicht läuft: Es tritt beiseite, sobald Discord startet, und prüft alle 10 Sekunden erneut. Wenn möglich, verbinde dich selbst mit gamevox-ipc-N; bei den meisten Bibliotheken lässt sich der Pipe-Name festlegen, und dann ist der Kompatibilitätsmodus nicht nötig.

Framing

Jeder Frame besteht aus einem 8-Byte-Header, dem Opcode und der Payload-Länge als vorzeichenlose 32-Bit-Little-Endian-Ganzzahlen, gefolgt von ebenso vielen Bytes UTF-8-JSON. Bei Frames größer als 64 KB wird die Verbindung geschlossen.

Handshake und READY

Sende {"v": 1, "client_id": "…"} innerhalb von 10 Sekunden nach dem Verbinden. client_id ist deine Anwendungs-ID (15 bis 21 Ziffern). GameVox antwortet mit einem READY-Dispatch, der die angemeldete Person enthält (ihre GameVox-Snowflake). Ein ungültiger Handshake wird mit CLOSE und Code 4000 beantwortet.

→ op 0 HANDSHAKE
{ "v": 1, "client_id": "1491200000000000000" }

← op 1 FRAME
{
  "cmd": "DISPATCH",
  "evt": "READY",
  "nonce": null,
  "data": {
    "v": 1,
    "config": {
      "cdn_host": "files.gamevox.com",
      "api_endpoint": "//app-api.gamevox.com/api",
      "environment": "production"
    },
    "user": {
      "id": "1491250000000000003", "username": "ben", "discriminator": "0",
      "global_name": "Ben", "avatar": null, "bot": false, "flags": 0, "premium_type": 0
    }
  }
}

SET_ACTIVITY

Die Antwort enthält die Aktivität so, wie GameVox sie angenommen hat. "activity": null löscht sie, ebenso das Schließen der Verbindung. Das Programm, das zuletzt eine Aktivität gesetzt hat, besitzt die eine lokale Aktivität.

→ op 1 FRAME
{
  "cmd": "SET_ACTIVITY",
  "nonce": "7c1f0a52",
  "args": {
    "pid": 4242,
    "activity": {
      "type": 0,
      "details": "Hunting in Roshamuul",
      "state": "Level 412 Elite Knight",
      "timestamps": { "start": 1761868000 },
      "assets": { "large_image": "roshamuul", "large_text": "Roshamuul" },
      "party": { "id": "p1", "size": [2, 5] }
    }
  }
}

← op 1 FRAME
{
  "cmd": "SET_ACTIVITY",
  "evt": null,
  "nonce": "7c1f0a52",
  "data": {
    "id": "a41c09e2f3b8d715", "name": "Tibia", "type": 0, "url": null,
    "created_at": 1761868800000,
    "timestamps": { "start": 1761868000000 },
    "application_id": "1491200000000000000",
    "details": "Hunting in Roshamuul", "state": "Level 412 Elite Knight", "emoji": null,
    "party": { "id": "p1", "size": [2, 5] },
    "assets": { "large_image": "roshamuul", "large_text": "Roshamuul" },
    "flags": 0
  }
}

Zustimmung und Identität

• Nichts verlässt den Computer, bis die Person dein Programm zulässt. Beim ersten Mal fragt GameVox: Erlauben, Nicht jetzt oder Niemals. Die Antwort wird pro ausführbarer Datei und Client-ID gespeichert. Bis dahin antwortet SET_ACTIVITY wie gewohnt, und die Aktivität wartet.
• GameVox erlaubt ohne Nachfrage, wenn dein Programm das erkannte Spiel ist und deine Client-ID auf GameVox mit diesem Spiel verknüpft ist.
• GameVox erfährt vom Betriebssystem, wer du bist (der Prozess am anderen Ende der Pipe und seine ausführbare Datei), nie aus args.pid oder irgendetwas anderem in der Payload.
• Den Namen wählt GameVox, nicht du: das Spiel oder die App, mit der deine Client-ID auf GameVox verknüpft ist, sonst das von GameVox erkannte Spiel, wenn deine ausführbare Datei dieses Spiel ist, sonst das Spiel, als das der Katalog deine ausführbare Datei kennt, sonst „eine App“. name in deiner Aktivität wird ignoriert.
• Buttons werden nur angezeigt, wenn deine Client-ID zu einer freigegebenen oder GameVox-eigenen App gehört. Bilder werden gegen die Assets dieser App aufgelöst.
• Text wird von den Servern von GameVox erneut geprüft, und unzulässige Details oder Zustände werden entfernt.

Grenzen: 5 SET_ACTIVITY pro 20 Sekunden pro Verbindung, mit mindestens 500 ms Abstand; schnellere Updates werden zusammengefasst, und das neueste gewinnt. Höchstens 16 gleichzeitig verbundene Programme.

Die Presence von Mitgliedern empfangen

Mit dem Intent GUILD_PRESENCES erhält dein Bot PRESENCE_UPDATE, wenn ein Mitglied eines Servers, auf dem er ist, seinen Status oder seine Aktivität ändert, im Discord-Format.

{
  "op": 0,
  "t": "PRESENCE_UPDATE",
  "d": {
    "user": { "id": "1491250000000000003" },
    "guild_id": "1491230000000000001",
    "status": "online",
    "activities": [ {
      "id": "a41c09e2f3b8d715", "name": "Tibia", "type": 0, "url": null,
      "created_at": 1761868800000,
      "timestamps": { "start": 1761868000000 },
      "application_id": "1491200000000000000",
      "details": "Hunting in Roshamuul", "state": "Level 412 Elite Knight", "emoji": null,
      "assets": { "large_image": "roshamuul", "large_text": "Roshamuul" },
      "buttons": [ "View character" ],
      "flags": 0
    } ],
    "client_status": { "desktop": "online" }
  }
}

• status ist online, idle, dnd oder offline. Ein unsichtbares Mitglied ist offline ohne Aktivitäten. client_status nennt immer desktop.
• Du siehst, was die Mitglieder des Servers sehen würden: kein Spiel, das ein Mitglied nicht mit diesem Server teilt, kein Spiel für Erwachsene, das es nicht anzeigen möchte, und von einem Mitglied, das Details ausgeschaltet hat, nur Name und Typ.
• Aktivitäten sind Discord-Objekte mit einer id und created_at. buttons sind nur Labels; du bekommst nie eine Button-URL und keine eigenen Felder von GameVox.
• Nur Änderungen: In GUILD_CREATE und in Mitglieder-Chunks gibt es keine Presences. Änderungen werden pro Mitglied über etwa 2 Sekunden gebündelt.
• Die eigenen Status von Bots werden nicht an andere Bots gesendet.

Selbst gehostete Server

Auf einem selbst gehosteten Server:

• Der Status deines Bots funktioniert genauso und wird den Mitgliedern des Servers angezeigt.
• Der lokale RPC der Desktop-App funktioniert genauso, aber der Server kann keine Client-IDs nachschlagen: Er zeigt den Namen des erkannten Spiels, wenn deine Aktivität für dieses Spiel ist, sonst „eine App“. Keine Buttons, und Bilder nur vom eigenen Datei-Host von GameVox.
• Aktivitäten, die aus deiner App über den REST-Endpunkt gesetzt werden, erscheinen in der GameVox-Cloud (Profile, Freunde, Cloud-Server), nicht auf selbst gehosteten Servern.
• PRESENCE_UPDATE funktioniert genauso und wird vom Server selbst gesendet.

Nicht unterstützt

• Beitreten, Zuschauen und Beitrittsanfragen (secrets, party.privacy, Lobbys) sowie die zugehörigen RPC-Ereignisse.
• Bild-URLs und Bilder über den Discord-Medienproxy (mp:): Lade stattdessen Assets hoch.
• Der RPC über WebSocket oder HTTP und die RPC-Autorisierung (AUTHORIZE / AUTHENTICATE).
• Benutzerdefinierter Status für Personen und Headless-Sitzungen.

Gateway-Intents →  ·  Zurück zur Doku