开发者接入指南

面向已有游戏的开发者、游戏工作室，以及使用 Codex / Claude Code / Cursor 制作游戏的人。完成接入的主线是：准备浏览器能运行的网页成品 → 本地验证 → Combos CLI 上传 → 在线试玩 → 后续更新。

已有网页成品，可以从开始前的准备开始，再按发布与更新完成接入。需要先制作网页成品，可以选择准备 H5 成品、Unity 原生导出或Roblox 游戏适配。完整案例提供从准备到发布的操作过程、截图、源码和验证结果，可按需跟做。

文档口径核对：2026-10-08，Combos CLI v1.14.2。案例实操环境为 macOS 15.3、Node.js 25.7.0、Unity 6.3 LTS 6000.3.25f1。路径和游戏名称使用示例值时会明确标注。

指南目录

开始前的准备

选择接入路线

Combos 是浏览器原生（H5）游戏平台，玩家打开链接即可进入游戏。CLI 接入上传的是能在浏览器运行的静态网页成品，通常整理在名为 dist 的目录中。dist 是本教程统一使用的成品目录名称；自己的输出目录可以叫 build 等其他名称，上传时填写实际路径即可。

你的项目	先准备什么	对应章节
已经能运行的 H5 成品	包含 index.html 和全部网页资源的目录	发布与更新：通用发布流程
直接 HTML + JavaScript	整理入口 HTML、JS、CSS 和资源；无需编译	准备 H5 成品
Vite / Webpack 等工程	用项目自己的构建命令生成静态成品	准备 H5 成品
Unity 游戏	使用 Unity 原生 WebGL 导出整个成品目录	Unity 原生导出
Roblox 游戏	先在浏览器引擎中重实现或适配资产、人物与玩法	Roblox 游戏适配

使用哪种制作工具不改变最后的交付格式。安装 Combos CLI 不要求 Node.js、Unity 插件或 SDK；Vite 工程需要 Node.js，Unity 导出需要 Unity 官方 Web Build Support，这些属于各自项目的制作环境。

认识项目目录、dist 和浏览器地址


my-game/                      # 项目根目录：打开终端的位置
├── 源文件或引擎工程/          # 用来继续开发，保留在自己的环境
├── dist/                      # 网页成品：上传这个目录的内容
│   ├── index.html             # 浏览器入口
│   └── JS、CSS、图片、模型等   # 或 Unity 的 Build / TemplateData 等
├── cover.png                  # 封面图，首次创建游戏时使用
└── combos.json                # 发布后自动生成，记录当前游戏绑定

名称	含义	本教程的例子
项目根目录	整个工程所在的文件夹；先让终端进入这里	桌面 Move to Combos/native-h5
`./dist`	`./` 是终端当前目录；因此它指当前目录下的 dist	在 native-h5 根目录执行上传，读取 native-h5/dist
`http://127.0.0.1:8000/`	本地 HTTP 服务提供的地址；只在相应服务运行时可用	本地浏览器试玩地址，不是发布链接
Combos 分享链接	上传后返回的线上地址	发给玩家试玩，不依赖本地预览服务

进入目录时，可以在 Codex 中打开整个项目文件夹并使用它的终端，也可以使用系统终端。macOS / Linux 使用下面的 cd；Windows PowerShell 使用 Set-Location。将引号里的路径替换成自己的项目完整路径，有空格也保留引号。


cd "/你的项目完整路径"
pwd
ls


Set-Location "C:\你的项目完整路径"
Get-Location
Get-ChildItem

成功现象： 终端显示自己的项目路径，文件列表中能看到 dist 和 cover.png。如果还没有 dist，先按所选路线构建。路径写错时先修正当前目录，再执行后面的命令。

在 Codex 里制作，文件在哪里？

本机 Codex / Cursor 通常在所选工作目录里生成和修改文件。它是制作入口，生成的 HTML、JavaScript、模型和 dist 仍然是项目文件。让 Agent 明确告诉你项目路径、构建方式和成品路径，再进行发布。

