Cocos VScene - Scene Index & Analysis System

Design Philosophy

VScene = Index (索引) + Map (地图) + Analysis (分析)

┌──────────────────────────────────────────────────────────────────────────┐
│                           VScene System                                  │
├──────────────────────┬──────────────────────┬────────────────────────────┤
│  Index Layer (索引层) │  Map Layer (地图层)   │   Analysis Layer (分析层)   │
├──────────────────────┼──────────────────────┼────────────────────────────┤
│ • Fast lookup        │ • Key node extract   │ • Structure quality score  │
│ • Node/Component     │ • Bilingual annotate │ • Code-scene relations     │
│ • Offline capable    │ • Smart collapse     │ • Module identification    │
│ • Minimal context    │ • Human+AI readable  │ • Self-check & iteration   │
└──────────────────────┴──────────────────────┴────────────────────────────┘

Commands

* Offline if index exists; auto-pulls (requires MCP) if no index available.

Directory Structure

.vscene/
├── manifest.json                    # Scene manifest (场景清单)
├── scenes/
│   └── {sceneName}.json             # Scene index (场景索引)
├── maps/
│   └── {sceneName}.map.md           # Scene map (场景地图)
└── analysis/
    └── {sceneName}.analysis.md      # Quality analysis (质量分析)

Index Layer (索引层)

VNode Format (Enhanced)

{
  "u": "uuid",
  "n": "NodeName",
  "c": ["GameManager", "AudioSource"],
  "k": true,
  "d": 0,
  "role": "logic",
  "desc": "游戏逻辑根节点",
  "_": []
}

Node Role Classification

Map Layer (地图层)

map Command (Scene Map Generator)

Purpose: Generate a navigable, annotated scene map that both humans and AI can quickly understand. Unlike read (full tree dump), map extracts only the structural skeleton and key nodes, with bilingual (EN/ZH) annotations.

Output: .vscene/maps/{sceneName}.map.md

MCP: ❌ offline if index exists, auto-pulls if not (then needs MCP)

vscene map
  │
  ├─ Step 1: Load Index
  │   └─ If no index → auto pull (requires MCP)
  │
  ├─ Step 2: Filter Nodes (节点筛选)
  │   ├─ Keep all nodes at depth 0-1 (top-level skeleton)
  │   ├─ Keep all key nodes (k=true) at any depth
  │   ├─ Keep ancestor containers of key nodes (path completeness)
  │   ├─ Collapse repeated siblings (Enemy1~10 → [×10 Enemy*])
  │   └─ Aggregate decoration leaves (→ [... N nodes])
  │
  ├─ Step 3: Generate Annotations (注释生成)
  │   ├─ Component-based inference (GameManager → Core game controller / 核心游戏控制器)
  │   ├─ Name-based translation (Player → Player character / 玩家角色)
  │   ├─ Container inference from children (3 Buttons → Button group / 按钮组)
  │   └─ Mark ambiguous names with [?] (weilan → ? / 围栏? [?])
  │
  ├─ Step 4: Render Map Document (渲染地图文档)
  │   ├─ Header: scene info, stats, generation time
  │   ├─ Node Map: annotated tree with smart collapse
  │   ├─ Legend: symbol explanations
  │   ├─ Quick Reference: flat table of key nodes (path/components/purpose)
  │   └─ Stats: total nodes, key nodes shown, collapsed groups
  │
  └─ Output: .vscene/maps/{sceneName}.map.md

Command Variants

vscene map                # Generate map (auto-pull if no index)
vscene map --refresh      # Force regenerate (overwrites existing map)

Node Filtering Rules (节点筛选规则)

Collapse detection for repeated siblings:

Detect pattern: ≥3 siblings sharing a common prefix (case-insensitive)
  Enemy1, Enemy2, Enemy3 → [×3 Enemy*]
  Zone_Oven, Zone_Helper, Zone_Fish → [×3 Zone_*]
  tree, tree (1), tree (2) → [×3 tree*]

Annotation Inference Rules (注释推断规则)

AI generates bilingual # EN / 中文 annotations using 4 strategies (priority order):

1. Component match → GameManager → Game manager / Game管理器
2. Ambiguous detection → node1 → unnamed / 未命名 [?] (checked early to prevent bad translations)
3. Name translation → Player → Player / 玩家
4. Container inference → children are all Buttons → Button group / 按钮组

Full mapping tables: see references/annotation-rules.md

Map Output Template

See references/map-template.md for the full output template.

Key sections:

1. Header — Scene name, generation time, node count summary
2. Node Map — Annotated tree with inline # EN / 中文 comments
3. Legend — Symbol meanings (★, [×N], [...], [?])
4. Quick Reference — Flat table of key nodes with path, components, purpose
5. Stats — Total/shown/collapsed node counts

