GAME CREATOR

Host API and result integration

Connect readiness, start, events, completion, and restart through the injected window.OWOGG API.

Basic lifecycle

The Host injects window.OWOGG when the game runs inside OwOGG. Await whenReady(), call start() when real play begins, and call complete() once when the attempt ends.

A regular game that declares difficulties builds its in-game selector from difficulty, awaits selectDifficulty(id), and calls start() only after approval. playConfig and requestStart() are reserved for trusted-verifier games.

js
const api = window.OWOGG;

await api.whenReady();

async function beginGame(selectedDifficultyId) {
  const difficultyId = api.difficulty
    ? await api.selectDifficulty(selectedDifficultyId ?? api.difficulty.defaultLevelId)
    : "normal";
  resetGameState({ difficultyId });
  api.start();
}

function finishGame(score) {
  api.complete({
    outcome: "success",
    score,
    progression: { value: 7 },
    metrics: { targetsHit: 20 }
  });
}

retryButton.addEventListener("click", () => api.restart());
cancelButton.addEventListener("click", () => api.cancel());

API summary

APIWhen to use it
whenReady()Wait for Host bootstrap and public configuration
difficulty / selectDifficulty()Render regular-game difficulty inside the game and bind it to the generic session and leaderboard
start()Begin the actual attempt
event(name, data?)Send a bounded event declared in the manifest
complete(result?)Send final outcome, score, progression, and metrics
restart()Ask for a new Host-owned attempt from the in-game retry button
cancel()Cancel the current attempt by explicit user action
playModes / selectPlayMode()Choose an allowed topology in a hybrid game
playConfig / requestStart()Request an approved config and seed for a verifier-backed game
multiplayerConnect to an approved online-multi Relay profile

Result payload

complete() should contain only facts declared by the manifest. Score, progression.value, and metric values must be finite numbers and pass their range policies. Undeclared outcomes, metrics, and events may be rejected.

js
// owogg.json
"progression": {
  "type": "round",
  "range": { "min": 0, "max": 11, "outOfRange": "reject" }
},
"result": {
  "outcome": { "values": ["success", "failure"] },
  "score": {
    "unit": "points",
    "direction": "desc",
    "precision": 0,
    "range": { "min": 0, "max": 100000, "outOfRange": "reject" }
  },
  "metrics": {
    "targetsHit": {
      "type": "integer",
      "range": { "min": 0, "max": 1000, "outOfRange": "reject" }
    }
  }
}

// game.js
window.OWOGG.complete({
  outcome: "success",
  score: 12500,
  progression: { value: 7 },
  metrics: { targetsHit: 20 }
});

Restart and local testing

  • The ZIP owns its retry button and game-state reset.
  • Inside OwOGG, restart() requests a fresh play session and iframe remount.
  • window.OWOGG may be absent in a standalone local run. A development fallback may keep core gameplay testable, but it must never fake a production result submission.
  • Provide Korean and English switching for all core instructions, settings, progress, results, and accessibility labels.

Security boundaries handled by the Host

The OwOGG Web Host now handles protected activity reporting automatically. It obtains a short-lived activity proof bound to the slug and attempt ID and uses it for STARTED, LOADED, COMPLETED, and CLIENT_ERROR events without exposing the proof, session token, or user ID to the game iframe.

Issuing a proof does not write a D1 row, and duplicate lifecycle events for the same attempt do not keep adding rows. Do not call this endpoint or store proofs in the game; implement only the window.OWOGG lifecycle accurately.

  • If the Host or API fails, show a retry state instead of bypassing it with parallel fetches or an infinite loop.
  • Never put direct API URLs, cookies, tokens, or fabricated attempt IDs in the game ZIP.

Score trust

Iframe isolation does not make a score truthful. Generic browser scores are checked against a signed one-use session and manifest ranges, but the calculation still happens on the client. High-value competition needs PlayConfig plus a trusted verifier or a server-authoritative multiplayer design.

Continue reading