Discord Rich Presence and friends' status for Hyperfocus games

While a game runs, Hyperfocus shows it on the player's Discord profile as a Rich Presence card, and shows it to their Hyperfocus friends as "playing <game>". Your game does not need a Discord library: it sends a few fields to the launcher and the launcher does the rest. This guide covers what the card looks like, what a game may change, and how to do it.

What the card shows

With no input from your game, the card is built from the game's entry in Hyperfocus:

• Title - the name of the Discord application. By default that is "Hyperfocus".
• Details line - the game's name, or whatever your game set (below). There is no state line: the launcher does not print "Playing via Hyperfocus".
• Large image - the game's icon when it is an https:// picture, otherwise the Hyperfocus logo. An official game can override it with the name of an uploaded Rich Presence asset (discordAsset).
• Small badge - the Hyperfocus logo, with "via HYPERFOCUS" on hover. It is shown whenever the large image is not the plain Hyperfocus logo.
• Timer - how long the game has been running.
• Button - "Install HYPERFOCUS", which opens the launcher's download page. It cannot be removed or changed.

When the launcher is open but no game is running there is no details line, just the Hyperfocus logo and the install button. When the launcher is hidden in the tray the card is cleared. Rich Presence is on by default; players can turn it off in Settings, discord. If Discord is not running, Hyperfocus retries every 30 seconds and nothing ever fails for the game.

What a game can change

Only three things, all through POST /hyperfocus/presence on the game bridge:

Everything a game sets lasts until the game closes, or until POST /hyperfocus/presence/reset. The call only works while Hyperfocus has the game running (409 not_running otherwise), unless the developer settings allow it for testing.

curl -X POST http://127.0.0.1:47833/hyperfocus/presence \
  -H "Content-Type: application/json" \
  -d '{"state":"Night 1 - 5 AM"}'

In the Scratch extension:

Your own Discord application

Discord always puts the application's name in the big title. To make the title your game's name:

1. Create an application at discord.com/developers named after your game.
2. Copy its application ID (a long number).
3. Give the ID to Hyperfocus: for an official game put it in the game's discordAppId setting in the game list (the owner sets it in the official editor, where there is also an optional discordAsset for a Rich Presence asset name). For any other game, send it at runtime with appId or the Scratch block use Discord application ID [ID] for this session.

The community site's editor has no field for a Discord application ID, so community games switch applications from the game itself with appId.

How the member-list line behaves

The short "Playing ..." line in Discord's member list follows this rule, so it never shows a confusing text:

• Your own application (set with discordAppId or appId): the application's name, which is already the game's name.
• The Hyperfocus application and no custom line: the details line, which is the game's name.
• The Hyperfocus application and a custom line: the game's name goes to the state line and the member list shows the game's name.

Friends' status in Hyperfocus

Separately from Discord, Hyperfocus tells the player's friends (through Velora) which game they are playing:

• Friends see "playing <game>" in the launcher's friends list, in the in-game overlay, in the chat list and on the player's Velora profile.
• The status you set is added after it: "playing <game> - In the lobby".
• A friend gets a "started playing" popup when the player starts a game.
• The game's name and icon come from its entry. The icon is only sent when it is an https:// picture.
• It is cleared when the game closes.

curl -X POST http://127.0.0.1:47833/hyperfocus/presence -d '{"status":"In the lobby"}'
curl -X POST http://127.0.0.1:47833/hyperfocus/presence -d '{"status":""}'   # remove it

Testing

Launch the game from Hyperfocus and watch your own Discord profile. To test from the Scratch editor in the browser, turn on Developer Mode in Hyperfocus settings and allow game extension connections with no game open; presence then runs under the game ID you set (or a test ID). The game integration guide explains it.

Questions