Achievements and launcher notifications for Hyperfocus games

Hyperfocus has a built-in achievement system. You describe your game's achievements once, your game unlocks them with one call, and the launcher does the rest: a popup with a sound, the list on the game's page, the percentage of players who have each one, and a place on the player's Velora profile. The same bridge can also show a notification in the launcher over your game.

Define the achievements

Community games

Open your game in the community editor and go to the achievements tab. Add each achievement with the fields above (you can upload an icon for it), up to 100 per game, then press save achievements. Every achievement gets an ID once saved (it looks like a1b2c3d4e5f) with a copy ID button. That ID is what your game sends to grant it.

Official games

Official games keep their achievements in the game list, as an object keyed by an ID the owner chooses:

"achievements": {
  "night1": { "name": "Night 1", "description": "Survive the first night", "icon": "assets/fnaj/night1.png", "rarity": "common" },
  "no-power": { "name": "In the dark", "description": "Run out of power", "hidden": true, "rarity": "rare" }
}

An ID may contain letters, numbers, ., _ and -, up to 64 characters. IDs are looked up across all games, and when two games use the same ID the first one wins, so pick IDs that are unlikely to clash (a short game prefix works).

Grant and revoke

The player has to be logged in to Velora in Hyperfocus, and the game has to be launched from Hyperfocus (see the game bridge). The call is made as the launcher's login, not with your game's own token, and a game can only touch its own achievements.

POST http://127.0.0.1:47833/hyperfocus/achievements/grant
{ "achievement": "night1" }

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

POST /hyperfocus/achievements/revoke    { "achievement": "night1" }
-> { "ok": true, "game": "fnaj", "revoked": true }

GET  /hyperfocus/achievements
-> { "ok": true, "game": "fnaj", "achievements": { "night1": { "name": "Night 1", "description": "...", "icon": "...",
     "rarity": "common", "hidden": false, "game": "fnaj", "gameName": "...", "unlocked": true, "unlockedAt": 1790000000000 } } }

• Granting one the player already has returns "new": false and shows nothing, so you can call grant freely.
• unlockedAt is a time in milliseconds, and null while locked.
• The achievement ID must match the pattern above (400 bad_achievement_id). An unknown ID answers 404 achievement_not_found and an ID from another game 403 wrong_game.
• For a community game you can pass the 8-character game ID with or without the c- prefix.
• If the player is not logged in the call answers 401 not_logged_in.

Scratch blocks

The Hyperfocus extension (https://ikelene.net/launcher/hyperfocus_extension.js) has the same four operations:

The list is cached for 3 seconds inside the extension. Use this game's Hyperfocus ID is if the project could run next to other Hyperfocus games.

What the player sees

• A popup at the bottom of the screen with a sound, over the game. Up to 3 popups stack at once and extra ones wait in line.
• The game's page in Hyperfocus lists every achievement with its unlock date and "% of players" bar. The percentage is the share of people who have played the game and hold it, and it is refreshed when someone unlocks one. Locked hidden achievements sort last, the rest by percentage of players (most common first), and ties keep the order you defined them in.
• The in-game overlay has an achievements widget for the running game.
• Perfect Game - when a player has every achievement, the widget turns gold.
• Profiles - unlocked achievements, grouped by game, show on the player's Velora profile and in Hyperfocus profile popups.

Offline behaviour

If Velora cannot be reached (no connection, a server error, or Offline Mode), grant and revoke still work: the launcher reads the achievement list from the game's own entry, shows the popup straight away and queues the change in a file on the player's PC. The queue is sent again before the next refresh and every 60 seconds. An offline GET returns the game's list with "offline": true.

Testing

In the Hyperfocus settings, turn on Developer Mode (Settings, developer) for test achievement popups, the bridge log and the data folder. To grant from an editor in a browser, also tick Allow game extension connections when no game is open and name the game: the Scratch block this game's Hyperfocus ID is [ID], or "game" in the request body. With Developer Mode, right-click a game for Copy game ID and Copy achievement IDs. Achievements work for community games that are still waiting for review, so you can test before the game goes public.

Launcher notifications

A game can also pop a message up in the launcher, over the game, for things that are not achievements (a night finished, a friend joined, a download done):

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

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

• The title is cut to 80 characters (blank means the game's name) and the text to 240; line breaks become spaces.
• The notification shows the game's icon, plays the launcher's warning sound and, when clicked, opens the game in Hyperfocus.
• One every 1.5 seconds per game: faster calls get 429 too_fast. Use it sparingly; players can mute launcher sounds.
• From a website (an editor in the browser) it needs the one-time Allow popup like the other player-facing calls.

Questions