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.
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
| API | When 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 |
| multiplayer | Connect 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.
// 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.