Project Structure

The flat game folder Remix Desktop and the CLI work with, and the fields of remix.json.

A Remix project is a flat folder. There is no package.json, no node_modules, no bundler config and no vendored engine. The platform owns preview and compilation; the folder holds source, assets and agent context.

The Folder

game/
├── index.html              # the document the player frame loads
├── game-main.ts            # root entry module (Three.js projects)
├── remix.ts                # the game's own link to the Remix host
├── systems/
├── objects/
├── ui/
├── remix.json              # the project's declaration
├── remix-three.d.ts        # editor-only types entry point
├── tsconfig.json
├── assets/                 # images, models, audio, achievement icons
├── AGENTS.md               # context for coding agents
├── CLAUDE.md -> AGENTS.md
└── .remix/
    ├── panels/             # optional creator tools, self-contained HTML
    └── types/              # generated platform declarations

A folder is a Remix project when it has remix.json, index.html and game-main.ts. Remix Desktop gives an imported single-file HTML game this shape, and a single-file game you upload through the Studio or the HTTP API needs no folder at all.

Reference media with literal paths such as 'assets/ship.png'. Publish scans the built code for those strings and hosts each file; a path assembled at runtime is invisible to that scan and returns a 404 in production while working in preview.

remix.json

remix.json is the file the platform reads. Everything a game declares about itself lives here and is sent with every version.

{
  "name": "Harbor Sprint",
  "gameId": "2fd7f6fb-…",          // written on create; never edit
  "presentation": {
    "target": "mobile",            // "mobile" | "desktop"
    "orientation": "portrait",     // "portrait" | "landscape"
    "preferredAspectRatio": "16:9",// desktop only
    "input": ["touch"],            // "touch" | "keyboard" | "pointer"
    "compatibility": ["MOBILE"]    // optional; see below
  },
  "lifecycle": "scored",           // "scored" | "levels" | "custom" | "portal"
  "levelCount": 12,                // levels games only, 5 to 99
  "leaderboards": [ /* see Leaderboards */ ],
  "achievements": [ /* see Achievements */ ]
}

Field	Meaning
`name`	The display name, 5 to 25 characters and unique for your account.
`gameId`	The platform id, written by `remix create` or your first publish. Do not change it.
`presentation`	Which surface the game targets and how it is played. Omitted means mobile, portrait, touch.
`lifecycle`	The game type. `scored` (Arcade) calls `gameOver` with a score for the Remix leaderboard, `levels` reports an attempt per level, `custom` is any other style of game: it runs its own flow and never calls `gameOver`, and `portal` is a portal world. For a desktop game, Remix reads the type from the build each time it launches: a Custom game becomes Arcade or Levels by launching a build that uses that SDK, and an Arcade game whose build stops calling `gameOver` becomes Custom. Only Arcade and Levels games get Remix's built-in achievements (First Play and trophies); a Custom game declares its own. `open-ended`, Custom's former name, still works.
`levelCount`	Required with `lifecycle: "levels"`. The authored level total, 5 to 99. A launched game's count can grow but never shrink.
`leaderboards`	Named boards beside the main score. See Leaderboards.
`achievements`	Declared achievements and their icons; the game unlocks them. See Achievements.

Presentation and Compatibility

presentation.target decides where the game is listed. A mobile game plays on phones and on every other surface. A desktop game plays on Remix Desktop and on wide web windows, and is shown as a preview on phones. Games that predate the field are treated as mobile.

presentation.compatibility is optional and names the platforms directly: ["MOBILE", "DESKTOP"] lists a game on every surface, and ["LANDSCAPE"] marks a phone game played sideways, which orientation alone does not do. A game takes MOBILE or LANDSCAPE, never both. When you launch from Remix Desktop, the platforms you choose there apply instead.

The design box follows the target: portrait phone games compose for 720 by 1080, sideways phone games for 1080 by 720, and desktop games for a 16:9 frame of 1280 by 720. The real viewport is any size and can change mid-session, so read the viewport when you lay out, never once at boot.

AGENTS.md

AGENTS.md is read by coding agents working in the folder. The scaffolded one explains the host contract, the lifecycle rules and where to put things. Keep it current when you change how the project is organised; it is the cheapest way to make the next agent session productive.