開發者整合指南

面向已有遊戲的開發者、遊戲工作室，以及使用 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；案例結果來自原文記錄的實測。