WeChat 미니게임 엔진 플러그인 실전 가이드: 설정부터 자주 겪는 문제까지

미니게임 개발을 끝내고 빌드해 보니 패키지 크기가 5.2M입니다.

WeChat 백엔드에 업로드하자마자 바로 반려됩니다. 메인 패키지는 4M을 넘을 수 없기 때문입니다.

리소스를 지우고, 텍스처를 압축하고, 오디오를 잘라 내며 한참을 손본 끝에 겨우 3.9M까지 줄여 업로드는 성공했습니다. 그런데 플레이어가 게임을 열 때 몇 초씩 기다려야 하고, 일부는 아예 나가 버립니다.

문제의 핵심은 엔진 코드가 많은 공간을 차지한다는 점입니다.

WeChat 미니게임 엔진 플러그인은 WeChat v7.0.7에서 추가된 기능으로, 엔진 코드를 분리해 별도로 캐시할 수 있습니다. 플레이어가 플러그인을 활성화한 게임을 한 번 실행한 뒤에는, 당신의 게임을 열 때 엔진을 다시 다운로드하지 않아도 됩니다. 시작 속도는 0.5~2초 빨라질 수 있습니다.

설정 과정은 복잡하지 않지만, 몇 가지 자주 밟는 지점이 있습니다. 이 글에서는 전체 흐름과 해결책을 한 번에 정리해, 시행착오에 쓰는 시간을 줄이는 데 초점을 맞춥니다.

엔진 플러그인이란 무엇이고, 왜 시작 속도를 높이나요

먼저 엔진 플러그인이 어떻게 동작하는지 이해해야 이 기능이 왜 유용한지 알 수 있습니다.

일반 모드에서는 각 미니게임이 전체 게임 엔진 코드를 다운로드해야 합니다. 예를 들어 Cocos Creator로 개발했다면, 플레이어가 게임을 열 때 Cocos 엔진 전체를 내려받아야 합니다. 대략 1~2M 정도입니다.

WeChat v7.0.7 이후에는 엔진을 플러그인으로 별도 캐시할 수 있습니다. 이는 다음을 뜻합니다.

첫 번째 플레이어가 당신의 게임을 열 때: 전체 엔진 + 게임 코드를 다운로드하고, 엔진은 WeChat 클라이언트에 캐시됩니다.

두 번째 플레이어가 당신의 게임을 열 때: 로컬에 같은 버전의 엔진 캐시가 있다면 바로 재사용하고, 엔진을 다시 다운로드하지 않습니다.

플레이어가 같은 엔진의 다른 게임을 열 때: 그 게임도 엔진 플러그인을 활성화했고 엔진 버전이 같다면, 엔진 코드를 그대로 재사용합니다.

예를 들어 플레이어가 방금 A 게임(Cocos 2.2.0 사용)을 플레이했고, 이제 당신의 B 게임(역시 2.2.0 사용)을 연다고 생각해 보겠습니다. 엔진은 이미 캐시되어 있으므로 바로 재사용됩니다. 시작 시간이 4초에서 2초로, 때로는 더 짧게 줄어듭니다.

엔진 버전이 다르면 어떻게 될까요? 예를 들어 플레이어가 캐시한 버전은 v2.2.0이고, 당신의 게임은 v2.2.1을 사용합니다. 이때 WeChat은 전체를 다시 다운로드하지 않고 두 버전의 차이만 증분으로 다운로드합니다. 실제 테스트에서는 증분 업데이트가 보통 다운로드량을 50% 이상 줄여 줍니다.

공식 데이터는 시작 속도가 0.5~2초 빨라질 수 있다고 말합니다. 숫자만 보면 크지 않아 보이지만, 이탈률 데이터는 꽤 냉정합니다. 평균 시작 시간이 4초인 게임은 1초 만에 시작하는 게임보다 이탈 가능성이 60% 더 높습니다. 시작 시간의 1초는 실제로 비용입니다.

현재 엔진 플러그인을 지원하는 엔진은 Cocos Creator, Egret, LayaAir 세 가지입니다. 이 글은 주로 Cocos Creator 설정 흐름을 다룹니다. 다른 엔진도 원리는 같고, 설정 방식만 약간 다릅니다.

엔진 플러그인 활성화 방법: 전체 설정 흐름

