Developer integration guide

Bring an existing game to Combos, whether you work in a studio or build with Codex, Claude Code, or Cursor. The workflow is prepare a browser build → test locally → upload with Combos CLI → play online → update.

Choose a route

• Already have a working browser build? Read Before you start and Publish and update.
• Need a build? Follow H5, Unity, or Roblox, then publish.
• Prefer a working project? Explore the three complete examples, with screenshots, source downloads, and recorded results.
• Stuck? Check Troubleshooting.

Version and evidence

The source guide was checked on 2026-10-08 against Combos CLI v1.14.2. Its examples used macOS 15.3, Node.js 25.7.0, and Unity 6.3 LTS 6000.3.25f1. Results below describe those recorded runs; example-specific paths, settings, and patches are not universal requirements. A successful upload, a published revision, and a playable game are separate checks.

Before you start

Combos hosts browser-native games. Upload a complete static website, usually in dist. Your output folder may have another name: always pass its actual path. The authoring tool does not change the final delivery format.

Match your project to a route

Installing Combos CLI requires neither Node.js nor a Unity plugin or SDK. Vite needs its own Node.js environment; Unity needs official Web Build Support.

Know where your files are

my-game/
├── source/
├── dist/
│   ├── index.html
│   └── assets/
├── cover.png
└── combos.json

The project root contains your editable source. ./dist is relative to the terminal’s current directory. Keep cover.png and the generated combos.json in the project root. The latter binds this project to its published game; it is not source code.

In Codex, open the whole project and its terminal, or use a system terminal. Replace the quoted path below with your own; retain quotes around spaces. Confirm that the displayed directory contains dist and cover.png, or build them first.

cd "/path/to/project"
pwd
ls

Set-Location "C:\path\to\project"
Get-Location
Get-ChildItem

Local and cloud workspaces

Codex and Cursor create files in the selected workspace. Ask your Agent for the full project path, build command, output directory, preview address, and a check of the core gameplay before publishing.

A cloud workspace can build and upload where the CLI is installed, or you can download the project and work locally. Its 127.0.0.1 is not your computer’s localhost: use the tool’s preview link or run a local server after downloading. A local preview works only while its server runs; a Combos share link works independently.

Read examples correctly

Commands require the stated environment and working directory. Replace sample paths, titles, covers, and device flags. BoatAttack’s commit and patch, and Ball Game’s coordinates, belong only to those examples. Lua and JavaScript snippets explain source behavior; they are neither terminal commands nor universal migration scripts.

Publish and update

1. Install and sign in

Ask your coding Agent to install Combos CLI and its skill using the official installation instructions , verify the installation, and guide you through login. The CLI page  is another entry point.

combos --version
combos account status
combos account login

Run combos account login only when signed out, then finish login in the browser. Confirm the version and account before uploading. Use combos update --check to check for updates and combos update to install one.

2. Prepare the build and cover

Put index.html at the root of the complete output directory and prepare cover.png from an actual game screenshot. Plain HTML/JS can already be the finished build. For Vite, Webpack, or Unity, upload the generated output, not node_modules, Library, or the whole development project. Keep credentials, server secrets, and combos.json out of the browser build.

Limits: uncompressed total ≤ 200 MiB, each file ≤ 100 MiB, at most 2,000 files. There is no separate product-level ZIP size limit; the recorded BoatAttack ZIP was 124.88 MiB.

Games run under a subpath. Use relative local asset URLs such as ./assets/game.js; Vite can use base: './'. Unity’s generated Build/... and StreamingAssets/... paths are already relative. Keep external HTTPS URLs intact; do not blindly rewrite tested engine output.

3. Test the exact output

With Python installed, run the appropriate command from the project root and keep it running. Open http://127.0.0.1:8000/.

python3 -m http.server 8000 --bind 127.0.0.1 --directory dist

py -m http.server 8000 --bind 127.0.0.1 --directory dist

Vite’s preview command or Unity’s Build And Run also works. Test the final directory you will upload, not just a development server. Do not open Unity HTML through file://. Play through start, movement or the core action, ending, and replay. Check Console and Network for failures and missing assets. Ask your Agent to serve the same output under a non-root subpath too, repair problems, and rebuild before uploading.

4. Create your game

Replace the title and use real paths. Select pc, mobile, or pc,mobile, and landscape or portrait according to verified support.

combos post create --dir ./dist --title "My Game" --cover ./cover.png --platform pc --screen-orientation landscape
combos post get

The first creation requires a cover. A new build requires --platform; platform and orientation flags do not add touch controls or change the layout. The CLI returns the share link, Canvas search code, Post, and publishing result, and creates combos.json in the project root.

The CLI compresses the directory automatically. If delivering a ZIP manually, archive the contents of dist, so index.html is at the extracted root. On macOS/Linux with zip:

cd dist
zip -r ../game-dist.zip .
cd ..

On Windows, select all files and folders inside dist and compress them.

5. Verify the public link

Stop your preview with Ctrl+C, open the returned link, and play again. Find the game in Canvas using its five-digit code, preserving leading zeros. Inspect status, revision, and submission_is_current; if the submission is not current yet, follow the actual receipt and verify the public version.

short_url: https://share.combos.game/p/0875954
game_code: 08759
status: POST_STATUS_PUBLISHED
revision: 2
submission_is_current: true

6. Update the same game

Keep your own combos.json, edit the source, rebuild, and repeat local checks before updating:

combos post update --dir ./dist --platform pc --screen-orientation landscape
combos post get

Confirm the new revision and play online again using the same share entry. Do not create a new Post for every edit. When starting from someone else’s source, create your own game first. Title or cover changes can update metadata alone; a new dist still requires platform flags.

Delegate the workflow to an Agent

Locate the project and check CLI login. Build complete static output with relative asset paths. Preview it, report the browser address, and verify the gameplay. Prepare a real screenshot cover. Create my first game or update the game bound by my own combos.json, using the actual supported devices and orientation. Stop the local server, play through the Combos link, and report the share URL, Canvas code, revision, and publishing result. Use native Unity WebGL export without a Combos Editor plugin.

Source: Combos developer integration guide , checked on 2026-10-08 with CLI v1.14.2. Example results refer to the original recorded runs.