GAME CREATOR

owogg.json specification

Manifest v1 required fields, accepted values, and localization, result, and ranking contracts based on the live validator.

Open the Manifest v1 JSON SchemaUse it for editor completion and field validation before submission.

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.

json
{
  "$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

  1. 1Add $schema and numeric schemaVersion 1, then settle game.slug, title, and genre first.
  2. 2Choose game.mode and game.playModes to match real gameplay. Do not add multiplayer for a local-only game.
  3. 3Use progression.type: none when there is no progression, and start with result.score: null when there is no score.
  4. 4Add only the input, presentation, and in-game difficulties that the build actually supports.
  5. 5Declare metrics and events that the game really sends before referencing those facts from achievements.
  6. 6Add leaderboard, playConfig, or multiplayer only when the required trust model and operational review are ready.
  7. 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

FieldRequiredRule
$schemaOptionalIf present: https://owogg.com/schemas/manifest/v1.json
schemaVersionYesNumber 1
gameYesIdentity, display metadata, and play topology
progressionYesProgression type and optional range
resultYesThe score key must exist; use null when there is no score
input / presentationOptionalInput devices and screen preferences
difficulties / events / achievementsOptionalDifficulty and validated facts
leaderboard / playConfigOptionalRanking and trusted verifier integration
multiplayerOptionalExact-version online runtime review request

game fields

FieldRule
slug3–64 lowercase letters, digits, or hyphens; permanent after registration
title1–60 character default English title
shortDescriptionOptional default English summary, up to 200 characters
localizationsOptional ko, ja, and zh title or shortDescription overrides
genreA non-empty, free-form broad genre
tagsOptional, unique, up to 20; 40 characters each
modesingle or multi
playModesRequired array: single, local-multi, online-multi
descriptionOptional string up to 4,000 characters or fixed Markdown file array
description_imagesOptional, up to 5 raster images in the bundle
Keep mode and playModes consistent. mode: single requires exactly ["single"]. mode: multi must include local-multi or online-multi.

How to use optional fields

FieldWhen and how to write it
inputDeclare only the keyboard, mouse, touch, and gamepad inputs you really handle, without duplicates
presentationorientation (any|landscape|portrait), integer aspectRatio, and initial defaultMode (default|theater)
difficultiesUnique IDs and titles selectable inside the game, with at most one default
eventsKeys passed to event(name), with an optional positive maxPerAttempt
achievementsSession or lifetime conditions that reference only declared score, outcome, progression, metric, or event facts
leaderboardSet enabled: true only when a valid score exists and server-approved scores should be ranked
playConfigUse only with a registered trusted verifier and allowed difficulty/variant combinations
multiplayerA 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.
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 }
});

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.

json
{
  "$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.

Most casual games can start without playConfig. Coordinate a verifier contract with the OwOGG team when competitive results must be reproduced and checked by the server.

Continue reading