Hyperfocus game integration: the game bridge and the Scratch extension

Hyperfocus is the launcher for the games on ikelene.net and the community site. When it starts your game it also opens a small local web server that the game can call, so the game can set its Discord status, read who is playing, invite friends, hand out achievements and show launcher notifications. This guide is the overview and the reference for that server (the game bridge) and for the Hyperfocus Scratch extension that wraps it.

What a game can use

• Sign in with Velora - the launcher gives the game its own Velora token in an environment variable. Velora login guide.
• Discord Rich Presence and friends' status - the game sets the line under its title and what friends see. Presence guide.
• Game invites and join codes - friends invite each other into the running game. Invites guide.
• Achievements and launcher notifications. Achievements guide.
• Everything on the publishing side - cloud saves, betas, trailers, keys, sales and more. Publishing guide.

How Hyperfocus launches your game

When the player presses Play, Hyperfocus runs the game's executable from its install folder (the executable's folder is the working directory). Only .exe, .cmd and .bat files are started and tracked this way. Anything else (an .html file, for example) is simply opened with its default program, and then the launcher has no running game to attach the bridge or the Velora token to. If you ship a web game, package it as an app first (the community site can package .sb3, .pmp and .html projects for you, see the publishing guide).

• Command-line arguments come from the game's args list.
• If the game has a Velora login configured, two environment variables are added: HF_VELORA_TOKEN and HF_VELORA_USER.
• While the process runs the game counts as running, and the bridge accepts calls for it. When the process ends, everything the game set (Discord line, friends status, invite state, accepted invite) is cleared.

Game IDs

Every game has an ID. Official games use the id in the Hyperfocus game list (for example fnaj). Community games use c- plus the 8-character ID shown on the community site, for example c-cyqr2nr2. With Developer Mode on, right-click a game in Hyperfocus and choose Copy game ID. Use the c-<id> form in every call; the bare 8-character ID also works for presence, invites and notifications from Hyperfocus 1.3.33-beta.4 onward (achievement calls have always accepted it). When the game was launched by Hyperfocus the simplest thing is to leave the game ID out and let the launcher use the game that is running.

Links that open Hyperfocus

The game bridge

The bridge listens on http://127.0.0.1:47833, on this PC only. All replies are JSON.

• The Host header must be 127.0.0.1 or localhost; anything else gets 403 forbidden (this blocks DNS rebinding).
• CORS is open (Access-Control-Allow-Origin: *, plus the Private Network header), so browsers can call it. OPTIONS requests are answered. The Scratch extension posts as text/plain so no preflight is needed.
• POST bodies are JSON and at most 4096 bytes (413 too_big, 400 bad_json otherwise).
• Which game? The call uses the game field of the body (or ?game= in the URL). If it is missing, the only running game is used, or the most recently launched one.
• Only games Hyperfocus started. If the game is not running you get 409 not_running. Running the project in an editor or browser therefore does nothing, unless you use Developer Mode (below).
• Website permission. A packaged game sends no Origin header and is always fine. A request from a website (an editor in the browser, for example) is allowed only for sites the player has allowed once: the first call raises an Allow or Block popup in Hyperfocus and answers 403 needs_permission. Blocked sites get 403 site_blocked. The player changes this under Settings, game blocks. This check covers /user, /friends/open, /invite*, /achievements* and /notify; /status and /presence* are open.
• Every call except the constant status and invite polling is written to %APPDATA%\hyperfocus\bridge.log, which is handy when something does not work.

Endpoints

GET /hyperfocus/status

curl http://127.0.0.1:47833/hyperfocus/status

{
  "ok": true,
  "hyperfocus": true,
  "version": "1.3.33",
  "running": ["fnaj"],
  "currentGame": "fnaj",
  "devNoGame": false
}

running lists the games Hyperfocus launched that are still open. devNoGame is true when Developer Mode allows connections with no game open. A game is "launched from Hyperfocus" when its ID is in running (or devNoGame is true).

POST /hyperfocus/presence

All fields are optional. Details in the Discord presence guide.

curl -X POST http://127.0.0.1:47833/hyperfocus/presence \
  -H "Content-Type: application/json" \
  -d '{"state":"Night 1 - 5 AM","status":"In the lobby","appId":"123456789012345678"}'

{ "ok": true, "game": "fnaj",
  "presence": { "state": "Night 1 - 5 AM", "status": "In the lobby", "clientId": "123456789012345678" } }

