| 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.