Yonest SDK guide

How your game runs on the platform

When a player clicks “Start game” they land on a platform page, not on your file. The platform puts a persistent top bar at the top of that page and loads your game in an iframe below it; your file lives at a different URL and is read directly by the iframe.

At runtime the shell attaches platform capabilities to the iframe's window, so from your file's point of view the platform is just “a window.Yonest that happens to exist”. That is also what makes “portability” possible: the file contains no platform scaffolding, only the optional calls you wrote yourself.

Three ground rules before integrating

You don't need to put the SDK into your own file

The platform loads yonest-sdk.js and installs it on the game window. All you do is call methods on window.Yonest from inside your game — don't copy this file into your HTML or import it yourself.

You don't need to implement sign-in or authorization

The player's identity comes from the platform session cookie; the game can't get player credentials and doesn't need them. The platform already guarantees that signed-out users are not let through, so your code should never contain its own login logic.

Every platform call must be removable in one pass

Put each platform call inside its own if (window.Yonest) check and wrap them in the comment markers below. The markers do nothing at runtime; they simply turn “removing platform features” into one verifiable deletion.

/* yonest:start */
if (window.Yonest) window.Yonest.submitScore(score);
if (window.Yonest) window.Yonest.gameOverActions(overlayEl);
/* yonest:end */

When you open this file outside the platform, window.Yonest doesn't exist, so these calls are blocked by the if and skipped silently, and the game runs as usual.

Minimal integration

The most typical integration point is “end of a run”: hand the score to the platform and add one more back entry point to your own game-over dialog. The code below can be copied straight into your existing game-over handler.

// Call when the round ends (overlayEl is your own results overlay)
function onGameOver(score, overlayEl) {
  /* yonest:start */
  if (window.Yonest) {
    if (window.Yonest.supportsLeaderboard) {
      window.Yonest.submitScore(score).then(function (r) {
        console.log(r.improved ? 'New record ' + r.best : 'Best ' + r.best);
      }).catch(function () { /* silently skip when not signed in / not acquired */ });
    }
    window.Yonest.gameOverActions(overlayEl);
  }
  /* yonest:end */
}

There is one more equally required integration point: registering the dictionary table (called once when the game initialises). Skip it and players who switch to English or German still see your source text.

// Call once at init: the dictionary table = every player-facing string in the game
/* yonest:start */
var yonestTable = [
  ['key',   'zh',    'en',     'de',   'fr',   'es',   'ru',   'ja',   'ko'  ],
  ['start', '开始',  'Play',   '',     '',     '',     '',     '',     ''    ],
  ['score', '分数',  'Score',  '',     '',     '',     '',     '',     ''    ],
];
function initYonestI18n(Yonest) {
  Yonest = Yonest || window.Yonest;
  if (!Yonest) {
    // not injected yet (the shell installs it after iframe load): queue it, it replays on install
    (window.YonestQueue = window.YonestQueue || []).push(initYonestI18n);
    return;
  }
  Yonest.i18n(yonestTable, 'zh');                          // an empty cell = not translated, falls back to the source language (zh)
  Yonest.applyI18n();                                      // translates data-i18n markers in the DOM
  document.documentElement.lang = Yonest.textLocale;       // the language actually rendered, NOT locale
}
/* yonest:end */
initYonestI18n();

Why the queue? The shell injects window.Yonest only after the game’s iframe has finished loading, so during your init code it usually does not exist yet — if (window.Yonest) then silently skips the registration, leaving the dictionary empty (the Maker Console marks every platform language as missing). Push the init call into window.YonestQueue as shown: the SDK replays it the moment it is installed, and anything pushed after install runs immediately.

In the header, list all of en de fr es ru ja ko zh at once (in the same order as Yonest.platformLocales); leave translations you are unsure about empty — an empty cell only falls back, it does not error. Registered languages show up under “Supported languages” on the game page.

Hand integration to an AI

Step 4 above (the dictionary table) is the easiest to miss — because it never errors, it just degrades silently: the game still runs, but players on other languages keep seeing your source text. The block below can be pasted as-is into your AI (Trae / Cursor / Claude, etc.), and it will build the dictionary table for you.

Following the Yonest SDK Guide, integrate this web game into the platform and complete the localisation in one pass:

1. Find every player-facing string in the game (buttons, prompts, results, tutorial, etc.) and put them into one dictionary table whose header lists all platform languages in order: ['key','zh','en','de','fr','es','ru','ja','ko'].
2. Call this once, when the game initialises:
   window.Yonest.i18n(dictionary, '<source language>');        // source language = the language your current strings are in
   window.Yonest.applyI18n();                                 // translates data-i18n markers in the DOM
   document.documentElement.lang = window.Yonest.textLocale;   // NOT locale
   Mark page strings with data-i18n="<key>", or look words up with window.Yonest.t('<key>').
