zhongwei/gh-dev-gom-claude-code-marketplace-plugins-unity-editor-toolkit

Fork 0

Files

Zhongwei Li 1da7b24c8e Initial commit

2025-11-29 18:19:28 +08:00

17 KiB

Raw Permalink Blame History

Unity Editor Toolkit - Database Guide

Complete guide for Unity Editor Toolkit's SQLite database integration and real-time GameObject synchronization.

Overview

Unity Editor Toolkit provides a complete SQLite database integration for real-time GameObject synchronization, analytics, and version control capabilities.

Key Features

GUID-based Persistence: GameObjects are identified by persistent GUIDs across Unity sessions
Real-time Synchronization: Auto-sync all loaded scenes every 1 second
Multi-scene Support: Synchronize all loaded scenes simultaneously
Command Pattern: Undo/Redo support for database operations
Auto Migration: Automatic schema migration system
Batch Operations: Efficient bulk operations (500 objects/batch)
Security: SQL injection prevention with parameterized queries and transaction safety

Database Setup

1. Unity Editor Setup

Open Unity Editor Toolkit Server window

Tools > Unity Editor Toolkit > Server Window

Switch to "Database" tab
Click "Connect" to initialize SQLite database
- Database file: {ProjectRoot}/.unity-websocket/unity-editor.db
- Auto-creates schema with migrations
Enable Real-time Sync (Optional)
- Click "Start Sync" for auto-sync (1s interval)
- All loaded scenes are synchronized automatically
- GameObjects automatically tagged with GUID components

2. Database File Location

{ProjectRoot}/
└── .unity-websocket/
    ├── unity-editor.db          # SQLite database
    ├── server-status.json       # WebSocket status
    └── uw.js                    # CLI wrapper

CLI Commands

All database commands run from the Unity project root:

cd <unity-project-root> && node .unity-websocket/uw <command> [options]

Database Management (`db`)

Connect to Database

# Connect and initialize database
cd <unity-project-root> && node .unity-websocket/uw db connect

# Connect with WAL mode disabled (default: enabled)
cd <unity-project-root> && node .unity-websocket/uw db connect --no-wal

WAL Mode (Write-Ahead Logging):

Default: Enabled for better performance
Multiple readers, single writer
Disable with --no-wal for compatibility

Check Database Status

# Get connection and health status
cd <unity-project-root> && node .unity-websocket/uw db status

# Output in JSON format
cd <unity-project-root> && node .unity-websocket/uw db status --json

Output includes:

Connection status
Database file path and existence
Initialization state
Auto-sync status

Disconnect from Database

# Safely disconnect and cleanup
cd <unity-project-root> && node .unity-websocket/uw db disconnect

Reset Database

# Delete and recreate database with fresh migrations
cd <unity-project-root> && node .unity-websocket/uw db reset

# Confirm reset
cd <unity-project-root> && node .unity-websocket/uw db reset --yes

Warning: Deletes all data!

Run Migrations

# Apply pending migrations
cd <unity-project-root> && node .unity-websocket/uw db migrate

# Force re-run all migrations
cd <unity-project-root> && node .unity-websocket/uw db clear-migrations
cd <unity-project-root> && node .unity-websocket/uw db migrate

Scene Synchronization (`sync`)

Sync Entire Scene

# Sync current active scene to database
cd <unity-project-root> && node .unity-websocket/uw sync scene

# Keep existing data (no clear)
cd <unity-project-root> && node .unity-websocket/uw sync scene --no-clear

# Skip components (GameObject only)
cd <unity-project-root> && node .unity-websocket/uw sync scene --no-components

# Skip hierarchy closure table
cd <unity-project-root> && node .unity-websocket/uw sync scene --no-closure

# JSON output
cd <unity-project-root> && node .unity-websocket/uw sync scene --json

Closure Table: Stores parent-child relationships for efficient hierarchy queries.

Sync Specific GameObject

# Sync single GameObject
cd <unity-project-root> && node .unity-websocket/uw sync object "Player"

# Sync with full hierarchy path
cd <unity-project-root> && node .unity-websocket/uw sync object "Environment/Trees/Oak"

# Include children
cd <unity-project-root> && node .unity-websocket/uw sync object "Player" --children

# Skip components
cd <unity-project-root> && node .unity-websocket/uw sync object "Player" --no-components

Check Sync Status

# Get sync status for current scene
cd <unity-project-root> && node .unity-websocket/uw sync status

# JSON output
cd <unity-project-root> && node .unity-websocket/uw sync status --json

Output includes:

