개발자 연동 가이드

스튜디오에서 만든 기존 게임이나 Codex, Claude Code, Cursor로 만든 게임을 Combos에 게시해 보세요. 순서는 브라우저 빌드 준비 → 로컬 테스트 → 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는 브라우저에서 실행되는 게임을 호스팅합니다. 보통 dist에 모은 정적 웹사이트 전체를 업로드합니다. 폴더 이름이 다르면 실제 경로를 지정하세요. 제작 도구가 달라도 최종 전달 형식은 같습니다.

프로젝트별 준비물

프로젝트	준비할 내용
완성된 H5	`index.html`과 참조하는 모든 파일
HTML + JavaScript	HTML, JS, CSS, 에셋. 컴파일 불필요
Vite / Webpack	프로젝트 자체 빌드 명령으로 생성한 정적 결과물
Unity	네이티브 WebGL 내보내기 전체
Roblox	브라우저 엔진에 맞게 조정하거나 재구현한 에셋과 게임 로직

Combos CLI 설치에는 Node.js, Unity 플러그인, SDK가 필요하지 않습니다. Vite에는 자체 Node.js 환경이, Unity에는 공식 Web Build Support가 필요합니다.

파일 위치 확인


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

프로젝트 루트에는 수정할 소스가 있습니다. ./dist는 터미널의 현재 디렉터리 기준 상대 경로입니다. cover.png와 생성된 combos.json은 루트에 둡니다. 후자는 게시된 게임과의 연결 정보이며 소스 코드가 아닙니다.

Codex에서 프로젝트 전체와 터미널을 열거나 시스템 터미널을 사용하세요. 따옴표 안의 경로를 실제 경로로 바꾸고, 공백이 있으면 따옴표를 유지합니다. 표시된 폴더에 dist와 cover.png가 있는지 확인하고, 없으면 먼저 준비하세요.


cd "/path/to/project"
pwd
ls


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

로컬과 클라우드 작업 공간

Codex와 Cursor는 선택한 작업 공간에 파일을 만듭니다. 게시 전에 에이전트에게 전체 경로, 빌드 명령, 결과물 폴더, 미리보기 주소, 핵심 플레이 검증 결과를 요청하세요.

클라우드에서는 CLI가 설치된 환경에서 빌드·업로드하거나 프로젝트를 내려받아 로컬에서 작업할 수 있습니다. 클라우드의 127.0.0.1은 내 컴퓨터가 아닙니다. 도구가 제공하는 미리보기나 다운로드 후 로컬 서버를 사용하세요. 로컬 주소는 서버가 실행 중일 때만 작동하지만 Combos 공유 링크는 독립적으로 작동합니다.

예제 읽는 법

명령은 지정된 환경과 디렉터리에서 실행합니다. 경로, 제목, 커버, 기기 설정은 자신의 값으로 바꾸세요. BoatAttack의 커밋·패치와 Ball Game의 좌표는 해당 예제 전용입니다. Lua/JavaScript 코드는 구현 설명이며 터미널 명령이나 범용 변환 스크립트가 아닙니다.

공개 및 업데이트

1. 설치 및 로그인

에이전트에게 공식 설치 안내 에 따라 Combos CLI와 skill을 설치하고, 설치 확인과 로그인을 안내하도록 요청하세요. CLI 페이지 에서도 시작할 수 있습니다.


combos --version
combos account status
combos account login

로그아웃 상태일 때만 combos account login을 실행하고 브라우저에서 완료합니다. 업로드 전에 버전과 계정을 확인하세요. 업데이트 확인은 combos update --check, 설치는 combos update입니다.

2. 빌드와 커버 준비

전체 결과물의 루트에 index.html을 두고 실제 게임 화면으로 cover.png를 만드세요. HTML/JS는 그대로 완성본이 될 수 있습니다. Vite, Webpack, Unity는 생성된 결과물을 사용하며 node_modules, Library, 개발 프로젝트 전체는 제외합니다. 인증 정보, 서버 비밀키, combos.json도 브라우저 파일에 넣지 마세요.