Analysis Layer (分析层)

analyze Command Flow

vscene analyze
  │
  ├─ Step 1: Check/Load Index
  │   └─ If no index → auto pull
  │
  ├─ Step 2: Structure Analysis (结构分析)
  │   ├─ Hierarchy depth analysis
  │   ├─ Node naming conventions
  │   ├─ Module organization
  │   └─ Component distribution
  │
  ├─ Step 3: Code-Scene Relation Analysis (代码-场景关系分析)
  │   ├─ Grep: getChildByName / find patterns
  │   ├─ Grep: getComponent patterns
  │   ├─ Match code references to scene nodes
  │   └─ Identify missing/orphan references
  │
  ├─ Step 4: Quality Scoring (质量评分)
  │   ├─ Structure Score (结构分)
  │   ├─ Naming Score (命名分)
  │   ├─ Code-Scene Coupling Score (耦合分)
  │   └─ Overall Score (总分)
  │
  ├─ Step 5: Generate Issues & Suggestions (问题与建议)
  │   ├─ Critical issues (严重��题)
  │   ├─ Warnings (警告)
  │   └─ Improvement suggestions (改进建议)
  │
  └─ Output: .vscene/analysis/{sceneName}.analysis.md

Quality Scoring System (评分体系)

Total Score: 100 points

Scoring Rules

Structure Score (30 points)

Naming Score (20 points)

Code-Scene Score (30 points)

Maintainability Score (20 points)

Score Levels

review Command (Self-Check & Iterate)

vscene review
  │
  ├─ Step 1: Load existing analysis
  │
  ├─ Step 2: Verify issues still exist
  │   └─ Re-check each reported issue
  │
  ├─ Step 3: Check if suggestions implemented
  │   └─ Compare with previous analysis
  │
  ├─ Step 4: Update scores
  │   └─ Recalculate based on current state
  │
  └─ Output: Updated analysis with delta

Review Output Example:

## Review: gameScene

### Score Change
| Dimension | Previous | Current | Delta |
|-----------|----------|---------|-------|
| Structure | 22/30 | 25/30 | +3 ✅ |
| Naming | 12/20 | 15/20 | +3 ✅ |
| Code-Scene | 20/30 | 20/30 | 0 |
| Total | 64/100 | 70/100 | +6 ✅ |

### Resolved Issues
- ✅ [S-001] node1 renamed to Environment
- ✅ [N-002] Added Chinese comments

### Remaining Issues
- ⚠️ [C-001] Still has hardcoded path in PlayerController.ts:45

pretty Command (Hierarchy Optimization)

Core Workflow: Analyze → Propose → Confirm → Execute

vscene pretty
  │
  ├─ Phase 1: Analysis (分析阶段)
  │   ├─ Check/Load index (auto pull if needed)
  │   ├─ Detect naming issues (node1, New Node, etc.)
  │   ├─ Detect hierarchy issues (depth > 6, scattered nodes)
  │   ├─ Detect structure issues (ungrouped, mixed concerns)
  │   └─ Generate issue list with severity
  │
  ├─ Phase 2: Proposal (方案生成)
  │   ├─ Generate optimization operations
  │   │   ├─ Rename operations (重命名)
  │   │   ├─ Reparent operations (调整父节点)
  │   │   ├─ Reorder operations (调整顺序)
  │   │   └─ Group operations (分组整理)
  │   ├─ Preview before/after structure
  │   └─ Estimate impact (affected nodes count)
  │
  ├─ Phase 3: Confirmation (用户确认) ⏸️
  │   ├─ Display proposal to user
  │   ├─ Wait for user decision:
  │   │   ├─ "同意" / "执行" → Proceed to Phase 4
  │   │   ├─ "修改" + feedback → Revise proposal
  │   │   └─ "取消" → Abort
  │   └─ User can select specific operations
  │
  └─ Phase 4: Execution (执行阶段)
      ├─ Execute via MCP node_modify
      ├─ Batch operations for efficiency
      ├─ Update local index
      └─ Output: Execution summary

Optimization Rules (优化规则)

1. Naming Optimization (命名优化)

2. Hierarchy Optimization (层级优化)

3. Structure Optimization (结构优化)

Proposal Output Format (方案输出格式)

## VScene Pretty: gameScene

### 检测到的问题 (Issues Found)

| # | 类型 | 节点 | 问题 | 严重度 |
|---|------|------|------|--------|
| 1 | 命名 | `node1` | 无意义命名 | ⚠️ |
| 2 | 命名 | `New Node` | 默认名称 | ⚠️ |
| 3 | 层级 | `A/B/C/D/E/F/G` | 层级过深 (7层) | ❌ |
| 4 | 结构 | `Canvas/PlayerCtrl` | 逻辑组件在UI容器下 | ⚠️ |