3. Leave cells you are unsure about empty (they fall back to the source language, no error), but the header must list all of en de fr es ru ja ko zh.
4. Always wrap platform calls in if (window.Yonest) and in /* yonest:start */ … /* yonest:end */.
5. Final self-check: Yonest.missingLocales() should return an empty array; then tell me how to verify it on the platform.
6. Timing: the shell injects window.Yonest only after the iframe loads. If it is missing at init, push the setup call into window.YonestQueue — (window.YonestQueue = window.YonestQueue || []).push(fn) — so the SDK replays it on install.

Tip: the full list of languages the platform supports is in Yonest.platformLocales; you can also see the platform’s “missing X, Y translations” badge on the game’s card in the Maker Console.

API reference

Every method hangs off window.Yonest. Check that it exists before calling — this is the key to letting the game run in environments without the platform.

Environment and identity

Score reporting

window.Yonest.submitScore(1280).then(function (r) {
  // r = { ok: true, score: 1280, best: 1280, improved: true }
});

This member only exists when supportsLeaderboard is true. Check for it together before calling, e.g. if (window.Yonest && window.Yonest.supportsLeaderboard) { ... }; games without a leaderboard don't provide this method, and calling it directly throws a TypeError.

Shell and navigation

Back button in your game-over dialog

Languages and accounts

The SDK also provides multi-language and account support: the game ships all its translations in one dictionary table (the platform neither translates nor overrides them); player identity and a login credential are handed to your own backend for verification.

var table = [
  // ship the game's own dictionary table — row 0 declares the language of each column
  ['key',   'zh',   'en',    'de'],
  ['start', '开始', 'Play',  'Spielen'],
  ['score', '分数', 'Score', 'Punkte'],
];
function initYonestI18n(Yonest) {
  Yonest = Yonest || window.Yonest;
  // 2nd arg: source language. Not injected yet? Queue it — replayed on install.
  if (!Yonest) { (window.YonestQueue = window.YonestQueue || []).push(initYonestI18n); return; }
  Yonest.i18n(table, 'zh');
  Yonest.applyI18n();           // translates data-i18n markers in the DOM
  // use textLocale (NOT locale) for : it is the language actually rendered
  document.documentElement.lang = Yonest.textLocale;
}
initYonestI18n();

// hand a game-scoped token to your own backend for verification
// const { access_token } = await window.Yonest.getToken();

Errors and error codes

Every failure rejects with a YonestError: e.code is a stable code you can branch on, e.message is a localized sentence you can show as-is, and e.retryable tells you whether an identical retry makes sense. Never match on the message text — it is translated.

Domain codes are passed through unchanged, so e.code may be a value that is not in this table. When in doubt, branch on e.retryable and show e.message.

window.Yonest.submitScore(score).catch(function (e) {
  if (e.code === 'GAME_NOT_ACQUIRED') { showHint(); return; }
  if (e.retryable) { setTimeout(retry, (e.retryAfter || 5) * 1000); return; }
  console.warn(e.code, e.message);
});

Local mock and TypeScript types

/yonest-sdk-mock.js mirrors the SDK without the platform: it installs window.Yonest right away, keeps scores and tokens local, and records every call in YonestMock.calls. Use YonestMock.failNext(code) to exercise your error branches.

<script src="./yonest-sdk-mock.js"></script>
<script>
  YonestMock.configure({ leaderboard: true, player: { id: 'u1', name: 'Local', maker: false } });
  YonestMock.failNext('RATE_LIMITED');     // make the next async call fail on purpose
</script>

/yonest-sdk.d.ts is the typed contract: drop it into your project (or reference it) and window.Yonest, YonestError and window.YonestQueue become typed. Keep it in sync with the build you ship against.

Lifecycle and in-game events

Subscribe with Yonest.on(name, fn) / off(name, fn): pause and resume fire when the tab goes to the background; visibility carries { visible }; fullscreen carries { fullscreen } (forwarded by the shell); beforeLeave fires right before the game page unloads — use it for one last synchronous save.

Yonest.on('pause', pauseTimers);
Yonest.on('resume', resumeTimers);
Yonest.on('beforeLeave', function () { saveProgress(); });

In-game events: Yonest.track(name, result?) counts per game and per UTC day (result is an optional small bucket, e.g. a level id). Events are aggregated — no per-player rows, no free text. track never rejects; it resolves true/false to say whether the report was delivered.

You can download the counts as CSV from the game card in the Maker Console (date,event,result,count; last 30 days by default).

Cloud saves and achievements

Yonest.save.list() / get(key) / set(key, value) / remove(key) keep progress with the account. value is any JSON-serializable value; list() also returns the quota (maxKeys 20, maxBytes 32KB per entry).

// restore on start
Yonest.save.list().then(function (d) {
  var slot = d.saves.filter(function (s) { return s.key === 'main'; })[0];
  if (slot) state = JSON.parse(slot.value);
});

