# Reference

The agreed authoring and submission contract, plus the details that are not yet specified. This page is not a live MCP schema or proof of hosting compatibility.

## Required submission details

| Detail | Defined rule |
| --- | --- |
| Title | Plain text, 1–60 characters. Preserve spelling, capitalization and punctuation. Supply through MCP or ask if missing. |
| Playable build | One ZIP with `index.html` directly at its root. A self-contained game goes in the ZIP as `index.html`; a single `.html` file on its own can't carry the cover and is refused. |
| Cover image | Required for every build: exactly one `publishing/coverImage.webp` (or `.png` or `.jpg`) in the ZIP. AI-generated cover art, a designed SVG rendered to PNG or WebP, or a screenshot of the game; it must look like the real game and show the game's name in the image. Size and format are in [Build limits](#build-limits). See [Make a cover](docs-prepare.html#make-a-cover). |
| Project type | Exactly `Tech Demo`, `Short game` or `World`, describing the current playable experience. Browse labels are Tech Demos, Short Games and Worlds. Optional in `demo.json`, required before publishing. VR capability and Active are separate. See [the definitions](docs.html#know-the-vocabulary). Exact MCP parameter names remain unresolved. |
| Works on phones | Boolean `worksOnPhones`: `true` means the core experience is usable with phone layouts and touch controls; `false` means phone gameplay is unsupported. Optional in `demo.json`, but a valid answer is required before publishing without a default. Actual device-test evidence is separate. Capability does not release phone gameplay on the platform. |
| Active | Boolean `active`: the creator's explicit answer about developing, improving or expanding the project now. Optional in `demo.json`, but an explicit valid answer is required before publishing. No default or inference from recent activity. |
| Creation models | Public `creationModels` array of AI model names used to create the submitted build, including versions when known. Required for every published build, supplied through MCP or requested if missing; optional in `demo.json`. Keep testing-model attribution separate. |
| Engine | Required plain-text `engine`, naming the engine/framework used for this build. Unity, Godot, Three.js and HTML/JavaScript are examples only. Supply through MCP or ask if missing; optional in `demo.json`. |
| Version (optional) | Separate `engineVersion`, presented next to Engine. Include the actual engine/framework version when known; omit if unavailable. |

README and metadata files are optional; a cover image is required. Original-prompt disclosure is required only for the optional One Shot label. Descriptions, tags and controls are normally optional. When flashing/strobing effects are present, the uploading assistant adds the exact warning note to description as specified below; this is not an extra creator question. Do not turn them into new required creator steps. Required details can come from the creator or existing accurate information; a metadata file is not required.

## Build limits

| Measure | Defined rule |
| --- | --- |
| Total build size | Maximum 500 MB, meaning 500,000,000 bytes after ZIP extraction across all packaged files; for single HTML, measure that file. Compression does not increase the allowance. |
| Initial download | Aim for no more than 50 MB before usable core interaction on a fresh load, including external dependencies. Guidance only: exceeding it alone does not reject or hold a build. |
| File count | Maximum 1,500 individual files after extraction across all packaged files. A standalone HTML counts as one file; directories are not individual files. |
| ZIP transfer size | Maximum 550 MB (550,000,000 bytes) for the ZIP itself. Total extracted content still cannot exceed 500 MB. A standalone HTML remains capped at 500 MB. |
| Individual file size | No additional smaller per-file cap. One file may use the 500 MB allowance, provided all files combined remain within 500,000,000 bytes. File-type and safety checks still apply. |
| Cover image | Required. PNG, JPEG or WebP, landscape, at least 960 × 600 and at most 4096 px on each side, no more than 2 MB; 1600 × 1000 (16:10) recommended. A missing cover, or one outside these limits, is refused at upload with a [cover code](docs-publish.html#cover-codes). |
| Allowed extensions | Unresolved. Do not treat the packaging examples as a complete allowlist. |

## Metadata

MCP is the primary metadata route: the assistant supplies structured fields through the creator's authorised connection. `demo.json` is an optional portable copy; explicit publishing-request values take priority and valid packaged metadata fills gaps only. The keys below define file metadata; exact MCP parameter names remain unresolved.

| Key | Value | Requirement |
| --- | --- | --- |
| `name` | Plain-text public title, 1–60 characters. | Optional in `demo.json`; a valid title is required before publishing, supplied through MCP or requested if missing. |
| `engine` | Plain-text engine/framework name. Examples: Unity, Godot, Three.js, HTML/JavaScript. These are examples only, not an exhaustive list or allowlist. | Optional in `demo.json`; required before publishing, supplied through MCP or requested if missing. See [Engine and version](#engine-and-version). |
| `engineVersion` | Separate plain-text version of the engine/framework used for this build. Show next to Engine as Version (optional). | Optional. Include when known; omit if unavailable, without guessing or a default. |
| `type` | Exactly `Tech Demo`, `Short game` or `World`. | Optional in `demo.json`; a valid type is required before publishing, supplied through MCP or requested if missing without a guessed default. |
| `supportsVR` | Boolean: `true` declares immersive WebXR support; `false` declares no VR support. | Optional. Omission leaves support undeclared. Record actual headset inputs and tests separately. |
| `worksOnPhones` | Boolean: `true` means the core experience is usable with phone layouts and touch controls; `false` means phone gameplay is unsupported. | Optional in `demo.json`; a valid answer is required before publishing, supplied through MCP or requested if missing without a guessed default. |
| `active` | Boolean: `true` means the creator is currently developing, improving or expanding the project; `false` means they are not. | Optional in `demo.json`; an explicit valid creator answer is required before publishing. Reuse a valid answer already available or ask if missing. No default or inference from recent activity. |
| `shortDescription` | Plain text, 1–110 characters, for the one-line catalogue description. Describe what the player does or experiences in the current build. No HTML or formatting. | Optional. Omit if unavailable; it adds no required publishing question. |
| `description` | Plain text, 1–2,000 characters, for the fuller project-page description. Explain the current playable experience and what players can expect. Paragraph breaks are allowed; no HTML or rich formatting. | Normally optional. When flashing/strobing effects are present, the assistant includes the exact warning note below. No extra required creator question. |
| `tags` | Array of names from the fixed list below, for example `["Puzzle", "Calm"]`. Remove duplicates; ignore unknown values with MCP warnings while preserving valid tags. | Optional. Omit if unavailable; it adds no required publishing question. A numeric tag-count limit is not specified. |
| `controls` | Plain text, 1–1,000 characters, explaining actual controls for supported keyboard/mouse, touch, gamepad or headset inputs. Paragraph breaks are allowed; no HTML or rich formatting. | Optional. Omit if unavailable; it adds no required publishing question. Instructions do not establish capability or device-test evidence. |
| `supportedInputs` | Array containing only `keyboard`, `mouse`, `touch`, `gamepad`, `xrControllers` or `handTracking`. List implemented support only. Remove duplicates; ignore unknown values with MCP warnings while retaining valid values. | Optional. Omit if unavailable; it adds no required publishing question. VR, phone suitability and actual test evidence remain separate. |
| `credits` | Plain text, 1–2,000 characters, crediting contributors, assets, audio and tools as appropriate. Paragraph breaks are allowed; no HTML or rich formatting. Include only credits intended for public display. | Optional. Omit if unavailable; it adds no required publishing question. |
| `oneShot` | Boolean claim for this build: one creator prompt, with autonomous AI building, testing and fixes; no follow-up creator instructions or manual game-code changes. | Optional. The label requires the actual original prompt to be included and publicly disclosed with accurate creation-model information. False or omission does not apply the label. See [One Shot](#one-shot). |
| `originalPrompt` | Plain-text string containing the actual original creator prompt, preserved verbatim with its line breaks. Display as literal text. | Required and public for One Shot; optional otherwise. Optional in `demo.json`; a metadata file is not required. Never invent, rewrite or summarise the original. See [Original prompt](#original-prompt). |
| `creationModels` | Array of AI model names used to create the submitted build. Include versions when known; do not guess. Use `"Unknown"` for unavailable attribution, for example `["Unknown"]`. | Required and public for every published build. Optional in `demo.json`; supply through MCP or ask if missing. Keep the model that only tested the game separate. See [Creation models](#creation-models). |

```json
{
  "name": "Magnet Run",
  "engine": "HTML/JavaScript",
  "shortDescription": "Pull magnets into place and guide the ball to the exit.",
  "description": "Guide a ball through compact magnetic puzzles.\n\nExperiment with magnet placement to find a route to the exit.",
  "type": "Short game",
  "tags": ["Puzzle", "Calm"],
  "supportedInputs": ["mouse", "xrControllers"],
  "controls": "Mouse: drag magnets into position.\n\nVR: point at a magnet, hold the trigger and move it.",
  "credits": "Design and development: the project creator.",
  "supportsVR": true,
  "worksOnPhones": false,
  "active": true,
  "oneShot": false,
  "creationModels": ["Unknown"]
}
```

For `description`, `controls` and `credits`, represent paragraph breaks as `\n\n` inside the JSON string; show them as paragraph breaks when displaying the text.

`supportedInputs` names implemented input support; `controls` explains the actions. `xrControllers` means tracked XR controllers, and `handTracking` means tracked hands. Neither declares immersive VR by itself: `supportsVR` remains separate. Likewise, `touch` alone does not establish `worksOnPhones`. Keep actual device/headset tests separate from these declarations.

There is no `playTime` metadata field. If useful, mention duration naturally in `description`; do not invent an estimate. Cover images use the [publishing-folder convention](docs-prepare.html#publishing-assets), with no `coverImage` metadata field. Other metadata keys and exact MCP parameter names remain unresolved. Use only the documented file keys, and follow the actual published MCP schema when available. The example illustrates field syntax, including an explicit unknown-attribution value. Use actual known creation models whenever available, or `Unknown` when they cannot be established. Supply accurate values for the build, including the creator's explicit Active answer; the example does not establish One Shot eligibility.

`active` applies to all three types independently of VR and phone capability. A complete Short Game can remain Active for improvements or expansion. The badge is displayed only while `active` is `true` and the last build or update is less than 60 days old. Badge visibility is separate from the creator's saved answer; do not infer that answer from activity or from the badge.

`worksOnPhones` applies independently of type, Active and VR. Do not infer phone suitability from the engine, viewport width, touch detection or `supportsVR`. Record actual device tests separately, including devices and checks performed; this declaration does not certify every phone. Unknown suitability is not a default `false`: obtain a valid answer before publishing. Phone gameplay on the platform remains unreleased independently of this metadata.

Tech Demo covers a polished interactive idea, physics demonstrator, visually compelling or innovative experience; a loop is optional and it may omit features of a complete app or game. Short game is deliberately small but complete, with a playable loop, a menu and an ending. World is a coherent place to explore or inhabit, with usable UI and good UX; a conventional game loop or ending is optional. Any type can be in active development, including a complete Short Game being improved or expanded. The current build must already be polished and worthwhile. There is no separate In development type. Active and VR capability remain separate from type. A normal screen-based 3D scene does not establish immersive VR support, and declared `supportsVR` capability does not establish real-headset verification.

Explicit publishing-request values take priority. Valid packaged metadata fills gaps only. For example, if the explicit request title is Moon Runner and `demo.json` says Space Game, use Moon Runner. This precedence does not override security, playability or publication checks.

If the file cannot be read or parsed, skip its metadata import and report the problem. If readable metadata contains invalid or unknown optional values, ignore those values, retain usable fields and return clear MCP warnings naming the affected fields and reasons. The warning alone does not reject or hold a build. Required details and all normal package and gameplay checks still apply.

## Labels and optional details

Allowed `tags` values are Experience, Arcade, Puzzle, Racing, Platformer, Horror, Audio, Calm, Retro, Sim, Story and Toy. Supply them as an optional array using these names. Remove duplicates; ignore unknown values with an MCP warning and retain valid tags. Unknown values are not published as project tags. A numeric tag-count limit is not specified. One Shot is an optional build label and discovery filter. It is independent of project type and is not a guarantee of quality. See the [One Shot challenge](docs.html#one-shot-challenge).

### One Shot

One Shot means **one creator prompt**. The AI can build, test and fix autonomously; the creator provides no follow-up instructions or manual game-code changes. The first generated output does not have to work without fixes.

The labelled build **must include and publicly disclose the actual original creator prompt**, alongside accurate creation-model information. Never invent or rewrite an original prompt or infer eligibility from an engine or tool. Share only creator-approved public material; do not copy private chat histories. If the prompt/model disclosure is missing or cannot be shared, the build cannot receive the One Shot label. Other projects do not need original-prompt disclosure, but `creationModels` attribution is required for every published build.

The `oneShot` claim applies to the individual build. False or omission does not apply the label. Assess a later creator-directed revision for its own eligibility instead of inheriting an earlier claim. Normal packaging, quality and Docs-based testing requirements still apply.

Creation models are recorded in `creationModels` for every published build; the original prompt remains specific to One Shot. Exact MCP disclosure handoff mechanics are not yet defined. Do not mistake the testing LLM/model for the game's creation-model attribution.

#### Original prompt

`originalPrompt` contains the actual original creator prompt as a plain-text string. Preserve its wording, punctuation and line breaks verbatim. In JSON, encode line breaks as `\n`; display the decoded text with those line breaks preserved. Treat any markup in the prompt as literal text, not executable HTML.

The prompt is required and public for One Shot, optional otherwise. It may be supplied in optional `demo.json`; the metadata file itself is not compulsory. Explicit publishing-request values take priority over packaged metadata, and the selected value must still be the actual original prompt.

Use only the original prompt the creator intends to publish. Do not invent, rewrite, summarise or silently redact it and present the result as the original; do not copy private conversation history. If the actual original prompt is missing, invalid or cannot be shared publicly, the build cannot receive the One Shot label. That alone does not prevent ordinary publication when its normal requirements are met. Invalid optional values are ignored with an MCP warning, preserving other valid metadata.

### Engine and version

`engine` names the actual engine or framework used to create the submitted build. It is required before publishing, supplied by the assistant through MCP from accurate project/build information or requested if missing. Unity, Godot, Three.js and HTML/JavaScript are examples only, not a complete list or an engine-name allowlist.

`engineVersion` is a separate optional plain-text string. Present it next to Engine with the label **Version (optional)**. Include the actual engine/framework version used for the build when known; omit it if unavailable. Do not guess or substitute the latest version. The example above omits this optional field.

Both keys are optional in `demo.json`, because the file itself is optional; a valid engine answer is still required before publishing. Existing MCP-request-first precedence and invalid-optional-file-value warning/ignore rules apply. Naming an engine does not certify hosting compatibility or bypass normal package and gameplay checks. WebXR is a capability, separate from engine/version; `supportsVR`, headset inputs and real-device testing remain distinct.

### Creation models

`creationModels` is an array of the AI model names actually used to create the submitted build. It is required and public for every published build, whether or not the build is One Shot. Include model versions when known; do not guess names or versions from the editor, MCP client or engine.

The field is optional in `demo.json`, because the metadata file itself is optional. Reuse accurate information already available or obtain it through the publishing handoff; ask if missing, without a default. Explicit publishing-request values take priority over valid packaged metadata. Invalid optional file values are ignored with an MCP warning, but valid required creation-model information is still needed before publishing.

Keep this attribution separate from the testing LLM/model in the private TESTING section. A model used only to test is not a creation model. If the same model performed both roles, record it accurately in each place.

When the creation model cannot be established, include the exact string `Unknown`, for example `"creationModels": ["Unknown"]`. Keep known model names and versions if only part of the attribution is unknown, and use `Unknown` for the unknown remainder. Do not infer creation models from whichever assistant uploads or tests the build. Missing data or an empty array is not an explicit unknown answer.

`Unknown` is a valid recorded answer; it is not verified model identity or proof of One Shot eligibility. The normal One Shot disclosure and testing requirements still apply. Exact MCP wire/disclosure implementation remains unresolved.

### Publishing artwork

Every build needs one still cover image in `publishing/` at the ZIP root, with the stem `coverImage`, `cover-image` or `cover_image` and a PNG/JPEG/WebP extension. Discovery searches only this folder; generic `cover` files and other game assets are not imported automatically. Multiple recognised candidates are refused (`cover_ambiguous`) rather than guessed. No `coverImage` metadata field is defined. Follow [Publishing assets](docs-prepare.html#publishing-assets).

Accepted covers are AI-generated cover art, a designed SVG rendered to PNG or WebP, or a screenshot of the game. Whichever kind, the cover must look like the real game (its own characters, places and art style) and the game's name must appear in the image. Stay art-led and avoid a dominant background matching the site's `#171421`; avoid extra slogans, paragraphs and promotional labels. Size limits are in [Build limits](#build-limits); follow [Make a cover](docs-prepare.html#make-a-cover). The format and size rules are checked automatically at upload; the name and the likeness are checked by the reviewer.

### Flashing effects

When the build contains flashing or strobing effects, the uploading LLM should add this exact small note as a plain-text paragraph in the public `description`: "Warning: Contains Flashing lights". Preserve existing copy, add the note once and keep within the description limit. If there is no other description, the note can stand alone. Include it in the description actually submitted. Do not add it indiscriminately or treat its absence as a declaration that the build has no flashing effects. There is no `flashingLights` metadata field and no extra required publishing question.

## Hosting compatibility

The defined player uses a separate game domain and a sandboxed iframe. The production domain, exact headers, iframe permissions, network restrictions and browser/device compatibility matrix have not been published or verified. A local export pass does not prove hosted compatibility.

- **Assets:** use relative paths and bundle every dependency. During the private preview no outside host is allowed: scripts may load only from the game's own address, and the hosted check holds any build that requests another host. A shared-CDN allowlist may come later; none applies now.
- **Godot:** use the documented single-threaded Web baseline. Threaded or extension-enabled exports require additional isolation support; do not assume it is available.
- **Unity:** preserve export folders and filenames. Verify compression headers, content types or decompression fallback on the destination; automatic repair is not promised.
- **WebXR:** requires HTTPS, player-initiated entry and actual browser/host permissions. Verify hosted entry, headset inputs, exit/re-entry and desktop fallback independently. No headset/browser combination is certified by this preview.
- **Audio and storage:** begin audio through player interaction and handle unavailable browser storage gracefully. Do not assume persistent saves, cloud saves or a platform SDK.

Follow the version-specific sources linked in [Prepare and test](docs-prepare.html#export-by-engine).

## Testing confirmation

The uploading assistant generates the compact [TESTING section](docs-prepare.html#testing-confirmation) against the [Docs testing checklist](docs-prepare.html#test-the-final-package). It records the Docs-specific completion true/false, testing-instructions link/version, actual UTC test date/time, tester, environment and concise outcomes/notes. True means all applicable prescribed testing was completed and recorded; it does not mean bug-free or that all checks passed.

The defined handoff sends this section alongside the build through MCP, outside publicly served game files. Upload tooling is to attach the exact tested build identity/hash automatically. Exact wire keys/schema, transport/binding implementation and intake handling remain unspecified. Do not invent a demo.json key, compulsory package file or MCP argument. In the private preview the publisher helper's `finish_testing` tool carries it; without the helper, return the prepared section with the artifact and real computed hash.

## Unresolved contracts

The following details cannot yet be used as instructions:

- MCP server address, connection transport, authorization setup and verified client file handoff.
- Exact tools, input/output schemas, upload/status identifiers, status strings, retries and recovery mechanics.
- Remaining file metadata keys and exact MCP disclosure mechanics, archive protections and extension rules.
- Production hosting headers, permissions and verified device coverage, and any future allowlist of outside hosts (none applies in the private preview).
- Detailed validation coverage and measurable criteria, review response times, recovery and appeal procedures.
- Notification delivery details and creator visibility/recovery controls.

Until a contract is published and the relevant service is available, prepare what can be checked locally, retain the artifact and report the specific limitation. Do not fill gaps with invented defaults, endpoints or claims of support.

## Common questions

### Can an assistant publish just by reading this page?

No. It needs a working authorized MCP connection and access to the exact artifact. Publishing is a private preview for invited accounts through the local publisher helper.

### Do I need to pack source code or prompts?

Supply the production runtime build with its cover image; source code is not required. README and metadata files are optional. The optional One Shot label requires public disclosure of the actual original prompt through `originalPrompt`, alongside accurate creation-model information. Other projects do not need prompt disclosure. Only share material intended for public distribution.

### Does touch support mean the game is available on phones here?

No. Device capability and platform availability are different. Mobile Games is not publicly released. Phone browsing remains distinct from phone gameplay.

### Does a cosmetic suggestion prevent publication?

No. Style suggestions alone do not block or hold a build. Required security, functional gameplay and play-preventing UX/UI checks still apply.

### Does upload mean published?

No. Check the actual returned status. Publication confirmation and successful hosted play are separate evidence.