Cocos VScene – Scene Index & Analysis System

Design Philosophy

VScene = Index (索引) + Analysis (分析)

┌─────────────────────────────────────────────────────────────┐
│                    VScene System                            │
├─────────────────────────┬───────────────────────────────────┤
│   Index Layer (索引层)   │      Analysis Layer (分析层)      │
├─────────────────────────┼───────────────────────────────────┤
│ • Fast lookup           │ • Structure quality scoring       │
│ • Node/Component cache  │ • Code-scene relation analysis    │
│ • Offline capable       │ • Business module identification  │
│ • Minimal context       │ • Self-check & iteration          │
└─────────────────────────┴───────────────────────────────────┘

Commands

Directory Structure

.vscene/
├── manifest.json                    # Scene manifest (场景清单)
├── scenes/
│   └── {sceneName}.json             # Scene index (场景索引)
└── 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

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

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/scoring-rules.md – Detailed scoring criteria

Error Handling