// save with optimistic locking
Yonest.save.set('main', state, { version: lastVersion })
  .then(function (r) { lastVersion = r.version; })
  .catch(function (e) { /* SAVE_CONFLICT: merge e.body.current, then retry */ });

Every failure is a YonestError: SAVE_QUOTA (no free keys), SAVE_TOO_LARGE, SAVE_KEY_INVALID. Pass the { version } you last read to enable optimistic locking — a mismatch rejects with SAVE_CONFLICT and e.body.current holds the stored value, so you can merge and retry.

Achievements: Yonest.achievement.unlock(id, name) is idempotent ({ first } tells you whether it was new, so you never show the same toast twice); list() returns what this player already unlocked. Both calls require a signed-in player.

Yonest.achievement.unlock('first_win', 'First win').then(function (r) {
  if (r.first) showToast('Achievement unlocked');
});

Leaderboard time windows need no extra work: submitting a score also feeds the daily and weekly boards, bucketed by UTC (daily = the UTC date, weekly = ISO week). The game page switches between all-time, today and this week.

Saves up to 32KB work for every game. Games with at least 200 distinct players in the last 30 days can also write big saves (1MB per entry, 50MB per game) — those come back from list() with backend: "r2" and value: null, so read them with save.get(key).

Adding translations after the platform adds a language

The languages the platform supports come from Yonest.platformLocales (currently en / de / fr / es / ru / ja / ko / zh). To see what your game is missing, run Yonest.missingLocales() inside the game, or read the missing-translation badge on the game's card in the Maker Console.

1. Add a column: in your Yonest.i18n([...]) dictionary table, add one column per missing language — the language code in row 0, then the translations below. Cells you are unsure about can stay empty; they fall back to the source language.
2. Change the version: bump it (e.g. 1.0.0 → 1.0.1). The update endpoint requires a different version and rejects an unchanged one.
3. Hand it back: open "Update game" on that game's card in the Maker Console, fill in the slug and the new version, pick the new file and click "Update". The slug does not change.
4. Re-check: enter the game again — Yonest.missingLocales() should return an empty array, and the game page's language list gains the new language.

Score reporting: rules and limits

A submitted score must satisfy all of the conditions below. If any one is unmet, the server returns an error instead of silently dropping it, so you can pinpoint issues while debugging.

Values are rounded to two decimal places. The leaderboard ranks scores from high to low and counts only each player's best score, so repeated submissions don't lengthen it; improved tells you whether this submission pushed the record higher.

Tell us when you need the leaderboard enabled and the platform will mark this game as integrated; games without it show no leaderboard entry and don't get submitScore.

Moving your game to another platform

There are three paths — pick whichever is easiest for your situation.

How to verify

Search the exported file for Yonest — the result should be 0. Then open it on its own: the game should start and finish normally, with no score notices or back buttons. The platform also returns two headers with the export, X-Yonest-Hooks-Original for the number of hook calls before stripping and X-Yonest-Hooks after; if the two numbers match, everything was removed.

If you want to own the shell yourself

The SDK depends entirely on the single global window.Yonest and has no other coupling. You can implement an object with the same name to take over its behavior — for example, point back() at your own page, or use an empty implementation on another platform so every call becomes a no-op.

FAQ

Will opening this HTML locally throw errors?

No. Every platform call is inside if (window.Yonest); when the object doesn't exist locally the calls are skipped, and the rest of the game is unaffected.

Why doesn't my game have window.Yonest.submitScore?

It means this game doesn't have the leaderboard enabled. back(), gameOverActions() and the like are still available, but submitScore doesn't exist and calling it directly throws; check window.Yonest.supportsLeaderboard first, then call.

Is submitting multiple scores in one run a problem?

It won't affect correctness, but each submission pops a notice in the top bar. For mid-run reporting, add { silent: true } and use the default behavior only at the real end.

Will the game-over button be inserted more than once?

No. gameOverActions() is idempotent and keeps only one button per container, so it's safe to put in every game-over path.

Will a failed submission interrupt my game?

No. Submission returns a Promise; as long as you add .catch() as shown, a failure is just a swallowed error and the game moves on to the next round. This covers cases like the player not having acquired the game or an expired session.

Will the SDK slow down loading?

It isn't added to your file and it isn't injected into your document.

Can I hide the top bar entirely?

You can collapse the secondary buttons (setChromeVisible(false)), but the back entry point is kept — this avoids leaving players with no way out. If your gameplay genuinely needs a full-screen area, tell us and we'll discuss the full-screen case.

Version and download

The SDK file is provided and loaded by the platform; you never need to put it into your own HTML. If you want a copy saved locally for debugging, you can download one from the Publish page.

If you hit problems during integration, write to hello@yonest.games, or leave a note via the Publish page.