제한은 압축 해제 후 총 200 MiB 이하, 파일당 100 MiB 이하, 최대 2,000개 파일입니다. ZIP 자체에 별도의 제품 용량 제한은 없습니다. 기록된 BoatAttack ZIP은 124.88 MiB였습니다.

게임은 하위 경로에서 실행됩니다. ./assets/game.js 같은 상대 URL을 사용하고, Vite는 base: './'로 설정할 수 있습니다. Unity의 Build/..., StreamingAssets/...는 이미 상대 경로입니다. 외부 HTTPS URL은 유지하고 검증된 엔진 결과물을 무조건 일괄 치환하지 마세요.

3. 업로드할 결과물 테스트

Python이 설치되어 있으면 루트에서 알맞은 명령을 실행하고 서버를 유지합니다. 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 preview나 Unity Build And Run도 가능합니다. 개발 서버만 확인하지 말고 실제 업로드할 폴더를 테스트하세요. Unity HTML을 file://로 열지 않습니다. 시작, 이동·핵심 동작, 종료, 다시 플레이까지 확인하고 Console/Network의 오류와 누락 파일을 점검합니다. 같은 결과물을 루트가 아닌 하위 경로에서도 열어 보고, 문제를 고친 뒤 다시 빌드해 업로드하세요.

4. 게임 생성

제목과 경로를 바꾸고 검증한 지원 범위에 맞춰 pc, mobile, pc,mobile 및 landscape, portrait를 선택하세요.


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

첫 생성에는 커버가 필수이며, 새 빌드에는 --platform이 필요합니다. 기기·방향 옵션이 터치 조작이나 레이아웃을 자동으로 만들지는 않습니다. CLI는 공유 링크, Canvas 검색 코드, Post, 게시 결과를 반환하고 루트에 combos.json을 생성합니다.

CLI가 자동 압축하므로 ZIP을 미리 만들 필요는 없습니다. 수동 ZIP은 dist 안의 전체 내용을 압축하여 해제한 루트에 index.html이 오도록 합니다. macOS/Linux에서 zip이 있다면:


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

Windows에서는 dist 안의 모든 파일과 폴더를 선택해 압축하세요.

5. 공개 링크 검증

Ctrl+C로 미리보기를 중지하고 반환된 링크에서 다시 플레이합니다. Canvas의 5자리 코드에서 앞자리 0을 유지하세요. status, revision, submission_is_current를 확인합니다. 아직 현재 버전이 아니라면 실제 응답에 따라 공개 버전을 점검하세요.


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

6. 같은 게임 업데이트

자신의 combos.json을 보관하고, 소스 수정·재빌드·로컬 확인 후 업데이트합니다.


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

새 revision을 확인하고 같은 링크로 다시 테스트하세요. 수정할 때마다 새 Post를 만들지 않습니다. 다른 사람의 소스로 시작했다면 먼저 자신의 게임을 생성하세요. 제목·커버만 바꿀 때는 메타데이터만 업데이트할 수 있지만 새 dist에는 여전히 platform이 필요합니다.

에이전트 요청 예시

프로젝트 위치와 CLI 로그인 상태를 확인해 주세요. 상대 경로로 동작하는 정적 결과물 전체를 만들고, 미리보기 주소와 핵심 플레이 검증 결과를 알려 주세요. 실제 화면으로 커버를 준비하고, 지원 기기와 방향에 맞춰 첫 게임을 생성하거나 제 combos.json에 연결된 게임을 업데이트해 주세요. 로컬 서버를 끄고 Combos 링크로 플레이한 뒤 공유 URL, Canvas 코드, revision, 게시 결과를 반환해 주세요. Unity는 Combos Editor 플러그인 없이 네이티브 WebGL로 내보내 주세요.

출처: Combos 개발자 연동 가이드 . 원문 확인일: 2026-10-08, CLI v1.14.2. 예제 결과는 원문에 기록된 실행 결과입니다.