# Cocos Gray Screen Debug Flow

> Cocos Creator 3.x Gray/Black Screen Debug Flow

- Skill: `chrislamdev/cocos-gray-screen-debug-flow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chrislamdev/cocos-gray-screen-debug-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chrislamdev/cocos-gray-screen-debug-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: chrislamdev (https://skillmd.com/u/chrislamdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chrislamdev/cocos-gray-screen-debug-flow

---


# 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

```bash
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)

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

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