game.json metadata reference

game.json is an optional file at the top level of a game's folder. It describes the game: its name, its text, its controls, its category and a few technical settings. The file is read by the platform and is never served to players.

Ground rules

• Every field is optional. A game with no game.json at all can still be published; the platform then fills in what it can from the game's page. See If a field is left out.
• Unknown fields are errors. A field name the platform does not recognise is rejected with a message naming it, so a typing mistake never passes silently.
• Wrong values are errors. A value of the wrong type, or outside its limits, is rejected with a message naming the field.
• The file must be valid JSON.
• Text is plain text. Text fields are shown exactly as written. HTML and Markdown in them are not interpreted. Spaces at the start and end are trimmed before lengths are checked.

Field reference

Field	Type	Required	Limits	Meaning
slug	string	No	2 to 60 characters; see Slug rules	The game's permanent identifier. It forms the page address and the name of the subdomain the game is served from.
title	string	No	1 to 80 characters	The game's name, shown everywhere the game appears.
tagline	string	No	Up to 120 characters	One line shown under the title, on the front page, in the release history and in search results.
description	string	No	Up to 1,200 characters	A few sentences shown on the game's page and on the front page. Also used for search-engine and link-preview descriptions.
instructions	string	No	Up to 2,000 characters	The "How to play" paragraph on the game's page.
controls	array of objects	No	Up to 16 entries; see Controls entries	The list shown in the "Controls" panel, grouped by input.
category	string	No	One of the fifteen category identifiers	The game's single category.
tags	array of strings	No	Up to 12 tags; each 1 to 24 characters, made of lowercase letters, digits and hyphens, and starting with a letter or digit	Short labels shown on the game's page. Each links to the list of games with that tag, and search matches them.
developer	string	No	Up to 80 characters	The credit shown on the game's page as "Made by".
releaseDate	string	No	A real calendar date written YYYY-MM-DD	The day the game is to be released, in the site's time zone. Each day holds one game.
draft	boolean	No	true or false	true holds the game back as a draft even though it passes validation.
entry	string	No	Up to 240 characters; must name a file in the folder	The entry HTML file, for when it cannot be detected.
themeColor	string	No	# followed by six hexadecimal digits, such as #101820	A colour associated with the game. It is stored with the game; the public pages currently take their colours from the game's category, not from this value.
orientation	string	No	any, landscape or portrait	The screen shape the game is made for.
inputs	array of strings	No	Up to 4 entries; each one of keyboard, mouse, touch, gamepad	The kinds of input the game supports, shown as "Plays with".
aspectRatio	string	No	Two numbers of one or two digits separated by a colon, such as 16:9	The shape of the player frame on the game's page.
permissions	object	No	See Permissions	Abilities the game needs inside its sandbox.
noteworthy	boolean	No	true or false	true marks the game as an editor's pick.

Tags are trimmed and converted to lower case before they are checked, so Pixel-Art is stored as pixel-art.

Three of these fields are editorial: releaseDate, draft and noteworthy. Release days and editor's picks are decided by the One Game a Day team, so a developer would normally leave them out.

Controls entries

Each entry in controls is an object with three fields, all required:

Field	Type	Limits	Meaning
input	string	One of keyboard, mouse, touch, gamepad	Which group the control is listed under.
keys	string	1 to 60 characters	The key, button or gesture, for example Arrow keys or Tap.
action	string	1 to 80 characters	What it does, for example Move.

On the game's page the entries are grouped in the order keyboard, mouse, touch, gamepad. Within a group they keep the order of the file.

Permissions

Every field of permissions is optional. An unknown field inside it is an error.

Field	Type	Limits	Meaning
network	array of strings	Up to 12 entries; each an https origin with no path, such as https://api.example.com	Other websites the game may load from and connect to.
pointerLock	boolean		Allows the game to capture the mouse pointer.
modals	boolean		Allows alert, confirm and prompt dialogs.
forms	boolean		Allows form submission.
downloads	boolean		Allows the game to offer a file download, such as a save file.
popups	boolean		Allows the game to open links in a new tab.

Write network origins without a trailing slash. Sandbox and permissions explains what each permission unlocks and which are granted automatically.

Category identifiers

Identifier	Shown as
action	Action
adventure	Adventure
arcade	Arcade
puzzle	Puzzle
strategy	Strategy
simulation	Simulation
sandbox	Sandbox
rhythm	Rhythm
shooter	Shooter
platformer	Platformer
racing	Racing
sports	Sports
rpg	RPG
card	Card & Board
casual	Casual

Slug rules

A slug must:

• Be 2 to 60 characters long.
• Use only lowercase letters a to z and digits 0 to 9, in groups separated by single hyphens. It cannot begin or end with a hyphen, and cannot contain two hyphens in a row.
• Not be one of the reserved words: admin, api, games, game, g, play, releases, category, categories, search, favorites, library, about, privacy, media, assets, static, new, index, sitemap, robots, www, mail, docs, status, cdn.

Choose the slug with care. It is the game's identity on the platform. A different slug is a different game, with a different address and separate saved data for players.

If a field is left out

