GAME CREATOR
owogg.json specification
Manifest v1 required fields, accepted values, and localization, result, and ranking contracts based on the live validator.
Minimal example
Manifest v1 is the only public schema. Unknown fields are rejected, so do not mix in keys from older guides or private extensions.
{
"$schema": "https://owogg.com/schemas/manifest/v1.json",
"schemaVersion": 1,
"game": {
"slug": "my-game",
"title": "My Game",
"shortDescription": "A short English summary.",
"localizations": {
"ko": { "title": "내 게임", "shortDescription": "한국어 한 줄 소개" },
"ja": { "title": "マイゲーム" },
"zh": { "title": "我的游戏" }
},
"genre": "arcade",
"tags": ["casual", "puzzle"],
"mode": "single",
"playModes": ["single"],
"description": ["description.md", "description_kr.md"]
},
"input": ["mouse", "touch", "keyboard"],
"presentation": {
"orientation": "any",
"aspectRatio": "16:9",
"defaultMode": "default"
},
"progression": { "type": "none" },
"result": { "score": null },
"leaderboard": { "enabled": false }
}Recommended writing order
- 1Add $schema and numeric schemaVersion 1, then settle game.slug, title, and genre first.
- 2Choose game.mode and game.playModes to match real gameplay. Do not add multiplayer for a local-only game.
- 3Use progression.type: none when there is no progression, and start with result.score: null when there is no score.
- 4Add only the input, presentation, and in-game difficulties that the build actually supports.
- 5Declare metrics and events that the game really sends before referencing those facts from achievements.
- 6Add leaderboard, playConfig, or multiplayer only when the required trust model and operational review are ready.
- 7Check JSON syntax, use the public schema for completion, then upload the exact release ZIP and fix errors from the first MANIFEST_INVALID path onward.
Top-level fields
| Field | Required | Rule |
|---|---|---|
| $schema | Optional | If present: https://owogg.com/schemas/manifest/v1.json |
| schemaVersion | Yes | Number 1 |
| game | Yes | Identity, display metadata, and play topology |
| progression | Yes | Progression type and optional range |
| result | Yes | The score key must exist; use null when there is no score |
| input / presentation | Optional | Input devices and screen preferences |
| difficulties / events / achievements | Optional | Difficulty and validated facts |
| leaderboard / playConfig | Optional | Ranking and trusted verifier integration |
| multiplayer | Optional | Exact-version online runtime review request |
game fields
| Field | Rule |
|---|---|
| slug | 3–64 lowercase letters, digits, or hyphens; permanent after registration |
| title | 1–60 character default English title |
| shortDescription | Optional default English summary, up to 200 characters |
| localizations | Optional ko, ja, and zh title or shortDescription overrides |
| genre | A non-empty, free-form broad genre |
| tags | Optional, unique, up to 20; 40 characters each |
| mode | single or multi |
| playModes | Required array: single, local-multi, online-multi |
| description | Optional string up to 4,000 characters or fixed Markdown file array |
| description_images | Optional, up to 5 raster images in the bundle |
How to use optional fields
| Field | When and how to write it |
|---|---|
| input | Declare only the keyboard, mouse, touch, and gamepad inputs you really handle, without duplicates |
| presentation | orientation (any|landscape|portrait), integer aspectRatio, and initial defaultMode (default|theater) |
| difficulties | Unique IDs and titles selectable inside the game, with at most one default |
| events | Keys passed to event(name), with an optional positive maxPerAttempt |
| achievements | Session or lifetime conditions that reference only declared score, outcome, progression, metric, or event facts |
| leaderboard | Set enabled: true only when a valid score exists and server-approved scores should be ranked |
| playConfig | Use only with a registered trusted verifier and allowed difficulty/variant combinations |
| multiplayer | A Relay review request for an exact online-multi version; never needed for local play |
Progression and results
- progression.type: none, endless, stage, level, round, wave, chapter, lap, or custom
- A range requires min < max; outOfRange is clamp by default or reject.
- result.score is null or contains unit, direction (asc|desc), precision (0–6), and range.
- leaderboard.enabled cannot be true when score is null.
- Declare only the outcome values you return: neutral, success, failure, win, loss, draw.
- Metric and event keys use restricted identifiers starting with a letter and must match complete/event payloads.
// 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 }
});Complete scored, event, and achievement example
This valid example combines difficulty, progression, score, a metric, an event, session and lifetime achievements, and a leaderboard. Replace the IDs and ranges with values the game logic can actually produce.
{
"$schema": "https://owogg.com/schemas/manifest/v1.json",
"schemaVersion": 1,
"game": {
"slug": "target-rush",
"title": "Target Rush",
"genre": "skill-test",
"mode": "single",
"playModes": ["single"]
},
"input": ["mouse", "touch"],
"presentation": {
"orientation": "any",
"aspectRatio": "16:9",
"defaultMode": "default"
},
"difficulties": [
{ "id": "normal", "title": "Normal", "default": true },
{ "id": "hard", "title": "Hard" }
],
"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": 100001, "outOfRange": "reject" }
},
"metrics": {
"targetsHit": {
"type": "integer",
"range": { "min": 0, "max": 1001, "outOfRange": "reject" }
}
}
},
"leaderboard": { "enabled": true },
"events": { "bossDefeated": { "maxPerAttempt": 1 } },
"achievements": [
{
"id": "first-clear",
"title": "First Clear",
"scope": "session",
"condition": { "source": "outcome", "operator": "==", "value": "success" }
},
{
"id": "boss-hunter",
"title": "Boss Hunter",
"scope": "lifetime",
"condition": {
"source": "event",
"key": "bossDefeated",
"aggregate": "count",
"operator": ">=",
"value": 10
}
}
]
}Difficulties, achievements, and PlayConfig
difficulties must be a non-empty array with unique IDs and at most one default. If no default is marked, the first difficulty becomes the default.
A regular game renders these choices inside its own UI and uses difficulty / selectDifficulty() before starting to bind the choice to the Host session and leaderboard. The outer player UI does not render a difficulty selector.
Achievements may reference only declared score, outcome, progression, metric, or event facts. Lifetime numeric conditions require a max, min, sum, or count aggregate.
playConfig is an advanced feature paired with a trusted verifier already installed on the server. Writing a verifierId in the manifest does not install server code or create authoritative scoring.