Unity object count
Database object count
Component count
Closure record count
In-sync status

Clear Sync Data

# Clear all sync data for current scene
cd <unity-project-root> && node .unity-websocket/uw sync clear

# Confirm clear
cd <unity-project-root> && node .unity-websocket/uw sync clear --yes

Auto-Sync Control

# Start auto-sync (1s interval)
cd <unity-project-root> && node .unity-websocket/uw sync start

# Stop auto-sync
cd <unity-project-root> && node .unity-websocket/uw sync stop

# Get auto-sync status
cd <unity-project-root> && node .unity-websocket/uw sync auto-status

Auto-sync status includes:

Running state
Last sync time
Success/fail counts
Sync interval (ms)
Batch size

Analytics (`analytics`)

Scene Analytics

# Get scene statistics
cd <unity-project-root> && node .unity-websocket/uw analytics scene

# JSON output
cd <unity-project-root> && node .unity-websocket/uw analytics scene --json

Output includes:

Total GameObjects
Total Components
Active vs inactive objects
Object hierarchy depth
Component type distribution

GameObject Analytics

# Get GameObject statistics
cd <unity-project-root> && node .unity-websocket/uw analytics objects

# Filter by active state
cd <unity-project-root> && node .unity-websocket/uw analytics objects --active-only

Component Analytics

# Get component type distribution
cd <unity-project-root> && node .unity-websocket/uw analytics components

# Top N most used components
cd <unity-project-root> && node .unity-websocket/uw analytics components --top 10

Tag Analytics

# Get tag usage statistics
cd <unity-project-root> && node .unity-websocket/uw analytics tags

Layer Analytics

# Get layer usage statistics
cd <unity-project-root> && node .unity-websocket/uw analytics layers

Snapshots (`snapshot`)

Snapshots capture the complete state of GameObjects and Components at a specific point in time.

Create Snapshot

# Create snapshot of current scene
cd <unity-project-root> && node .unity-websocket/uw snapshot create "Before Refactor"

# Create snapshot with description
cd <unity-project-root> && node .unity-websocket/uw snapshot create "v1.0 Release" \
  --description "Scene state before major refactor"

List Snapshots

# List all snapshots
cd <unity-project-root> && node .unity-websocket/uw snapshot list

# JSON output
cd <unity-project-root> && node .unity-websocket/uw snapshot list --json

Get Snapshot Details

# Get snapshot by ID
cd <unity-project-root> && node .unity-websocket/uw snapshot get 1

# JSON output
cd <unity-project-root> && node .unity-websocket/uw snapshot get 1 --json

Compare Snapshots

# Compare two snapshots
cd <unity-project-root> && node .unity-websocket/uw snapshot compare 1 2

# Show differences only
cd <unity-project-root> && node .unity-websocket/uw snapshot compare 1 2 --diff-only

Output includes:

Added objects
Removed objects
Modified objects
Component changes

Restore Snapshot

# Restore scene from snapshot
cd <unity-project-root> && node .unity-websocket/uw snapshot restore 1

# Confirm restore
cd <unity-project-root> && node .unity-websocket/uw snapshot restore 1 --yes

Warning: Overwrites current scene state!

Delete Snapshot

# Delete snapshot by ID
cd <unity-project-root> && node .unity-websocket/uw snapshot delete 1

# Confirm delete
cd <unity-project-root> && node .unity-websocket/uw snapshot delete 1 --yes

Transform History (`transform-history`)

Track position, rotation, and scale changes over time with Undo/Redo support.

Start Recording

# Start recording transform changes
cd <unity-project-root> && node .unity-websocket/uw transform-history start

# Record specific GameObject
cd <unity-project-root> && node .unity-websocket/uw transform-history start "Player"

Stop Recording

# Stop recording
cd <unity-project-root> && node .unity-websocket/uw transform-history stop

Get History

# Get transform history for GameObject
cd <unity-project-root> && node .unity-websocket/uw transform-history get "Player"

# Limit results
cd <unity-project-root> && node .unity-websocket/uw transform-history get "Player" --limit 10

# JSON output
cd <unity-project-root> && node .unity-websocket/uw transform-history get "Player" --json

Compare Transforms

# Compare transform between two timestamps
cd <unity-project-root> && node .unity-websocket/uw transform-history compare "Player" \
  --from "2025-11-19T10:00:00" \
  --to "2025-11-19T11:00:00"

Undo/Redo

# Undo last transform change
cd <unity-project-root> && node .unity-websocket/uw transform-history undo "Player"