Cocos Creator 2.2.1 이후에는 엔진 플러그인 기능이 이미 내장되어 있습니다. 설정은 생각보다 단순합니다. 대부분의 작업은 에디터가 자동으로 처리합니다.

1단계: 빌드 패널에서 “엔진 분리” 옵션 선택

Cocos Creator를 열고 메뉴에서 “Project” -> “Build”를 선택하거나, 에디터 상단의 “Build” 버튼을 바로 클릭합니다.

빌드 패널에서 WeChat 미니게임 플랫폼을 찾고 “Separate Engine”에 해당하는 옵션을 선택합니다. 에디터 버전에 따라 이 옵션 이름은 조금 다를 수 있습니다. 어떤 버전은 “Use Engine Plugin”, 어떤 버전은 “Allow Separate Engine”처럼 표시되지만 기능은 같습니다.

전제 조건은 두 가지입니다.

1. 에디터 내장 엔진을 사용해야 하며, 커스텀 엔진이 아니어야 합니다. 커스텀 엔진은 플러그인 모드를 지원하지 않습니다.
2. 디버그 모드 빌드가 아니어야 합니다. 디버그 모드에서는 엔진 코드가 전체 패키징되고 분리되지 않습니다.

빌드를 클릭하고 완료될 때까지 기다리면, 빌드 디렉터리에서 새 파일 세 개를 볼 수 있습니다.

• game.json: 게임 설정 파일이며 plugins 필드가 추가됩니다.
• plugin.json: 플러그인 설정 파일이며 플러그인 엔트리를 지정합니다.
• signature.json: 플러그인 파일 검증 서명입니다.

이 세 파일은 에디터가 자동으로 생성하므로 직접 수정할 필요가 없습니다.

2단계: WeChat Developer Tools로 프로젝트 열기

WeChat Developer Tools로 빌드 출력 디렉터리를 엽니다. 보통 build/wechatgame입니다.

여기서 주의할 점이 하나 있습니다. appid는 반드시 직접 개통한 값을 입력해야 하며, 에디터 기본 범용 테스트 id를 쓰면 안 됩니다.

왜 그럴까요? 엔진 플러그인은 권한 검증이 필요합니다. 범용 테스트 id는 검증을 통과할 수 없으므로 플러그인 기능이 실패합니다.

WeChat Developer Tools에서 오른쪽 위 “Details”를 클릭한 뒤, “Local Settings”에 자신의 appid를 입력합니다. appid가 아직 없다면 WeChat Official Accounts Platform에서 미니게임 계정을 등록하고, 심사를 통과한 뒤 받을 수 있습니다.

3단계: 실제 기기 테스트로 검증

WeChat Developer Tools에서 “Preview”를 클릭해 미리보기 QR 코드를 생성합니다. 휴대폰으로 스캔해 테스트합니다.

디버깅 패널(vConsole)을 열면 다음과 비슷한 로그가 보입니다.

plugin ***** inject success!

inject success가 보이면 엔진 플러그인이 정상적으로 로드된 것입니다. inject fail이 보이면 문제가 있다는 뜻입니다. 다음 장에서 자주 겪는 문제와 해결 방법을 자세히 다룹니다.

버전 요구 사항 체크리스트

설정 전에 아래 버전 요구 사항을 모두 만족하는지 확인합니다.

항목	버전 요구 사항	설명
WeChat 클라이언트	>= 7.0.7	이보다 낮은 버전은 엔진 플러그인을 지원하지 않음
WeChat Developer Tools	>= 1.02.1911181	RC 버전이면 가능
기본 라이브러리 버전	>= 2.9.0	Developer Tools에서 설정
Cocos Creator	>= 2.2.1	이전 버전은 플러그인 기능을 지원하지 않음

버전이 기준에 미치지 못하면 엔진 플러그인 기능은 적용되지 않습니다. 다만 게임 자체는 정상 실행됩니다. 엔진 코드가 메인 패키지에 전체 포함될 뿐입니다.

성능 개선 실측 데이터 비교

원리만으로는 직관적이지 않으니 실제 데이터를 보겠습니다.

같은 엔진 버전: 완전 재사용

플레이어의 휴대폰에 Cocos Creator v2.2.0 엔진이 이미 캐시되어 있다고 가정해 보겠습니다. 당신의 게임도 이 버전을 사용하고, 엔진 플러그인을 활성화했습니다.