### 优化方案 (Optimization Plan)

#### 重命名操作 (Rename)
| # | 原名称 | 新名称 | UUID |
|---|--------|--------|------|
| R1 | `node1` | `Environment` | abc123 |
| R2 | `New Node` | `GameManager` | def456 |

#### 层级调整 (Reparent)
| # | 节点 | 原父节点 | 新父节点 | 原因 |
|---|------|----------|----------|------|
| P1 | `PlayerCtrl` | `Canvas` | `LogicRoot` | 逻辑组件应在逻辑容器 |
| P2 | `DeepNode` | `A/B/C/D/E/F` | `A/B` | 层级扁平化 |

#### 分组操作 (Group)
| # | 新容器 | 包含节点 | 原因 |
|---|--------|----------|------|
| G1 | `Managers` | `GameMgr, AudioMgr, UIMgr` | 管理器分组 |

### 预览 (Preview)

**Before:**

gameScene ├─ node1 ├─ New Node [GameManager] ├─ Canvas │ └─ PlayerCtrl [PlayerController] ⚠️ └─ A/B/C/D/E/F/G ❌

**After:**

gameScene ├─ Environment (原 node1) ├─ LogicRoot │ ├─ GameManager (原 New Node) │ └─ PlayerCtrl ✅ ├─ Canvas └─ A/B/DeepNode ✅

### 影响范围
- 重命名: 2 个节���
- 移动: 2 个节点
- 新建容器: 1 个

---
**请确认是否执行以上优化？**
- 输入 `同意` 或 `执行` 执行全部操作
- 输入 `执行 R1 P1` 执行指定操作
- 输入 `修改` + 反馈 调整方案
- 输入 `取消` 放弃优化

Execution Output (执行结果)

## 执行完成 ✅

### 执行结果
| # | 操作 | 状态 |
|---|------|------|
| R1 | `node1` → `Environment` | ✅ 成功 |
| R2 | `New Node` → `GameManager` | ✅ 成功 |
| P1 | `PlayerCtrl` → `LogicRoot` | ✅ 成功 |

### 索引已更新
场景已保存，建议运行 `vscene analyze` 查看优化后评分。

Analysis Document Template

See references/analysis-template.md for full template.

Key Sections

1. Header - Scene name, stats, score summary
2. Score Card - Detailed scoring breakdown
3. Structure Overview - Annotated hierarchy tree
4. Module Analysis - Business module identification
5. Code-Scene Relations - Reference mapping table
6. Issues & Suggestions - Prioritized improvement list
7. Iteration Log - Review history

Quick Start

First Analysis

vscene pull              # Build index
vscene analyze           # Generate analysis
# Review .vscene/analysis/{scene}.analysis.md

Iterate on Quality

# Make improvements to scene...
vscene review            # Check progress
vscene analyze           # Full re-analysis

Generate Scene Map

vscene map               # Generate annotated scene map
# View .vscene/maps/{scene}.map.md
vscene map --refresh     # Force regenerate

Auto Optimization

vscene pretty            # Analyze and propose optimizations
# Review proposal, then:
# - "同意" to execute all
# - "执行 R1 P1" to execute specific operations
# - "修改" + feedback to revise
# - "取消" to abort

Check Specific Issues

vscene find node*        # Find poorly named nodes
vscene detail <uuid>     # Inspect specific node

Index Output Format

vscene read (depth: 3)

## VScene: gameScene (226 nodes, depth 8)
Cached: 2026-01-26 | Score: 72/100 ⚠️

gameScene                           # 场景根节点
├─ Main Light [DirectionalLight]    # 主光源
├─ Main Camera [CameraComponent]    # 主相机
├─ Canvas [Canvas] ★                # UI 画布
│  ├─ JoystickUI                   # 摇杆控制
│  └─ DragtoMove                   # 拖拽提示
├─ node1                           # ⚠️ 命名不规范
│  └─ [+36 nodes]
└─ LogicRoot ★                     # 逻辑根节点
   ├─ Player ★                     # 玩家角色
   ├─ Unlock ★                     # 解锁系统
   └─ UnlockBuildings ★            # 可解锁建筑

★ = Key node | ⚠️ = Has issues | [+N] = Collapsed

Key Node Detection

Nodes with these components are marked as key (k: true):

Priority 1 (Always):

• *Manager, *Controller, *System, Root
• *Assets, *Factory, *Spawner

Priority 2 (Business):

• *Trigger, *Handler, *Generator
• Any custom component (not cc.* prefixed)

Detailed References

• references/data-structure.md - Full JSON schema
• references/auto-sync.md - Auto-sync flow details
• references/mcp-integration.md - MCP API usage
• references/analysis-template.md - Analysis document template
• references/map-template.md - Scene map output template
• references/annotation-rules.md - Map annotation inference rules

Error Handling