• state - the line under the title on Discord (up to 128 characters; empty goes back to the game's name).
• status - what friends see in Hyperfocus as "playing <game> - <status>" (up to 128 characters; empty removes it).
• appId - a Discord application ID (15 to 22 digits) to use for this session; 400 bad_app_id otherwise. Empty goes back to the default.

POST /hyperfocus/presence/reset clears all three.

GET /hyperfocus/user

{ "ok": true, "loggedIn": true, "username": "Ikelene", "pfp": "https://...", "color": "#b09bcb", "rank": "owner" }

If nobody is logged in, loggedIn is false and the other fields are empty. This works without a game running. It is for showing the player's name and picture; it is not proof of identity. For anything that matters, use the Velora token and validate it.

Invites

POST /hyperfocus/invites   {"enabled": true, "code": "room123"}
-> { "ok": true, "invites": { "enabled": true, "code": "room123" } }

GET  /hyperfocus/invite
-> { "ok": true, "invite": { "code": "room123", "from": "Ikelene", "seq": 3 }, "invites": { "enabled": true, "code": "room123" } }
   ("invite" is null when nothing was accepted)

POST /hyperfocus/invite/clear    -> { "ok": true }
POST /hyperfocus/friends/open    -> { "ok": true }

The join code may contain letters, numbers, - and _, up to 64 characters (400 bad_code otherwise). See the invites guide for the whole flow.

Achievements

GET /hyperfocus/achievements
-> { "ok": true, "game": "fnaj", "achievements": {
     "night1": { "name": "Night 1", "description": "Survive the first night", "icon": "https://...",
                 "rarity": "common", "hidden": false, "game": "fnaj", "gameName": "Five Nights at JARVIS",
                 "unlocked": true, "unlockedAt": 1790000000000 } } }

POST /hyperfocus/achievements/grant    {"achievement": "night1"}
POST /hyperfocus/achievements/revoke   {"achievement": "night1"}

Hidden achievements the player does not have yet are returned as "Hidden Achievement". Grant answers { "ok": true, "game", "new": true|false, "achievement": {...} } and revoke { "ok": true, "game", "revoked": true|false }; Velora's own errors (404 achievement_not_found, 403 wrong_game) are passed on. See the achievements guide.

POST /hyperfocus/notify

curl -X POST http://127.0.0.1:47833/hyperfocus/notify \
  -d '{"title":"Night 1 complete!","text":"Only 4 more to go..."}'

{ "ok": true, "game": "fnaj" }

Shows a toast over the game. The title is trimmed to 80 characters (default is the game's name) and the text to 240. A game can send one every 1.5 seconds (429 too_fast otherwise). Clicking it opens the game in Hyperfocus.

Error replies

Calling the bridge from code

It is plain HTTP, so any language works. Check /status first and keep going quietly when it is not there, because players can also run your game without Hyperfocus.

// JavaScript (browser or Electron renderer)
const HF = 'http://127.0.0.1:47833/hyperfocus';

async function hyperfocus(path, body) {
  try {
    const res = await fetch(HF + path, body === undefined ? {} : {
      method: 'POST',
      headers: { 'Content-Type': 'text/plain' },      // text/plain: no CORS preflight
      body: JSON.stringify(body),
    });
    return await res.json();
  } catch {
    return { ok: false, error: 'hyperfocus_not_reachable' };
  }
}

const status = await hyperfocus('/status');
if (status.hyperfocus && status.running.length) {
  await hyperfocus('/presence', { state: 'Night 1 - 5 AM' });
  await hyperfocus('/achievements/grant', { achievement: 'night1' });
}

# Python
import requests

HF = "http://127.0.0.1:47833/hyperfocus"

def hyperfocus(path, body=None):
    try:
        r = requests.post(HF + path, json=body, timeout=2) if body is not None else requests.get(HF + path, timeout=2)
        return r.json()
    except Exception:
        return {"ok": False, "error": "hyperfocus_not_reachable"}

hyperfocus("/notify", {"title": "Level 2", "text": "New area unlocked"})

Testing without launching from Hyperfocus

In Hyperfocus open Settings, developer, turn on Developer Mode, then turn on Allow game extension connections when no game is open. The bridge then accepts presence, invite, achievement and notification calls even though Hyperfocus did not start the game. Without a running game, name the game in the call (game) - achievements and invites need a game ID; presence falls back to a test ID. Achievements also work for community games that are still waiting for review. The same settings page has the test achievement popups, the bridge log and the data folder.

The Hyperfocus Scratch extension

For TurboWarp and PenguinMod projects (including projects packaged into an app) there is an extension that wraps the bridge. Add it as a custom extension from this URL:

https://ikelene.net/launcher/hyperfocus_extension.js

It works sandboxed or unsandboxed. While the game was not started from Hyperfocus, every command does nothing and the reporters are empty, so the same project can also be played elsewhere. The extension keeps checking for the launcher every 5 seconds, and when the launcher shows up (or comes back after a restart) it sends the Discord line, friends status, invite state and join code again. If you open Hyperfocus after the project started, use attempt reconnection to launcher.

Opening the project inside the editor in a browser needs the one-time Allow popup in Hyperfocus (see above) and Developer Mode, because the editor was not started by the launcher. The extension has a How to test? button that explains this.

Blocks

General

launched from Hyperfocus? is true while the launcher can hear the game. this game's Hyperfocus ID is is only needed when several apps run at once, for achievements while testing, or for Developer Mode. last Hyperfocus response is the raw JSON of the last call, for debugging.

Discord status

Player

[INFO] of the player has a menu: profile picture URL, accent colour, rank.

Friends and multiplayer

Achievements

all achievements (JSON) reports the same object as GET /hyperfocus/achievements.

Questions