플레이어가 게임을 열 때:

• 일반 모드: 엔진 1.5M + 게임 코드 2.5M = 총 4M 다운로드, 시작 시간 약 4초
• 플러그인 모드: 엔진은 바로 재사용하고 게임 코드 2.5M만 다운로드, 시작 시간 약 2초

이것이 가장 이상적인 상황입니다. 엔진을 전혀 다운로드하지 않아도 됩니다.

다른 엔진 버전: 증분 업데이트

당신의 게임은 v2.2.1을 사용하고, 플레이어가 캐시한 엔진은 v2.2.0이라면 상황이 조금 다릅니다.

WeChat은 두 버전의 차이를 비교해 변경된 부분만 다운로드합니다. 보통 버전 업그레이드의 차이는 크지 않으므로 증분 다운로드량은 전체의 약 10%~30%입니다.

예를 들면 다음과 같습니다.

• 일반 모드: 엔진 1.5M 다운로드(v2.2.1 전체 버전)
• 플러그인 모드: 약 0.15~0.45M만 증분 다운로드, 70% 이상 절감

패키지 최적화 실제 사례

한 캐주얼 러닝 게임 프로젝트의 실측 데이터는 꽤 대표적입니다.

최적화 전:

• 전체 패키지 6.8M(제한 초과, 업로드 불가)
• 텍스처 리소스 3.06M(45%)
• 오디오 파일 1.7M(25%)
• 폰트 파일 1.02M(15%)
• 엔진 코드 0.68M(10%)
• 기타 0.34M(5%)

엔진 플러그인 + 리소스 최적화 후:

• 전체 패키지 3.2M(정상 업로드)
• 첫 화면 로딩 시간이 5초에서 3초로 줄어 40% 빨라짐

이 사례가 말해 주는 점은 분명합니다. 엔진 플러그인은 최적화의 일부일 뿐입니다. 4M 제한을 실제로 넘기려면 리소스 압축과 코드 트리밍을 함께 적용해야 합니다. 이 부분은 뒤에서 더 자세히 다룹니다.

시작 속도 비교 요약

상황	일반 모드	플러그인 모드	효과
같은 버전 엔진 첫 시작	전체 엔진 다운로드	캐시된 엔진 재사용	0.5~2초 단축
다른 버전 엔진 시작	1.5M 전체 다운로드	0.15~0.45M 증분 다운로드	다운로드량 70% 감소
낮은 버전 WeChat(7.0.6)	정상 실행	플러그인 미적용	호환 처리 필요

데이터 출처는 Cocos 공식 문서와 CSDN 실측 사례입니다. 프로젝트마다 상황은 다르지만, 전체적인 경향은 같습니다. 엔진 플러그인은 다운로드량을 눈에 띄게 줄이고 시작 속도를 높일 수 있습니다.

자주 겪는 문제 5가지와 해결 방법

설정 과정은 단순해 보이지만, 실제로는 자주 문제가 생깁니다. 가장 흔한 5가지를 정리했고, 각각 해결 방법을 함께 적었습니다.

문제 1: appid에 범용 테스트 id를 사용해 테스트할 수 없음

증상:

빌드 완료 후 WeChat Developer Tools로 프로젝트를 열고 미리보기를 클릭합니다. 휴대폰으로 스캔하면 게임은 실행되지만 디버깅 패널에 다음이 표시됩니다.

plugin ***** inject fail!

또는 엔진 플러그인 관련 로그가 아예 나오지 않습니다.

원인:

Cocos Creator 빌드 패널에는 기본적으로 범용 테스트 appid가 들어 있습니다. 보통 wx1234567890abcdef 같은 값입니다. 이 id는 로컬 디버깅용일 뿐, 정식 미니게임 권한이 없습니다. 엔진 플러그인은 권한 검증이 필요하므로 범용 테스트 id로는 통과할 수 없습니다.

해결 단계:

1. WeChat Official Accounts Platform을 열고, appid에 미니게임 권한이 활성화되어 있는지 확인합니다. 미니프로그램 권한이 아니라 미니게임 권한이어야 합니다.
2. WeChat Developer Tools에서 오른쪽 위 “Details” -> “Local Settings”를 클릭합니다.
3. 자신의 appid를 입력합니다.
4. “Clear Cache” -> “Clear All”을 클릭한 뒤 다시 컴파일하고 미리보기합니다.

