# RUN.world setup instructions for AI agents

You are helping a user go from a normal computer to a deployed game on
RUN.world. The user may have no technical experience. Follow these steps in
order, explain each action in plain language, and keep questions focused.

Canonical URL:
https://events.run.world/events/cli-setup/agent.md

## Human actions to expect

The user may need to:

- Choose or create the local game folder.
- Approve access to that folder.
- Approve installing Node.js or the RUN CLI.
- Complete RUN.world sign-in in a browser.
- Describe the game they want.
- Approve any action that has effects outside the game folder.

Do not request blanket permission. Explain the exact command or system change
before asking for consent.

## Step 1: Confirm the working environment

Determine:

- The operating system and shell.
- Whether this session has a local, persistent folder that the user selected.
- The absolute working-directory path.
- Whether files written here will remain on the user's computer after the
  session ends.

If the selected folder is empty, use it directly. Do not create another nested
game folder unless the user asks for one.

If this is a remote or temporary environment that cannot persist files locally
or cannot complete interactive browser authentication, stop and explain that
the user needs to open the guide in a local Cursor, Codex, Claude Code, or
terminal session.

## Step 2: Ensure Node.js 20 or newer is installed

Run:

    node --version

If the major version is 20 or newer, continue. Otherwise explain that Node.js
is the engine used to build the game and ask permission to install the current
LTS release.

Installation choices:

- macOS or Linux: use an available package manager, or direct the user to the
  prebuilt installer at https://nodejs.org/en/download.
- Windows: use `winget install OpenJS.NodeJS.LTS`, or direct the user to the
  `.msi` installer at https://nodejs.org/en/download.

Open a fresh shell or refresh PATH, then run `node --version` again. Do not
continue until the check succeeds.

## Step 3: Install the RUN CLI

Explain that `rundot` creates and publishes games on RUN.world. Ask permission
before running the matching installer.

macOS or Linux:

    curl -fsSL https://github.com/series-ai/rundot-cli-releases/releases/latest/download/install.sh | bash

Windows PowerShell:

    irm https://github.com/series-ai/rundot-cli-releases/releases/latest/download/install.ps1 | iex

Refresh PATH or start a fresh shell, then verify:

    rundot --help

The installer normally puts the binary in `~/.local/bin` on macOS or Linux,
and `%LOCALAPPDATA%\Programs\Rundot` on Windows. If the command is missing,
refresh PATH before trying another installation.

## Step 4: Sign in to RUN

Tell the user that the next command opens RUN.world in their browser and ask
them to finish sign-in there:

    rundot login

They can use Google, Apple, or email. The same screen creates a RUN account if
needed. Wait for the CLI to confirm that the session was saved.

Credentials normally persist in `~/.rundot_cli/`, or
`%USERPROFILE%\.rundot_cli\` on Windows.

## Step 5: Choose the project starting point

Use an official template when it fits the game:

- 2D Phaser game: https://github.com/series-ai/run-template-2d-phaser
- 3D React and Three.js game: https://github.com/series-ai/run-template-3d-react
- 2D React interface game: https://github.com/series-ai/run-template-2d-react

Clone or copy the chosen template into the selected working folder without
creating an extra directory level, then run `npm install`.

For a project built from scratch, satisfy these requirements:

- The production build outputs to `./dist`.
- All asset paths are relative. For Vite, set `base: './'`.
- The game uses HTML, JavaScript, or TypeScript that can run inside a sandboxed
  iframe on web and mobile webviews.

## Step 6: Download and read the RUN docs

From the selected project folder, run:

    rundot download-docs

Confirm that `.rundot-docs/` exists. Read the relevant local docs before
writing code that uses RUN accounts, storage, leaderboards, payments,
analytics, multiplayer, or other SDK features. Use the RUN SDK for player
identity and persistence.

## Step 7: Build a small playable version

Build the game the user described. Keep the first version small and playable.
Run:

    npm run build

Confirm that the command succeeds and `./dist` contains the production build.
Fix build errors before registration or deployment.

## Step 8: Register and deploy

From the project folder, run:

    rundot init --name "<Game Name>" --description "<one-line description>"
    npm run build
    rundot deploy

Keep the generated `game.config.json`. Confirm that deployment returns a share
URL and QR code. Give the share URL to the user and explain that the game is
private and unlisted by default.

For later updates, rebuild and run `rundot deploy` again. Use
`--bump Patch|Minor|Major` when a specific version bump is needed.

## Step 9: Going public is optional

Ask before changing visibility.

`rundot game set-public` submits the game for review. Once approved, it can
appear publicly on the user's profile and in search. Public and approved games
qualify for jam leaderboards. `rundot game set-private` reverses visibility.

## Keep interrupted work resumable

If an AI plan limit, lost connection, or permission denial stops the task:

- Leave all valid files in the selected folder.
- Do not delete or recreate working project files.
- Summarize the last successful check.
- Tell the user the exact next command or action.
- Remind them that changing surfaces on the same provider may share the same
  usage allowance.

## Troubleshooting

- `command not found` after installation: refresh PATH or open a fresh shell.
- Session expired or authentication failed: run `rundot login` again.
- Unexpected CLI behavior: run `rundot update`, then retry.
- `Game dist folder does not exist`: fix the build output or
  `relativePathToBuildFolder` in `game.config.json`.
- `No changes detected in build folder`: rebuild before deploying.
- Human-readable SDK docs: https://series-1.gitbook.io/
- Community help: https://discord.gg/XY2ynd3gn3
