> ## Documentation Index > Fetch the complete documentation index at: https://docs.opengame.io/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Upload a browser game and get a private preview link that only you can open. Deploy your game folder to a private preview, where only you can play it as OpenGame hosts it. The creator platform is internal-only for now, so you need an invitation from the OpenGame team. ## Before you start Get these from the person who invited you: * An account with internal access. * The CLI and SDK tarballs, `opengamehq-cli-.tgz` and `opengamehq-sdk-.tgz`. * Your origin: the `https://` address the CLI signs in and uploads to. It is not opengame.io, which serves the agent guide but doesn't take uploads yet. * A starter folder, if you want a starter and don't have the OpenGame repository. You also need: * Node.js 20.19, or 22.12 or later, for a starter, because that is Vite 7's floor. A game you bring needs only the CLI's floor, Node.js 18.17. Run `node --version` to check. * A game with `index.html` in its build output, or a starter from the next section. ### No game yet? Copy a starter A starter is a small game with `opengame.json` and the SDK already set up. Pick `three-vite`, `phaser`, `react` or `javascript`. With no preference, pick `three-vite`, a game called Orb Run; the others share the placeholder title Target practice. Use the install blocks below. They replace the starter's repository-only SDK path with the tarball you downloaded. A plain `npm install` leaves the SDK missing without an error. > [tab] From the repository > > The starters are in the repository's `templates` folder. Change the first four lines before you paste the block: `REPO` is your copy of the repository, `TARBALLS` is the folder you saved the tarballs in, `STARTER` is the starter you picked, and `GAME` is a new folder for your game, which must not exist yet. > > ```bash theme={"system"} > REPO=~/opengame > TARBALLS=~/Downloads > STARTER=phaser > GAME=~/my-game > cd "$REPO/templates" && > cd "$STARTER" && > mkdir "$GAME" && > cp -R . "$GAME" && > cd "$GAME" && > npm install "$TARBALLS"/opengamehq-sdk-*[0-9].tgz > ``` > > Each line runs only if the one before it worked. A wrong `REPO` or `STARTER`, or an existing `GAME`, stops the block before anything is copied or installed. If only the last line fails, [If a command fails](#if-a-command-fails) covers it. > [tab] From a starter folder > > Move the folder the team sent you to where you want your game. Set `GAME` to that folder and `TARBALLS` to the folder you saved the tarballs in, then paste the block. > > ```bash theme={"system"} > GAME=~/my-game > TARBALLS=~/Downloads > cd "$GAME" && > npm install "$TARBALLS"/opengamehq-sdk-*[0-9].tgz > ``` The `*[0-9].tgz` pattern skips a duplicate download such as `opengamehq-sdk-0.1.0 (1).tgz`. If you saved more than one version, use the newest file's full name. npm saves the tarball's path relative to the game folder, so if you move either one, run the `npm install` line again. For other engines, [Engine support](https://docs.opengame.io/engines/overview.md) links each engine's guide, which names its starter or export recipe. ## Create your preview Pick how you want to work. Both end with the same private preview. > [tab] With an agent > > Open your game folder in Claude Code, Codex, Cursor or any coding agent that can run commands, and paste this prompt: > > ```text wrap theme={"system"} > Deploy this game to OpenGame as a private preview. > 1. If the CLI is missing or out of date, ask me for the internal CLI tarball. > 2. Read https://opengame.io/for-agents.md, then follow the AGENTS.md in that CLI package. > 3. Ask me for the internal OpenGame origin. > 4. Sign in only with my approval. > 5. Fix confirmed game findings. > 6. Give me the private preview link. > Submit only if I ask. > ``` > > The agent asks for the CLI tarball and your origin. The prompt on your origin's `/upload` page has both filled in, so you can paste that one instead. > > When the agent signs you in, it gives you a link and a code in two groups of four, such as `KTWQ-7MHP`. Open the link, type the code, then press **Allow access**, which stays greyed out until the code matches. > > You're done when the agent gives you a preview link. Open it while signed in to the same account. The [agent guide](https://docs.opengame.io/for-agents.md) is what the agent follows. > [tab] In your terminal > > **1. Install the CLI** > > Paste this block. If you saved the tarballs somewhere other than Downloads, change the first line. Delete any older `opengamehq-cli` tarball first, or npm installs both. > > ```bash theme={"system"} > cd ~/Downloads && > npm install -g opengamehq-cli-*[0-9].tgz > ``` > > Then run `opengame version`. It prints `opengame` and the version in the tarball's file name, such as `opengame 0.3.1`. If npm stops with `EACCES`, see [If a command fails](#if-a-command-fails). > > **2. Point it at your origin** > > Replace `https://your-origin` with the origin the team gave you. The setting lasts until you close this terminal, so to keep it, add the line to `~/.zshrc` or `~/.bashrc` too. > > ```bash theme={"system"} > export OPENGAME_API_URL=https://your-origin > ``` > > Without it, the CLI talks to opengame.io, which doesn't take uploads yet. > > **3. Describe your game** > > Run this step and the ones after it from your game folder. > > **If you copied a starter,** skip `init`: the starter already has `opengame.json`. Open it and change `title` and `description` to your game's. > > **If you brought your own game,** run: > > ```bash theme={"system"} > opengame init . > ``` > > `init` reads the title from `index.html` and the build command from `package.json`. Before it writes anything, it may ask a few things. To skip the questions, give the answers in the command: add `--description "…"`, `--genre ` and `--kind `. > > * **A description,** when `package.json` has no description of 40 to 500 characters. Press Enter to skip. > * **A genre,** from a menu, when it can't guess one from the title and description. Move with the arrow keys and pick with Enter. **Decide later** is already highlighted, so Enter skips it. > * **What you are making:** a game, a world, a decomp or a mod, each with a line that says what it means. **Game** is already highlighted, so Enter makes a game. Use the arrow keys to pick another. > * **Which game it is based on,** for a decomp or a mod, such as `Doom`. You can't skip this one, because a mod has to say what it changes. In the command, that is `--kind mod --based-on "Doom"`. > > Then it writes `opengame.json`. If a field is still missing or invalid, it prints `Created a draft opengame.json.` and names the field. Open the file and check three fields: > > * `description`: 40 characters or more on what the game is and how it plays. > * `genre`: if it is wrong, `opengame check` lists the valid slugs. > * `build.output`: the folder your build writes `index.html` into, such as `dist`. > > **4. Try it locally (optional)** > > ```bash theme={"system"} > opengame dev . --build > ``` > > This builds the game and serves it at a local address with the same headers it gets on OpenGame. Open the address it prints. If the game includes an SDK, platform services run as a local mock, so you send no data to OpenGame here. The starters include the SDK package, and a copy of `opengame-global.js` works the same way. `opengame dev` adds no SDK, so a game without one has no `window.OpenGame` here. Press Ctrl+C to stop. > > To find problems before you upload, run the local checks on their own. OpenGame's checks still run when you deploy. > > ```bash theme={"system"} > opengame check . --build > ``` > > **5. Deploy** > > ```bash theme={"system"} > opengame deploy . > ``` > > Deploy builds the game, checks it and uploads it, up to 200 MiB zipped (see [the limits](https://docs.opengame.io/reference/limits.md#package-your-bundle)). The first time, it signs you in: a page opens in your browser, or use the link it prints. Type the code the terminal shows, and press **Allow access**. Once the upload is in, it prints the address of your deploy's page and returns, while OpenGame's checks run. The page shows each check as it runs, and Play once the preview is ready. To wait in the terminal instead, run `opengame deploy . --wait`. > > **6. Play the preview** > > Open Play on your deploy's page, signed in to the same account, or run `opengame open`. > > The link has no expiry of its own. It keeps working while the release is one of your game's 10 newest, and each visit starts a preview session that lasts 1 day. Check that the game loads, the controls work, it resizes and the sound plays. ## If a command fails Find the message the CLI or npm printed, open its entry, and do what it says. Most entries start with the code that `--json` output reports for that error. The last two have no single code, because they cover any finding about your game and any check that failed on OpenGame's side. The [repair guide](https://docs.opengame.io/guides/repair-loop.md) covers every finding and exit code, and [For agents](https://docs.opengame.io/for-agents.md) covers `--json` for scripts. > [accordion] npm error code EACCES > > `npm install -g` couldn't write to npm's global folder, because your system owns that folder, not you. The CLI was not installed. Don't rerun it with `sudo`. Give npm a global folder you own: > > ```bash theme={"system"} > mkdir -p ~/.npm-global > npm config set prefix ~/.npm-global > export PATH=~/.npm-global/bin:$PATH > ``` > > `npm config set` is saved for later shells, and the `export` command is not. Add the `export` command to `~/.zshrc` or `~/.bashrc` too, so new shells find `opengame`. > > Then install the CLI again, changing the first line if you saved the tarballs somewhere other than Downloads: > > ```bash theme={"system"} > cd ~/Downloads && > npm install -g opengamehq-cli-*[0-9].tgz > ``` > [accordion] no matches found, or npm fails with ENOENT > > The SDK install couldn't find the tarball, because `TARBALLS` isn't the folder you saved it in. zsh prints `no matches found`. In bash, npm warns that the file `seems to be corrupted`, then exits with `ENOENT`. The starter is already copied and you are in the new folder, so don't paste the block again: set `TARBALLS` to the right folder and run the `npm install` line on its own. > [accordion] The OpenGame API is not available at an address > > `api_unavailable`. If the address is `https://opengame.io`, this shell has no `OPENGAME_API_URL`, so the CLI used opengame.io, which doesn't take uploads. Set it as in the terminal tab's second step, then run the command again. If the message names your origin instead, check the address with the team. > [accordion] Could not reach the OpenGame API at an address > > `network`. The same fix applies when the CLI prints `The OpenGame API at` and an address, then `sent an answer this CLI could not read`. The CLI got no answer from the address it names, or got a page it couldn't read, such as a proxy's sign-in page. Most often that address is wrong: a typo, or `https://your-origin` from the terminal tab's second step pasted as written. Run `echo "$OPENGAME_API_URL"`, compare it with the origin the team gave you, and set it again. If the address is right, check that you are online, and that `HTTPS_PROXY` is set if your network needs a proxy. Then run the command again. > [accordion] Run opengame login, or supply OPENGAME\_TOKEN > > `not_signed_in`. You aren't signed in on this machine. Run `opengame login`, open the link it prints, type the code it shows and press **Allow access**. > [accordion] Claim a handle on OpenGame, then try again > > `handle_required`. The account you signed in with has no handle yet, and every account that uses the CLI needs one. Claim it at opengame.io/handle, then run the command again. > [accordion] Uploads are not open yet > > `uploads_closed`. Signing in, previewing and reading your games all work, but OpenGame isn't taking new uploads yet. Nothing was uploaded. The message names the day uploads open when there is one; run the command again then. > [accordion] opengame.json already exists > > `manifest_exists`. The folder already has a manifest, as every starter does, so `init` left it alone. Skip `init` and edit `opengame.json` to change the game's details, or run `opengame pull` to get changes made on the website. > [accordion] The checks are still running > > `checks_pending`. `deploy --wait` or `status --watch` stopped waiting after 5 minutes. Your upload is safe and OpenGame's checks carry on. Open your deploy's page, or run `opengame status --watch` to follow them. > [accordion] The upload did not finish > > `upload_interrupted`. The connection dropped on every try. Your saved upload can be resumed. Keep the `.opengame/` folder, check your connection and run `opengame deploy .` again. It resumes the same upload, or starts a fresh one if the old one has expired. > [accordion] A finding about your game > > Something in the build needs a change. Each finding names the problem, usually with a file and line, and the fix. Make the change, run `opengame check . --build`, then deploy again. > [accordion] A check failed on OpenGame's side > > The problem is ours, and your game is fine, so don't change it. Wait a few minutes, then run the command the error names, or the same command again. ## Submit for review When the preview plays the way you want, run `opengame submit` from the game folder. Each deploy makes a new release, and `submit` takes the newest one once its checks have finished and it is ready. If that release isn't ready, `submit` stops and names the command to run. Otherwise it asks you to confirm the release, then for any jam details. The first time you submit a game, you certify in your browser that you have the rights to everything in it. A reviewer then plays it and approves it or asks for changes. The game becomes public when the reviewer approves and publishes it. [Enter a jam](https://docs.opengame.io/guides/jams.md) covers tracks, rules and following the review. ## Keep building > [card] [Package your game](https://docs.opengame.io/guides/packaging.md) > > What goes in the folder and the manifest, and the upload limits. > [card] [Connect the SDK](https://docs.opengame.io/guides/identity.md) > > Read the player, handle guests and respond to sign-in. > [card] [Add a leaderboard](https://docs.opengame.io/guides/leaderboards.md) > > Declare a board, submit scores and show results. > [card] [Update a live game](https://docs.opengame.io/guides/updating.md) > > Preview a new release while players keep the published one. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.