검증 방법:

미리보기 후 디버깅 패널에 plugin ***** inject success!가 표시되면 설정이 올바른 것입니다.

문제 2: “플러그인 사용 권한이 없으니 플러그인을 추가하라”는 메시지

증상:

실제 기기 미리보기에서 게임 시작에 실패하고 다음과 같은 메시지가 표시됩니다.

Plugin is not authorized. Please add the plugin.

원인:

플러그인이 아직 당신의 미니게임 프로젝트에 추가되지 않았습니다. WeChat은 개발자가 플러그인 권한을 직접 추가하도록 요구합니다.

해결 단계:

1. 안내 창의 “Add Plugin” 버튼을 클릭합니다.
2. 플러그인 목록에서 CocosCreator 플러그인을 찾아 추가합니다.
3. 게임을 다시 컴파일합니다.
4. 추가할 때 “추가 가능한 플러그인 정보가 비어 있음”과 비슷한 메시지가 나오면, Developer Tools에서 전체 캐시를 지운 뒤 다시 시도합니다.

검증 방법:

추가가 성공하면 게임이 정상 시작되고 디버깅 패널에 플러그인 주입 성공 로그가 표시됩니다.

문제 3: “코드 패키지 압축 해제 실패” 또는 “로그인 사용자가 개발자가 아님”

증상:

미리보기나 업로드 시 다음과 같은 오류가 납니다.

Code package unpacking failed. Please check the code package.

또는:

The logged-in user is not a developer of this mini program.

원인:

appid 설정이 잘못되었거나, 현재 로그인한 WeChat 계정에 해당 미니게임의 개발자 권한이 없습니다.

해결 단계:

1. appid가 올바른지 확인합니다. 범용 테스트 id가 아니어야 합니다.
2. WeChat Official Accounts Platform에 로그인해, 현재 WeChat 계정에 개발자 권한이 있는지 확인합니다.
3. 권한이 없다면 관리자에게 개발자로 추가해 달라고 요청합니다.
4. 권한이 있는 WeChat 계정으로 WeChat Developer Tools에 다시 로그인합니다.

검증 방법:

실제 기기 미리보기가 정상 실행되면 권한 설정이 올바른 것입니다.

문제 4: 낮은 버전 WeChat에서 정상 실행되지 않음

증상:

엔진 플러그인을 설정했고 실제 기기 테스트도 정상입니다. 하지만 출시 후 일부 사용자가 게임이 시작되지 않거나 시작이 매우 느리다고 피드백합니다.

원인:

WeChat 7.0.7 미만 버전은 엔진 플러그인을 지원하지 않습니다. 이 사용자가 게임을 열면 엔진 플러그인이 적용되지 않고, 엔진 코드를 여전히 전체 다운로드해야 합니다. 메인 패키지가 원래 4M 제한에 가까웠다면 전체 엔진이 포함되면서 초과되어 시작하지 못할 수 있습니다.

해결 단계:

두 가지 선택지가 있습니다.

방안 A: 전체 엔진 코드 유지(낮은 버전 호환)

빌드 패널에서 “Separate Engine”에 해당하는 옵션을 선택하지 않습니다. 이렇게 하면 엔진 코드가 메인 패키지에 전체 포함되어 모든 WeChat 버전에서 실행할 수 있습니다. 대신 메인 패키지가 커지므로 리소스 최적화를 함께 해야 합니다.

방안 B: 사용자에게 WeChat 업그레이드 안내

게임 시작 시 WeChat 버전을 감지하고, 7.0.7보다 낮으면 “최상의 경험을 위해 WeChat을 최신 버전으로 업그레이드해 주세요”라는 안내를 표시합니다. 사용자가 업그레이드하면 엔진 플러그인이 적용됩니다.

대부분의 개발자는 방안 A를 선택합니다. 호환성이 더 중요하기 때문입니다.

검증 방법:

WeChat 7.0.6 이하 버전이 설치된 휴대폰을 찾아 실제 기기 테스트를 합니다. 게임이 정상 시작되면 호환 처리가 올바른 것입니다.

