[앱인 토스] 코코스 기반 빌드 오류 해결

앱인토스 기반 게임개발 을 많이 하고 있다. 

 

최근 그래서 코코스 크리에이터 기반으로 웹 & 모바일 크로스 플랫폼 개발을 진행했음.

 

그래서 개발 진행하면서 

 

여러문제가 있었는데. 

 

첫번째 문제가 

 

ait 파일로 빌드하여 업로드하는 것인데.

 

이게 문제가 업로드 해도 로딩창만 뜨고 바로 꺼져버리는것 아닌가?

 

 

오류도 없고 뭐가 문제인지 커뮤니티에 올려놓아도 문제가 해결될 여지가 없음.

 

그러다가 여러 cocos 기반 개발은 아니지만 Native 개발, React 기반 개발 하는 사람들의 의견을 따라

 

이렇게 했다 

 

혹시나 나와같은 문제를 가지는 분들을위해 해결방안을 제시한다.

 

우선 나의 개발환경은 다음과같다

 

os : window 10

engine : cocos creator 3.8.7 

 

api 

firebase analytics 

firebase realtime database 

 

기반으로 개발한 단순한 하이퍼 캐주얼 게임

 

아래 부분을 참고할것.

 

## 필수 요구사항

### 소프트웨어

- Node.js 14.x 이상

- npm 6.x 이상

- Cocos Creator 3.8.7

 

 

## 1. 초기 설정

### 1.1 Toss Wrapper 프로젝트 설정

**toss-wrapper/package.json**

{
  "name": "brickbreaker-legendary",
  "version": "1.0.0",
  "description": "Breakers - Brick Breaker Game for Toss",
  "main": "index.html",
  "scripts": {
    "dev": "granite dev",
    "build": "granite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "@apps-in-toss/web-framework": "^1.1.2"
  },
  "devDependencies": {
    "vite": "^6.1.0"
  }
}


**중요 버전 정보:**
- `@apps-in-toss/web-framework`: **1.1.2** (필수)
- `vite`: **6.1.0** 이상

### 1.2 Granite 설정

**toss-wrapper/granite.config.ts**
```typescript
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'brickbreaker-legendary',  // Toss 콘솔의 앱 이름과 정확히 일치해야 함
  web: {
    host: 'localhost',
    port: 3000,
    commands: {
      dev: 'vite --host',
      build: 'vite build',
    },
  },
  permissions: [],  // 필요한 권한 (빈 배열)
  outdir: 'dist',   // 빌드 출력 디렉터리
  brand: {
    displayName: 'Breakers',        // 앱 표시 이름
    icon: '',                        // 아이콘 URL (필수 필드, 빈 문자열 가능)
    primaryColor: '#FF6B35',         // 앱 테마 색상
    bridgeColorMode: 'inverted',     // 브릿지 색상 모드
  },
  webViewProps: {
    type: 'partner',  // 웹뷰 타입 (필수)
  },
});

 

 

**필수 필드:**

- ✅ `appName` - Toss 콘솔 앱 이름과 **완전히 일치**해야 함

- ✅ `web.commands.dev` - 개발 서버 명령어

- ✅ `web.commands.build` - 빌드 명령어

- ✅ `permissions` - 권한 배열 (빈 배열도 필수)

- ✅ `brand.icon` - **반드시 포함** (빈 문자열 `''` 가능)

- ✅ `webViewProps.type` - 웹뷰 타입

 

 

### 1.3 Vite 설정

**toss-wrapper/vite.config.ts**

import { defineConfig } from 'vite';

export default defineConfig({
  publicDir: 'public',
});

 

 

 

기본적인 설정이고

 

아래는 빌드한 정보를 이제 ait 로 만드는과정

 

 

 

## 2. 빌드 프로세스

### 2.1 Cocos Creator 웹 빌드

1. Cocos Creator 열기
2. **Project → Build** 메뉴
3. 플랫폼: **Web Mobile** 선택
4. Build Path: `{your_project_directory}\build\web-mobile`
5. **Build** 클릭

### 2.2 Cocos 빌드 복사


# toss-wrapper/public/game/ 디렉터리로 복사

cd {your_project_directory}
mkdir -p toss-wrapper/public/game
cp -r build/web-mobile/* toss-wrapper/public/game/


### 2.3 의존성 설치


cd toss-wrapper
npm install


### 2.4 .ait 파일 빌드


cd toss-wrapper
npm run build


**빌드 성공 시 출력:**

vite v6.1.0 building for production...
✓ 2 modules transformed.
dist/index.html  0.60 kB │ gzip: 0.31 kB
✓ built in 207ms
◇  Building ios
◇  Building android
◆  brickbreaker-legendary.ait 빌드 완료
◆  Build completed


**생성된 파일:**

toss-wrapper/{your_project_name}.ait (약 5-6 MB)

 

 

정상 업로드 된다.