Field	What the platform uses instead
slug	The folder's name, lower-cased, with every run of other characters turned into a hyphen.
title	The text of the page's title tag, up to the first dash, bar, colon or middle dot that has a space on each side. If the page has no title, the slug.
tagline	The rest of the page's title after that separator. Otherwise empty.
description	The page's description meta tag, or its og:description tag, with a leading repeat of the title removed. Otherwise empty.
instructions	Empty. The game's page has no "How to play" section.
controls	None. The game's page has no "Controls" panel.
category	A guess from words in the page's title and description. If nothing matches, arcade.
tags	A guess from words in the page's title and description, at most eight. Possibly none.
developer	Empty. The game's page has no "Made by" line.
releaseDate	Nothing is scheduled by the file. The team assigns a day.
draft	false.
entry	The entry file is detected; see Game package format.
themeColor	The page's theme-color meta tag, if it is a #rrggbb value. Otherwise none.
orientation	landscape if the entry page asks the browser to lock landscape or tells the player to rotate their device; portrait if it asks to lock portrait; otherwise any.
inputs	Detected from the event handling in the entry page.
aspectRatio	16:9.
permissions	No network origins. pointerLock, forms and downloads are switched on if the entry page uses them. modals and popups stay off.
noteworthy	false.

Automatic detection reads the entry HTML file only. A game whose code lives in separate script files should state inputs, orientation and any permissions it needs explicitly.

Guesses are a fallback, not a substitute. A game presents best when its game.json gives at least title, tagline, description, instructions, controls, category, tags and inputs.

How the fields are used

• Orientation. A landscape game shows "Best on: Wide screens (landscape)" on its page, asks phone players holding the device upright to turn it, and requests a landscape lock in full screen. A portrait game shows "Best on: Tall screens (portrait)" and nothing more.
• Aspect ratio. The player frame takes this shape on the game's page, limited by the height of the window. In full screen and in the full-window phone view the frame fills the available space whatever the ratio, so a game must still cope with other shapes.
• Inputs. The first three are also shown as chips beside the game when it is featured on the front page.

A real example

This is the metadata supplied with the launch game Void Drifter:

{
  "slug": "void-drifter",
  "title": "Void Drifter",
  "tagline": "The Last Survivor",
  "description": "A space roguelite about staying alive one more minute. Pilot the last ship through waves of hostile drones, harvest glowing crystals to evolve your hull mid-run, and dash through the gaps the swarm leaves behind. Every run reshapes your build.",
  "instructions": "Keep moving, keep collecting. Crystals dropped by destroyed enemies evolve your ship — pick upgrades that fit how you fly. Dash is your escape: save it for when the swarm closes in. Losing focus pauses combat, and auto-aim can be switched on in Settings for keyboard-only play.",
  "category": "shooter",
  "tags": ["roguelite", "space", "survival", "single-player", "offline"],
  "controls": [
    { "input": "keyboard", "keys": "W A S D / Arrow keys", "action": "Move" },
    { "input": "mouse", "keys": "Move the pointer", "action": "Aim (firing is automatic)" },
    { "input": "keyboard", "keys": "Space", "action": "Dash" },
    { "input": "touch", "keys": "Left joystick", "action": "Move" },
    { "input": "touch", "keys": "DASH button", "action": "Dash" }
  ],
  "inputs": ["keyboard", "mouse", "touch"],
  "releaseDate": "2026-10-08"
}

An example with every field

This invented example uses every field the schema accepts, each with a valid value. Most games need far fewer.

{
  "slug": "lantern-run",
  "title": "Lantern Run",
  "tagline": "Keep the light alive",
  "description": "A side-scrolling platformer about carrying one lantern through a cave that is slowly going dark. Jump between ledges, relight the braziers and reach the surface before the flame goes out.",
  "instructions": "Run and jump to the right. Touch a brazier to relight your lantern and set a checkpoint. If the flame goes out you return to the last brazier you lit.",
  "controls": [
    { "input": "keyboard", "keys": "Arrow keys", "action": "Run" },
    { "input": "keyboard", "keys": "Space", "action": "Jump" },
    { "input": "touch", "keys": "Left and right buttons", "action": "Run" },
    { "input": "touch", "keys": "Tap the right side", "action": "Jump" },
    { "input": "gamepad", "keys": "Left stick, A button", "action": "Run and jump" }
  ],
  "category": "platformer",
  "tags": ["pixel-art", "single-player", "offline"],
  "developer": "Example Studio",
  "releaseDate": "2026-11-03",
  "draft": false,
  "entry": "index.html",
  "themeColor": "#101820",
  "orientation": "landscape",
  "inputs": ["keyboard", "touch", "gamepad"],
  "aspectRatio": "16:9",
  "permissions": {
    "network": ["https://api.example.com"],
    "pointerLock": false,
    "modals": false,
    "forms": false,
    "downloads": false,
    "popups": false
  },
  "noteworthy": false
}

Later changes

The details in game.json are applied when a game is imported. If the team afterwards edits a game's details on the site, those edits are kept: a later game.json no longer overwrites them. See Publishing workflow.