문제 5: 커스텀 엔진은 엔진 플러그인을 사용할 수 없음

증상:

Cocos Creator에서 커스텀 엔진을 사용하고 있습니다. 직접 엔진 소스 코드를 수정한 상태입니다. “Separate Engine” 옵션을 선택한 뒤 빌드가 실패하거나, 빌드는 성공하지만 플러그인이 적용되지 않습니다.

원인:

엔진 플러그인은 Cocos Creator에 내장된 공식 엔진 버전만 지원합니다. 커스텀 엔진은 WeChat의 공용 엔진 플러그인 라이브러리에 연결할 수 없습니다.

해결 단계:

두 가지 선택지가 있습니다.

방안 A: 내장 엔진으로 전환

커스텀 수정이 많지 않다면, 수정한 부분을 게임 코드 쪽으로 옮기고 커스텀 엔진을 포기한 뒤 내장 엔진 + 엔진 플러그인을 사용하는 방법을 시도할 수 있습니다.

방안 B: 엔진 플러그인 기능 포기

커스텀 엔진 변경 폭이 크고 반드시 유지해야 한다면 엔진 플러그인을 포기합니다. 엔진 코드는 메인 패키지에 전체 포함하고, 리소스 최적화로 패키지 크기를 제어합니다.

검증 방법:

빌드 패널에서 “Use Custom Engine”에 해당하는 옵션이 선택되어 있는지 확인합니다. 선택되어 있다면 엔진 플러그인 기능은 적용되지 않습니다.

엔진 플러그인과 패키지 최적화를 함께 적용하는 방법

앞의 네 장을 읽고 나면 이런 생각이 들 수 있습니다. 엔진 플러그인을 활성화하면 패키지 크기가 바로 1~2M 줄어드는 것 아닌가?

여기서 한 가지를 분명히 해야 합니다. 엔진 코드는 분리되더라도 첫 패키지 크기에는 여전히 포함됩니다.

WeChat의 규칙은 이렇습니다. 첫 패키지 제한은 4M, 전체 패키지 제한은 30M입니다. 엔진 플러그인 모드에서 엔진 코드는 “실제 다운로드량”에는 포함되지 않지만, “첫 패키지 선언 크기”에는 포함됩니다. 즉 메인 패키지에 엔진 코드를 더했을 때 4M을 넘으면 여전히 반려될 수 있습니다.

그래서 엔진 플러그인은 최적화 흐름의 첫 단계일 뿐입니다. 4M 제한을 실제로 넘기려면 다른 최적화 수단도 함께 적용해야 합니다.

패키지 구성 분석

먼저 전형적인 미니게임의 패키지 구성을 보겠습니다.

유형	비중	설명
텍스처 리소스	45%	PNG 이미지, 스프라이트 시트
오디오 파일	25%	WAV, MP3, OGG
폰트 파일	15%	TTF 폰트
엔진 코드	10%	Cocos Creator 엔진
기타	5%	설정 파일, JSON

텍스처 리소스의 비중이 가장 높으므로 최적화의 핵심입니다. 엔진 코드는 10%에 불과하지만, 플러그인으로 분리하면 이 부분은 다른 게임에도 이점을 줍니다.

전체 최적화 흐름

6M 이상에서 3M 아래로 줄이고 싶다면, 시스템적으로 네 가지를 해야 합니다.

1단계: 엔진 분리(앞에서 설명)

엔진 플러그인을 활성화해 엔진 코드를 매번 전체 다운로드하지 않게 합니다. 가장 쉬운 단계이며 설정을 선택하면 됩니다.

2단계: 텍스처 최적화

텍스처 리소스는 패키지의 45%를 차지하므로 효과가 가장 큽니다.

• TinyPNG로 PNG 이미지를 압축합니다. 온라인 도구나 CLI 도구를 사용할 수 있습니다.
• TexturePacker로 스프라이트 시트를 만들 때 RGBA4444 형식을 선택합니다. 용량을 50% 줄일 수 있습니다.
• “Allow Rotation”을 선택하면 스프라이트 시트 활용률을 15% 높일 수 있습니다.

2M 텍스처 패키지는 최적화 후 1M 정도만 남을 수 있습니다.

3단계: 오디오 다운그레이드

