cocos-gray-screen-debug-flow

스타0

포크0

업데이트2026년 7월 4일 01:36

Use when Cocos Creator 3.x shows gray or black screen in Preview mode.

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

출처

ChrisLamDev

ChrisLamDev/cocos-creator-debug-skills

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Cocos Creator 3.x Gray/Black Screen Debug Flow

Use when Cocos Creator Preview or WeChat DevTools shows a completely gray/black/blue screen with no visible UI, even though the scene loads successfully.

Step 1: Check Symptom Type

Turn on Show FPS in Preview toolbar.

Case A: FPS = 60, Draw Call = 0, Game Logic = 0ms

Root cause: Engine runs but script components aren't executing. See references/case-a-script-failure.md.

Case B: FPS = 0 or extremely low

Root cause: Engine or rendering pipeline failure. See references/case-b-render-failure.md.

Step 2: Run Scene Integrity Check

python3 -c "import json; data=json.load(open('assets/scenes/MainScene.scene')); print(f'Objects: {len(data)}'); [print(f'  [{i}] {o.get(\"__type__\",\"\")[:40]}', o.get('_name','')) for i,o in enumerate(data)]"

Step 3: Quick Fixes (try in order)

Quit Cocos Creator (Don't Save) and reopen — clears stale cache
Manually re-create Canvas node — right-click Hierarchy → Create → UI → Canvas, add BootEntry
Check Scene JSON for dead UUID references — see references/uuid-debug.md
Check Camera._near > 0 in scene JSON
Set gfx-webgl2: true in engine.json (macOS M1)

See references/full-debug-flow.md for complete detailed steps.

이 저장소의 다른 Skills

같은 저장소

cocos-creator-headless-install-scene-patch

ChrisLamDev/cocos-creator-debug-skills

Use when installing Cocos Creator 3.x and setting up a headless test bootstrap.

2026-07-040

cocos-cli-build-automation-setup

ChrisLamDev/cocos-creator-debug-skills

Use when setting up a GUI-free CLI build pipeline for Cocos Creator 3.x.

2026-07-040

cocos-code-driven-scrollview-ui

ChrisLamDev/cocos-creator-debug-skills

Use when building code-driven scrollable UI panels in Cocos Creator 3.x.

2026-07-040

cocos-code-driven-ui-common-pitfalls

ChrisLamDev/cocos-creator-debug-skills

Use when code-driven UI nodes in Cocos Creator 3.x fail to render text or colors.

2026-07-040

cocos-creator-cli-build-debug

ChrisLamDev/cocos-creator-debug-skills

Use when Cocos Creator 3.x CLI build fails with scene or library errors.

2026-07-040

cocos-creator-install-and-debug

ChrisLamDev/cocos-creator-debug-skills

Use when installing Cocos Creator 3.x and debugging scene import errors.

2026-07-040

name	cocos-gray-screen-debug-flow
description	Use when Cocos Creator 3.x shows gray or black screen in Preview mode.

Cocos Creator 3.x Gray/Black Screen Debug Flow

Use when Cocos Creator Preview or WeChat DevTools shows a completely gray/black/blue screen with no visible UI, even though the scene loads successfully.

Step 1: Check Symptom Type

Turn on Show FPS in Preview toolbar.

Case A: FPS = 60, Draw Call = 0, Game Logic = 0ms

Root cause: Engine runs but script components aren't executing. See references/case-a-script-failure.md.

Case B: FPS = 0 or extremely low

Root cause: Engine or rendering pipeline failure. See references/case-b-render-failure.md.

Step 2: Run Scene Integrity Check

python3 -c "import json; data=json.load(open('assets/scenes/MainScene.scene')); print(f'Objects: {len(data)}'); [print(f'  [{i}] {o.get(\"__type__\",\"\")[:40]}', o.get('_name','')) for i,o in enumerate(data)]"

Step 3: Quick Fixes (try in order)

Quit Cocos Creator (Don't Save) and reopen — clears stale cache
Manually re-create Canvas node — right-click Hierarchy → Create → UI → Canvas, add BootEntry
Check Scene JSON for dead UUID references — see references/uuid-debug.md
Check Camera._near > 0 in scene JSON
Set gfx-webgl2: true in engine.json (macOS M1)

See references/full-debug-flow.md for complete detailed steps.