如果使用云端 Coding 环境，文件可能位于云端工作区。可以在同一个有 CLI 的环境中构建和上传，也可以把工程下载到自己的电脑后构建和上传。云端的 127.0.0.1 不等于自己电脑的 127.0.0.1；使用该工具提供的预览入口，或下载后启动本地服务验证。


请检查当前工作区里的这个游戏，并告诉我：
1. 项目的完整路径和进入项目的方式。
2. 它是直接 HTML + JS，还是需要用构建工具或引擎导出。
3. 如何生成包含 index.html 的完整网页成品，以及成品目录路径。
4. 如何启动预览、在哪个浏览器地址打开，并检查主要玩法。
完成检查后再按[发布与更新](/docs/#publishing)发布到 Combos。

分清可以执行的命令和案例代码

标记	如何使用	例子
可直接执行	满足注明的环境和目录条件后，在终端运行	`combos --version`
需替换参数	先换成自己的路径、标题、封面或设备，再执行	`cd "/你的项目完整路径"`
仅本案例	用于跟做此案例；接入自己的游戏时按自己的工程调整	BoatAttack 固定 commit、Ball Game 坐标
源码对照	解释案例如何实现；不是终端命令，也不是通用迁移脚本	Lua 的 Touched 与 JavaScript 接触回调

发布与更新

安装 Combos CLI 并登录

操作位置： 自己的 Coding Agent 对话和项目终端。

操作： 把下方安装指令交给 Agent。安装完成后检查版本与账号状态；未登录时执行 login，并在打开的浏览器中完成账号登录。

成功现象： 版本能正常输出，account status 显示已登录。后续上传使用这个账号。


帮我按照 https://cdn.combos.fun/cli/install.md 安装 Combos CLI 和配套 skill，验证安装成功后引导我登录账号。


combos --version
combos account status
# 只有未登录时再执行：
combos account login

CLI 介绍与安装入口：Combos CLI 页面。以后检查新版本可用 combos update --check，需要更新时执行 combos update。

准备成品目录和封面

操作位置： 项目文件夹和项目根目录的终端。

操作： 找到完整 dist，确认根部有 index.html 和所有资源。准备一张真实游戏画面作为 cover.png，放在项目根目录。自己的成品不叫 dist 或封面不叫 cover.png 时，上传命令填写实际名字。

成功现象： 目录结构符合开始前的准备；不是仅有 index.html，也没有把 node_modules、Library 或完整开发工程放进成品。

直接 HTML + JS 的 HTML / JS / CSS 可以同时是源码与网页成品，无需为了上传再编译。Vite、Webpack 和 Unity 则上传各自输出的静态成品。前端网页资源会发送给浏览器；账号凭证和服务端密钥不属于成品。combos.json 保留在项目根目录。

成品硬性限制：解压后总量 ≤ 200 MiB、单文件 ≤ 100 MiB、最多 2,000 个文件。 ZIP 没有单独的 Combos 产品级体积上限。BoatAttack 的实际 ZIP 为 124.88 MiB，已完成上传。

游戏托管在子路径下。自己编写的项目资源使用相对地址，例如 ./assets/game.js；Vite 可设置 base: './'。Unity 默认生成的 Build/...、StreamingAssets/... 也是相对路径。外部完整 HTTPS 地址保留原样，已验证的引擎输出无需批量改字符串。

用浏览器验证最终成品

操作位置： 项目根目录的终端，然后是浏览器。

操作： 启动下面的 HTTP 服务，保持终端运行。在浏览器地址栏打开 http://127.0.0.1:8000/。命令要求已安装 Python 且当前目录下有 dist；Windows 使用 py，系统已有 python 命令也可以使用 python。

成功现象： 进入游戏，实际完成开始、移动或核心操作、结束或重玩。浏览器 Console / Network 没有导致游戏失败的错误或资源 404。


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 工程也可以使用项目的 preview 命令；Unity 可以使用 Build And Run。验证对象必须是最后上传的成品目录。Unity 不用 file:// 双击 HTML 验证。需要检查子路径时，让 Agent 将同一成品挂到一个预览子路径再打开，确认本地资源仍可加载。


请预览将要上传的成品目录，告诉我浏览器地址。检查入口、资源加载和主要玩法；再在一个非网站根目录的子路径下打开同一成品，确认资源地址正确。将发现的问题修复并重新构建后，再上传。

首次上传，创建自己的游戏

操作位置： 项目根目录的终端；dist 和 cover.png 已准备好。

操作： 修改下方标题后执行 create。按自己的游戏实际支持情况选择 pc、mobile 或 pc,mobile；横屏使用 landscape，竖屏使用 portrait。

成功现象： CLI 返回游戏的分享链接、Canvas 搜索码、Post 和发布结果；根目录生成 combos.json，用于继续更新这个游戏。


combos post create --dir ./dist --title "我的游戏" --cover ./cover.png --platform pc --screen-orientation landscape
combos post get

--dir 指向成品目录；--cover 指向封面文件；--title 是标题。--platform 和 --screen-orientation 声明设备与方向，不会自动增加触控或修改布局。首次创建必须提供封面；传入新构建时必须提供 platform。

CLI 自动把 dist 的内容压缩并上传，不需要提前手工制作 ZIP。如果交付 ZIP，压缩的是 dist 里面的全部内容，让解压后的根目录直接出现 index.html。下面的手工打包命令适用于有 zip 命令的 macOS / Linux；Windows 可以在 dist 内选中所有成品文件和目录进行压缩。


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

打开线上链接，再实际玩一次

操作位置： 本地预览终端和浏览器。

操作： 先在预览终端按 Ctrl+C 停止服务，再打开 CLI 返回的分享链接。重新进入游戏并验证主要玩法；用返回的五位搜索码在 Canvas 中查找游戏。

成功现象： 游戏从 Combos 线上资源加载，停止本地服务后仍可运行。核对发布状态和本次更新结果，不把“上传完成”直接当成“线上可玩”。

返回结果中的 short_url 是分享链接，game_code 是 Canvas 搜索码，保留开头的 0。查看 status、revision 和更新回执的 submission_is_current；若本次更新尚未成为当前版本，按 CLI 实际结果处理，并核对当前公开链接。


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

修改后更新同一个游戏

操作位置： 保留 combos.json 的原项目根目录。

操作： 修改自己的源工程，重新生成 dist，完成发布与更新的成品验证，再执行 update。设备和方向填写自己的实际支持情况。

成功现象： 同一个 Post 返回新 revision，原分享入口保持可继续使用；再次执行发布与更新线上试玩。


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

不要每次修改都重新 create。combos.json 记录的是游戏绑定，不是源码；从别人的案例源码开始时，先 create 自己的游戏。只改标题或封面时可单独更新元数据；上传新 dist 时仍须带 platform。

把发布任务交给 Agent


请把当前工作区的游戏发布到 Combos：
1. 明确项目路径，检查 CLI 安装和登录状态；未登录时引导我完成登录。
2. 按项目自己的方式生成静态成品，确认 index.html、相对资源路径和完整资源。
3. 启动成品预览，给出浏览器地址，验证主要玩法并修复加载问题。
4. 用实际游戏截图准备封面；按真实支持的设备和方向上传。
5. 项目有我自己的 combos.json 时更新同一游戏；首次发布则创建。
6. 停止本地服务，从 Combos 链接实际试玩，返回分享链接、Canvas 搜索码、版本与发布结果。
请不要要求安装 Unity 的 Combos Editor 插件；Unity 项目使用原生 WebGL 导出。

来源：Combos 开发者接入指南。原文核对日期：2026-10-08，CLI v1.14.2；案例结果为原文记录的实测结果。