오디오 파일은 패키지의 25%를 차지합니다. 많은 사람이 WAV 형식을 쓰지만, 용량이 크고 대부분의 경우 그럴 필요가 없습니다.

• 배경 음악: WAV를 OGG Vorbis Q5로 변환합니다. 품질은 충분하고 용량은 70% 줄어듭니다.
• 효과음: MP3 96kbps를 사용합니다. 용량을 65% 줄일 수 있습니다.

1.7M 오디오 리소스는 최적화 후 0.5M 정도로 줄어들 수 있습니다.

4단계: 코드 트리밍

Cocos Creator의 엔진 모듈 중에는 실제로 쓰지 않는 것이 많을 수 있습니다.

• 2D 게임이라면 3D 모듈을 제거할 수 있습니다.
• 싱글플레이 게임이라면 네트워크 모듈을 제거할 수 있습니다.
• 간단한 매치 퍼즐 게임이라면 물리 엔진을 제거할 수 있습니다.
• 디버그 기간에는 통계 모듈을 유지하고, 출시 시 제거할 수 있습니다.

빌드 패널의 “Engine Module Trimming” 영역에서 필요한 모듈만 선택합니다. 선택하지 않은 모듈은 제거됩니다.

함께 최적화했을 때의 실제 효과

앞에서 언급한 캐주얼 러닝 게임 프로젝트 사례로 돌아가 보겠습니다.

최적화 항목	최적화 전	최적화 후	감소량
텍스처 리소스	3.06M	1.02M	2.04M
오디오 파일	1.7M	0.5M	1.2M
엔진 코드	0.68M	플러그인 분리	캐시 재사용
폰트 파일	1.02M	0.34M(서브셋화)	0.68M
전체 패키지	6.8M	3.2M	53% 감소

첫 화면 로딩 시간은 5초에서 3초로 줄어 40% 빨라졌습니다.

이 방식의 장점은 각 최적화 항목이 독립적으로 효과를 낸다는 점입니다. 한 번에 모두 끝낼 필요는 없습니다. 먼저 엔진 플러그인을 적용해 효과를 보고, 다음으로 가장 효과가 큰 텍스처 최적화를 진행하면서 단계적으로 밀고 가면 됩니다.

물론 프로젝트마다 상황은 다릅니다. 어떤 게임은 텍스처 비중이 더 높고, 어떤 게임은 오디오가 더 많습니다. 먼저 빌드 패널에서 패키지 구성을 분석한 뒤, 병목이 큰 항목부터 최적화하는 편이 좋습니다.

결론

엔진 플러그인은 WeChat 미니게임 시작 최적화의 첫 단계이자 가장 쉬운 단계입니다. 설정만 선택하면 되고 코드를 수정할 필요가 없습니다.

하지만 엔진 플러그인만으로는 충분하지 않습니다. 메인 패키지가 원래 4M에 가까웠고 전체 엔진을 포함하면 제한을 넘는다면, 낮은 버전의 WeChat 사용자는 게임을 아예 열지 못할 수 있습니다.

실제로 효과적인 접근은 다음과 같습니다.

1. 먼저 엔진 플러그인을 활성화해 높은 버전 WeChat 사용자의 경험을 개선합니다.
2. 패키지 구성을 분석해 텍스처, 오디오, 폰트 중 어느 부분의 비중이 가장 높은지 확인합니다.
3. 항목별로 최적화합니다. 텍스처는 RGBA4444, 오디오는 OGG/MP3, 폰트는 서브셋화를 적용합니다.
4. WeChat 7.0.6 이하 버전에서 실제 기기 테스트를 수행해 호환성을 확인합니다.
5. 최적화 전후 데이터를 정량적으로 비교합니다. 느낌만으로 효과를 판단하지 않습니다.

이 흐름대로 진행하면 6.8M을 3.2M까지 줄이고, 시작 시간을 40% 빠르게 만드는 것도 가능합니다. 플레이어가 몇 초씩 기다리지 않아도 되므로 이탈률도 자연스럽게 내려갑니다.

저도 이 문제들을 직접 겪었고, 적지 않은 시간을 들여 하나씩 확인했습니다. 전체 흐름을 정리한 이유는 당신이 그 시간을 조금이라도 줄였으면 해서입니다. 궁금한 점이 있으면 댓글로 남겨 주세요. 가능한 한 답하겠습니다.