# Redo last undone change
cd <unity-project-root> && node .unity-websocket/uw transform-history redo "Player"

# Undo N steps
cd <unity-project-root> && node .unity-websocket/uw transform-history undo "Player" --steps 3

Clear History

# Clear history for specific GameObject
cd <unity-project-root> && node .unity-websocket/uw transform-history clear "Player"

# Clear all history
cd <unity-project-root> && node .unity-websocket/uw transform-history clear-all --yes

Database Schema

Core Tables

`scenes`

Stores scene information.

CREATE TABLE scenes (
    scene_id INTEGER PRIMARY KEY AUTOINCREMENT,
    scene_path TEXT NOT NULL UNIQUE,
    scene_name TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

`gameobjects`

Stores GameObject data with GUID-based identification.

CREATE TABLE gameobjects (
    object_id INTEGER PRIMARY KEY AUTOINCREMENT,
    guid TEXT UNIQUE,                        -- Persistent GUID
    instance_id INTEGER NOT NULL,
    scene_id INTEGER NOT NULL,
    object_name TEXT NOT NULL,
    parent_id INTEGER,
    tag TEXT,
    layer INTEGER,
    is_active BOOLEAN DEFAULT 1,
    is_static BOOLEAN DEFAULT 0,
    is_deleted BOOLEAN DEFAULT 0,            -- Soft delete
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (scene_id) REFERENCES scenes(scene_id)
);

`gameobject_closure`

Stores hierarchy relationships for efficient queries.

CREATE TABLE gameobject_closure (
    ancestor_id INTEGER NOT NULL,
    descendant_id INTEGER NOT NULL,
    depth INTEGER NOT NULL,
    PRIMARY KEY (ancestor_id, descendant_id),
    FOREIGN KEY (ancestor_id) REFERENCES gameobjects(object_id),
    FOREIGN KEY (descendant_id) REFERENCES gameobjects(object_id)
);

`migrations`

Tracks applied schema migrations.

CREATE TABLE migrations (
    migration_id INTEGER PRIMARY KEY AUTOINCREMENT,
    migration_name TEXT NOT NULL UNIQUE,
    applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Migration History

Migration_001: Initial schema (scenes, gameobjects, migrations)
Migration_002: Add GUID column to gameobjects table

Security

SQL Injection Prevention

All database operations use parameterized queries:

// ✓ Safe (parameterized)
connection.Execute("DELETE FROM gameobjects WHERE guid = ?", guid);

// ✗ Unsafe (string concatenation)
connection.Execute($"DELETE FROM gameobjects WHERE guid = '{guid}'");

Batch Operations:

≤100 items: Individual parameterized DELETE statements
100 items: Temporary table pattern with transaction

Transaction Safety

Nested Transaction Prevention:

ExecuteInTransaction(connection, () => {
    // Safe transaction execution
    // Detects and prevents nested transactions
    // Graceful fallback if transaction already started
});

Memory Safety

Domain Reload Safety:

if (!isDisposed)
{
    await UniTask.SwitchToMainThread();
}

Prevents crashes during Unity Domain Reload.

Best Practices

1. Connection Management

# Always check status before operations
cd <unity-project-root> && node .unity-websocket/uw db status

# Connect once at session start
cd <unity-project-root> && node .unity-websocket/uw db connect

# Disconnect at session end
cd <unity-project-root> && node .unity-websocket/uw db disconnect

2. Auto-Sync Usage

When to use:

Active development with frequent GameObject changes
Real-time analytics and monitoring
Multi-scene editing

When to disable:

Performance-critical operations
Large scene modifications (use manual sync)
Prefab editing

3. Snapshot Workflow

# Before major changes
cd <unity-project-root> && node .unity-websocket/uw snapshot create "Before Refactor"

# Make changes...

# If something goes wrong
cd <unity-project-root> && node .unity-websocket/uw snapshot restore 1 --yes

# After successful changes
cd <unity-project-root> && node .unity-websocket/uw snapshot create "After Refactor"

4. Performance Optimization

Batch Operations:

Use sync scene for full scene sync (more efficient than individual objects)
Disable components with --no-components if not needed
Skip closure table with --no-closure for flat hierarchies

Auto-Sync Interval:

Default: 1000ms (1 second)
Adjust in Unity Editor window if needed
Disable during intensive operations

5. Analytics Workflow

# Get scene overview
cd <unity-project-root> && node .unity-websocket/uw analytics scene

# Identify performance issues
cd <unity-project-root> && node .unity-websocket/uw analytics components --top 10

# Check tag/layer usage
cd <unity-project-root> && node .unity-websocket/uw analytics tags
cd <unity-project-root> && node .unity-websocket/uw analytics layers

Troubleshooting

Database Connection Failed

# Check Unity Editor is running
cd <unity-project-root> && node .unity-websocket/uw status

# Check database status
cd <unity-project-root> && node .unity-websocket/uw db status

# Reconnect
cd <unity-project-root> && node .unity-websocket/uw db connect

Sync Issues

# Check sync status
cd <unity-project-root> && node .unity-websocket/uw sync status

# Clear and resync
cd <unity-project-root> && node .unity-websocket/uw sync clear --yes
cd <unity-project-root> && node .unity-websocket/uw sync scene

Migration Errors

# Reset and reapply migrations
cd <unity-project-root> && node .unity-websocket/uw db reset --yes
cd <unity-project-root> && node .unity-websocket/uw db migrate

Performance Issues

# Stop auto-sync
cd <unity-project-root> && node .unity-websocket/uw sync stop

# Use manual sync with optimizations
cd <unity-project-root> && node .unity-websocket/uw sync scene --no-closure

Examples

Complete Workflow Example

# 1. Initialize database
cd /path/to/unity/project
node .unity-websocket/uw db connect

# 2. Sync current scene
node .unity-websocket/uw sync scene

# 3. Create snapshot
node .unity-websocket/uw snapshot create "Initial State"

# 4. Get analytics
node .unity-websocket/uw analytics scene --json

# 5. Start auto-sync
node .unity-websocket/uw sync start

# 6. Make changes in Unity Editor...

# 7. Check sync status
node .unity-websocket/uw sync status

# 8. Create another snapshot
node .unity-websocket/uw snapshot create "After Changes"

# 9. Compare snapshots
node .unity-websocket/uw snapshot compare 1 2

# 10. Cleanup
node .unity-websocket/uw sync stop
node .unity-websocket/uw db disconnect

CI/CD Integration

#!/bin/bash
# Build validation script

cd /path/to/unity/project

# Initialize
node .unity-websocket/uw db connect

# Sync and analyze
node .unity-websocket/uw sync scene
node .unity-websocket/uw analytics scene --json > scene-stats.json

# Validate object count
OBJECT_COUNT=$(cat scene-stats.json | jq '.totalObjects')
if [ "$OBJECT_COUNT" -gt 10000 ]; then
    echo "❌ Scene too complex: $OBJECT_COUNT objects"
    exit 1
fi

# Create snapshot for rollback
node .unity-websocket/uw snapshot create "CI Build $BUILD_NUMBER"

# Cleanup
node .unity-websocket/uw db disconnect

README.md - Main plugin documentation
COMMANDS.md - Complete CLI command reference
SKILL.md - Skill documentation
Unity C# Package - Database implementation

Version: 0.7.0 Last Updated: 2025-11-19 Database Version: Migration_002 (GUID support)

17 KiB Raw Permalink Blame History

Unity Editor Toolkit - Database Guide

Overview

Key Features

Database Setup

1. Unity Editor Setup

2. Database File Location

CLI Commands

Database Management (db)

Connect to Database

Check Database Status

Disconnect from Database

Reset Database

Run Migrations

Scene Synchronization (sync)

Sync Entire Scene

Sync Specific GameObject

Check Sync Status

Clear Sync Data

Auto-Sync Control

Analytics (analytics)

Scene Analytics

GameObject Analytics

Component Analytics

Tag Analytics

Layer Analytics

Snapshots (snapshot)

Create Snapshot

List Snapshots

Get Snapshot Details

Compare Snapshots

Restore Snapshot

Delete Snapshot

Transform History (transform-history)

Start Recording

Stop Recording

Get History

Compare Transforms

Undo/Redo

Clear History

Database Schema

Core Tables

scenes

gameobjects

gameobject_closure

migrations

Migration History

Security

SQL Injection Prevention

Transaction Safety

Memory Safety

Best Practices

1. Connection Management

2. Auto-Sync Usage

3. Snapshot Workflow

4. Performance Optimization

5. Analytics Workflow

Troubleshooting

Database Connection Failed

Sync Issues

Migration Errors

Performance Issues

Examples

Complete Workflow Example

CI/CD Integration

Related Documentation

17 KiB

Raw Permalink Blame History

Database Management (`db`)

Scene Synchronization (`sync`)

Analytics (`analytics`)

Snapshots (`snapshot`)

Transform History (`transform-history`)

`scenes`

`gameobjects`

`gameobject_closure`

`migrations`