unreal-engine-mcp-server 0.5.4 → 0.5.5

package/docs/Roadmap.md

@@ -1,53 +0,0 @@
-# Roadmap for Unreal Engine MCP Server
-
-This roadmap outlines the development plan for expanding the capabilities of the Unreal Engine Model Context Protocol (MCP) server.
-
-## Phase 1: Architecture & Foundation (✅ Completed)
-
-- [x] **Native C++ Bridge**: Replace Python-based bridge with native C++ WebSocket plugin.
-- [x] **Consolidated Tools**: Unify disparate tools into cohesive domains (`manage_asset`, `control_actor`, etc.).
-- [x] **Modular Server**: Refactor monolithic `index.ts` into specialized subsystems (`ServerSetup`, `HealthMonitor`, `ResourceHandler`).
-- [x] **WASM Acceleration**: Integrate Rust/WASM for high-performance JSON parsing and math.
-- [x] **Robust Error Handling**: Standardize error responses, codes, and logging.
-- [x] **Offline Capabilities**: Implement file-based fallback for project settings (`DefaultEngine.ini`).
-
-## Phase 2: Graph & Logic Automation (✅ Completed)
-
-- [x] **Blueprint Graphs**: Add/remove nodes, pins, and properties (`manage_blueprint_graph`).
-- [x] **Material Graphs**: Edit material expressions and connections (`manage_material_graph`).
-- [x] **Niagara Graphs**: Edit emitters, modules, and parameters (`manage_niagara_graph`).
-- [x] **Behavior Trees**: Edit AI behavior trees, tasks, and decorators (`manage_behavior_tree`).
-- [x] **Environment**: Unified environment builder (`build_environment`) for landscape, foliage, and proc-gen.
-
-## Phase 3: Cinematic & Visual Automation (✅ Completed)
-
-- [x] **Sequencer**: Full control over Level Sequences (create, play, tracks, keys, bindings).
-- [x] **Audio**: Create SoundCues, play sounds, set mixes (`create_sound_cue`, `play_sound_at_location`).
-- [x] **Landscape**: Sculpting, painting layers, modifying heightmaps (`sculpt_landscape`, `paint_landscape_layer`).
-- [x] **Foliage**: Painting foliage instances and procedural spawning (`paint_foliage`).
-
-## Phase 4: System & Developer Experience (Current)
-
-- [x] **GraphQL API**: Read/write access to assets and actors via GraphQL.
-- [x] **Pipeline Integration**: Direct UBT execution with output streaming.
-- [x] **Documentation**: Comprehensive handler mappings and API references.
-- [ ] **Real-time Streaming**: Streaming logs and test results via SSE or chunked responses.
-- [ ] **Advanced Rendering**: Nanite/Lumen-specific tools (partially implemented).
-- [x] **Metrics Dashboard**: `ue://health` view backed by bridge/server metrics.
-- [x] **UE 5.7 Support**: Full compatibility with Unreal Engine 5.7 (Control Rig, Subobject Data).
-
-## Phase 5: Future Horizons
-
-- [ ] **WASM Expansion**: Move more tools (for example, graph handlers) into Rust/WASM for performance and safety.
-- [x] **GraphQL Leverage**: Let tools query via GraphQL (for example, asset search) and explore schema stitching for composite APIs.
-- [x] **Monitoring & Metrics**: Prometheus-compatible endpoint for tool latency/errors and bridge metrics (pending requests, queue depth).
-- [ ] **Extensibility Framework**: Dynamic handler registry via JSON config and support for custom C++ handlers via plugins.
-- [ ] **Remote Profiling**: Deep integration with Unreal Insights for remote performance tuning.
-- [ ] **AI-Driven Optimization**: Automated asset auditing and optimization suggestions.
-- [ ] **Packaged Build Control**: Limited control over packaged executables (via sidecar or IPC).
-
-## Legend
-
-- ✅ **Completed**: Feature is implemented and verified.
-- 🚧 **In Progress**: Feature is under active development.
-- 📅 **Planned**: Feature is scheduled for a future release.

package/docs/WebAssembly-Integration.md

@@ -1,628 +0,0 @@
-# WebAssembly Integration for Performance-Critical Operations
-
-## Overview
-
-WebAssembly (WASM) is a binary instruction format for a stack-based virtual machine, designed for high-performance applications. Integrating WebAssembly into the Unreal Engine MCP Server will provide significant performance improvements for computational-heavy operations.
-
-## Performance Benefits
-
-### Current TypeScript Performance
-
-| Operation | Approximate Time | Limitations |
-|-----------|------------------|-------------|
-| Property parsing (1000 props) | ~150-300ms | Large JSON parsing overhead |
-| Asset dependency resolution | ~500-1000ms | Recursive traversal bottleneck |
-| Transform calculations | ~5-10ms | Per-object processing |
-| Blueprint compilation validation | ~200-500ms | Complex string parsing |
-| Bulk actor queries (500 actors) | ~800-1200ms | Object serialization cost |
-
-### Projected WASM Performance
-
-| Operation | Approximate Time | Improvement |
-|-----------|------------------|-------------|
-| Property parsing (1000 props) | ~20-40ms | **5-8x faster** |
-| Asset dependency resolution | ~100-200ms | **3-5x faster** |
-| Transform calculations | ~1-2ms | **5x faster** |
-| Blueprint compilation validation | ~50-100ms | **4x faster** |
-| Bulk actor queries (500 actors) | ~200-300ms | **3-4x faster** |
-
-## Integration Strategy
-
-### 1. Target Operations for WASM
-
-#### High-Priority Operations (Immediate Implementation)
-
-1. **Property Parsing and Serialization**
-   - Parse complex property hierarchies
-   - Serialize/deserialize Blueprint data
-   - Transform property values between formats
-
-2. **Asset Dependency Resolution**
-   - Traverse dependency graphs
-   - Detect circular dependencies
-   - Calculate dependency depth and relationships
-
-3. **Transform Calculations**
-   - Vector math (addition, subtraction, multiplication, division)
-   - Matrix transformations
-   - Rotation conversions (Euler → Quaternion → Matrix)
-   - Transform composition and decomposition
-
-4. **Data Validation**
-   - Blueprint node structure validation
-   - Property type checking
-   - Schema validation for complex objects
-
-#### Medium-Priority Operations (Phase 2)
-
-1. **Bulk Object Processing**
-   - Batch process multiple assets
-   - Parallel transform calculations
-   - Bulk property updates
-
-2. **Path Manipulation**
-   - Resolve asset paths
-   - Normalize path formats
-   - Path pattern matching
-
-3. **String Processing**
-   - Blueprint name generation
-   - Pattern matching for assets
-   - Tokenization of complex strings
-
-### 2. Technology Stack
-
-#### Rust → WebAssembly
-
-**Why Rust?**
-- Excellent WebAssembly support via `wasm-bindgen`
-- Memory safety without garbage collection
-- Zero-cost abstractions
-- Strong performance characteristics
-- Great tooling (`cargo`, `wasm-pack`)
-
-**Alternative Options:**
-- **C/C++**: Direct compilation to WebAssembly
-  - Pros: Mature ecosystem, direct control
-  - Cons: Manual memory management, more complex build setup
-- **AssemblyScript**: TypeScript-like syntax
-  - Pros: Familiar syntax for JS developers
-  - Cons: Less mature, some TypeScript features not supported
-
-#### Recommendation: **Rust**
-
-### 3. Architecture Design
-
-```
-┌─────────────────────────────────────┐
-│  TypeScript Layer                   │
-│  - API Layer                        │
-│  - Validation                       │
-│  - Error Handling                   │
-│  - Fallback Logic                   │
-└─────────────┬───────────────────────┘
-              │ wasm-bindgen
-              │ (function calls)
-┌─────────────▼───────────────────────┐
-│  WebAssembly Module                 │
-│  - Property parsing                 │
-│  - Dependency resolution            │
-│  - Transform math                   │
-│  - Data validation                  │
-└─────────────┬───────────────────────┘
-              │ FFI calls
-┌─────────────▼───────────────────────┐
-│  Rust Core                          │
-│  - Zero-cost abstractions          │
-│  - Memory safety                   │
-│  - High performance                │
-└─────────────────────────────────────┘
-```
-
-### 4. Project Structure
-
-```
-wasm/
-├── Cargo.toml                 # Rust project configuration
-├── src/
-│   ├── lib.rs                 # Entry point
-│   ├── property_parser.rs     # Property parsing functions
-│   ├── dependency_resolver.rs # Dependency graph traversal
-│   ├── transform_math.rs      # Vector/matrix calculations
-│   ├── validation.rs          # Data validation functions
-│   └── utils.rs               # Utility functions
-├── package.json               # Node.js integration
-├── build.rs                   # Build script
-├── README.md                  # Build instructions
-└── tests/
-    └── integration.rs         # Rust tests
-```
-
-### 5. Implementation Details
-
-#### 5.1 Rust Library (`src/lib.rs`)
-
-```rust
-use wasm_bindgen::prelude::*;
-use serde::{Serialize, Deserialize};
-
-#[wasm_bindgen]
-pub struct PropertyParser {
-    // Internal state
-}
-
-#[wasm_bindgen]
-impl PropertyParser {
-    #[wasm_bindgen(constructor)]
-    pub fn new() -> PropertyParser {
-        PropertyParser { }
-    }
-
-    #[wasm_bindgen]
-    pub fn parse_properties(&self, json_str: &str) -> Result<JsValue, JsValue> {
-        // Parse JSON efficiently using serde
-        // Return structured data
-    }
-
-    #[wasm_bindgen]
-    pub fn serialize_properties(&self, properties: &JsValue) -> Result<String, JsValue> {
-        // Serialize back to JSON
-    }
-}
-
-#[wasm_bindgen]
-pub struct TransformCalculator {
-    // Transform calculation state
-}
-
-#[wasm_bindgen]
-impl TransformCalculator {
-    #[wasm_bindgen(constructor)]
-    pub fn new() -> TransformCalculator {
-        TransformCalculator { }
-    }
-
-    #[wasm_bindgen]
-    pub fn compose_transform(
-        &self,
-        location: &[f32; 3],
-        rotation: &[f32; 3],
-        scale: &[f32; 3]
-    ) -> Vec<f32> {
-        // Efficient matrix composition
-    }
-
-    #[wasm_bindgen]
-    pub fn decompose_transform(&self, matrix: &[f32; 16]) -> Vec<f32> {
-        // Extract location, rotation, scale
-    }
-}
-```
-
-#### 5.2 TypeScript Integration (`src/wasm/`)
-
-```typescript
-import init, { PropertyParser, TransformCalculator } from './pkg/unreal_mcp_wasm.js';
-
-interface WASMModule {
-  propertyParser: PropertyParser;
-  transformCalculator: TransformCalculator;
-  initialized: boolean;
-}
-
-class WASMIntegration {
-  private module: WASMModule | null = null;
-
-  async initialize(): Promise<void> {
-    if (this.module?.initialized) {
-      return;
-    }
-
-    try {
-      // Load the WASM module
-      const wasmModule = await init();
-
-      this.module = {
-        propertyParser: new PropertyParser(),
-        transformCalculator: new TransformCalculator(),
-        initialized: true
-      };
-
-      console.log('WebAssembly module initialized successfully');
-    } catch (error) {
-      console.error('Failed to initialize WebAssembly module:', error);
-      // Fallback to TypeScript implementation
-      this.module = null;
-      throw error;
-    }
-  }
-
-  isInitialized(): boolean {
-    return this.module?.initialized === true;
-  }
-
-  // Property parsing with WASM fallback
-  async parseProperties(jsonStr: string): Promise<any> {
-    if (!this.module) {
-      await this.initialize();
-    }
-
-    if (this.module) {
-      try {
-        return this.module.propertyParser.parse_properties(jsonStr);
-      } catch (error) {
-        console.warn('WASM property parsing failed, falling back to TypeScript:', error);
-        // Fallback to TypeScript implementation
-      }
-    }
-
-    // TypeScript fallback
-    return JSON.parse(jsonStr);
-  }
-
-  // Transform calculations with WASM
-  composeTransform(
-    location: [number, number, number],
-    rotation: [number, number, number],
-    scale: [number, number, number]
-  ): Float32Array {
-    if (!this.module) {
-      throw new Error('WASM module not initialized');
-    }
-
-    try {
-      return this.module.transformCalculator.compose_transform(
-        location,
-        rotation,
-        scale
-      );
-    } catch (error) {
-      console.warn('WASM transform calculation failed, falling back to TypeScript:', error);
-      // TypeScript fallback implementation
-      return this.fallbackComposeTransform(location, rotation, scale);
-    }
-  }
-
-  private fallbackComposeTransform(
-    location: [number, number, number],
-    rotation: [number, number, number],
-    scale: [number, number, number]
-  ): Float32Array {
-    // Pure TypeScript implementation
-    const [x, y, z] = location;
-    const [pitch, yaw, roll] = rotation;
-    const [sx, sy, sz] = scale;
-
-    // Create transformation matrix
-    const matrix = new Float32Array(16);
-    // ... matrix composition logic
-    return matrix;
-  }
-}
-
-export const wasmIntegration = new WASMIntegration();
-```
-
-### 6. Build System
-
-#### 6.1 Cargo.toml
-
-```toml
-[package]
-name = "unreal-mcp-wasm"
-version = "0.1.0"
-edition = "2021"
-
-[lib]
-crate-type = ["cdylib"]
-
-[dependencies]
-wasm-bindgen = "0.2"
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
-js-sys = "0.3"
-
-[dependencies.web-sys]
-version = "0.3"
-features = ["console"]
-
-[dev-dependencies]
-wasm-bindgen-test = "0.3"
-
-[profile.release]
-opt-level = 3
-lto = true
-codegen-units = 1
-```
-
-#### 6.2 Build Script (`build.rs`)
-
-```rust
-use wasm_pack::wasm_pack;
-
-fn main() {
-    wasm_pack::build_package(&wasm_pack::Target::Web);
-}
-```
-
-#### 6.3 NPM Build Script
-
-```json
-{
-  "scripts": {
-    "build:wasm": "wasm-pack build wasm --target web --out-dir src/wasm/pkg",
-    "build": "npm run build:wasm && tsc",
-    "dev:wasm": "wasm-pack build wasm --target web --out-dir src/wasm/pkg --watch",
-    "test:wasm": "cd wasm && cargo test"
-  }
-}
-```
-
-### 7. Performance Optimizations
-
-#### 7.1 Memory Management
-
-- **Reuse Memory**: Avoid frequent allocation/deallocation
-- **Typed Arrays**: Use `Float32Array`, `Int32Array` for numerical data
-- **Struct of Arrays (SoA)**: Better cache locality than Array of Structs (AoS)
-- **Memory Pooling**: Pre-allocate buffers for frequently used operations
-
-#### 7.2 SIMD Instructions
-
-Use SIMD (Single Instruction, Multiple Data) for parallel operations:
-
-```rust
-#[cfg(target_feature = "simd128")]
-use wasm_bindgen::prelude::wasm_bindgen_simd;
-
-#[wasm_bindgen]
-pub fn batch_transform_actors(actors: &[Actor]) -> Vec<Matrix> {
-    // Use SIMD for parallel transform calculations
-}
-```
-
-#### 7.3 Parallel Processing
-
-For bulk operations, use Web Workers:
-
-```typescript
-// wasm-worker.ts
-import { wasmIntegration } from '../wasm-integration';
-
-self.onmessage = async (e) => {
-  const { operation, data } = e.data;
-
-  if (operation === 'batch_transform') {
-    const results = await wasmIntegration.batchTransform(data);
-    self.postMessage({ success: true, results });
-  }
-};
-```
-
-### 8. Error Handling and Fallbacks
-
-#### 8.1 Graceful Degradation
-
-```typescript
-async function withWASMFallback<T>(
-  wasmOperation: () => Promise<T>,
-  tsFallback: () => Promise<T>,
-  operationName: string
-): Promise<T> {
-  try {
-    if (wasmIntegration.isInitialized()) {
-      return await wasmOperation();
-    }
-  } catch (error) {
-    console.warn(`${operationName} failed with WASM, falling back to TypeScript:`, error);
-  }
-
-  return await tsFallback();
-}
-```
-
-#### 8.2 Feature Detection
-
-```typescript
-function detectWASMSupport(): boolean {
-  return typeof WebAssembly === 'object' &&
-         typeof WebAssembly.instantiate === 'function' &&
-         typeof SharedArrayBuffer !== 'undefined'; // For advanced features
-}
-```
-
-### 9. Testing Strategy
-
-#### 9.1 Rust Tests (`wasm/tests/integration.rs`)
-
-```rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_property_parser() {
-        let parser = PropertyParser::new();
-        let json = r#"{"name": "Test", "value": 42}"#;
-        let result = parser.parse_properties(json).unwrap();
-        // Verify result
-    }
-
-    #[test]
-    fn test_transform_composition() {
-        let calc = TransformCalculator::new();
-        let location = [0.0, 0.0, 0.0];
-        let rotation = [0.0, 0.0, 0.0];
-        let scale = [1.0, 1.0, 1.0];
-
-        let matrix = calc.compose_transform(location, rotation, scale);
-        assert_eq!(matrix.len(), 16);
-    }
-}
-```
-
-#### 9.2 TypeScript Tests
-
-```typescript
-import { wasmIntegration } from '../src/wasm-integration';
-
-describe('WASM Integration', () => {
-  beforeAll(async () => {
-    await wasmIntegration.initialize();
-  });
-
-  test('property parsing performance', async () => {
-    const properties = { /* test data */ };
-    const start = performance.now();
-
-    const result = await wasmIntegration.parseProperties(JSON.stringify(properties));
-
-    const end = performance.now();
-    expect(end - start).toBeLessThan(50); // Should be under 50ms
-  });
-
-  test('transform calculation accuracy', () => {
-    const location = [100, 200, 300];
-    const rotation = [0, 90, 0];
-    const scale = [1, 1, 1];
-
-    const result = wasmIntegration.composeTransform(location, rotation, scale);
-
-    // Verify transformation matrix is correct
-    expect(result[12]).toBe(100); // X translation
-    expect(result[13]).toBe(200); // Y translation
-    expect(result[14]).toBe(300); // Z translation
-  });
-});
-```
-
-### 10. Deployment
-
-#### 10.1 Build Pipeline
-
-1. **Rust Compilation**
-   ```bash
-   wasm-pack build --release --target web
-   ```
-
-2. **Binary Optimization**
-   ```bash
-   # Strip debug info
-   wasm-strip pkg/unreal_mcp_wasm_bg.wasm
-   ```
-
-3. **TypeScript Compilation**
-   ```bash
-   tsc --project tsconfig.json
-   ```
-
-#### 10.2 Distribution
-
-```
-dist/
-├── index.js
-├── cli.js
-├── wasm/
-│   ├── pkg/
-│   │   ├── unreal_mcp_wasm.js
-│   │   ├── unreal_mcp_wasm_bg.wasm
-│   │   └── unreal_mcp_wasm_bg.wasm.d.ts
-│   └── index.d.ts
-└── ...
-```
-
-### 11. Monitoring and Metrics
-
-#### 11.1 Performance Monitoring
-
-```typescript
-class WASMPerformanceMonitor {
-  private metrics = new Map<string, number[]>();
-
-  measureOperation(operation: string, fn: () => Promise<any>): Promise<any> {
-    const start = performance.now();
-
-    return fn().then(result => {
-      const end = performance.now();
-      const duration = end - start;
-
-      if (!this.metrics.has(operation)) {
-        this.metrics.set(operation, []);
-      }
-      this.metrics.get(operation)!.push(duration);
-
-      return result;
-    });
-  }
-
-  getAverageTime(operation: string): number {
-    const times = this.metrics.get(operation) || [];
-    return times.reduce((a, b) => a + b, 0) / times.length;
-  }
-
-  report(): string {
-    const report = [];
-    for (const [operation, times] of this.metrics) {
-      const avg = this.getAverageTime(operation);
-      report.push(`${operation}: ${avg.toFixed(2)}ms (${times.length} samples)`);
-    }
-    return report.join('\n');
-  }
-}
-```
-
-### 12. Migration Plan
-
-#### Phase 1: Core Operations (Weeks 1-2)
-- Implement property parser
-- Add transform calculations
-- Create Rust tests
-- Add TypeScript integration
-
-#### Phase 2: Advanced Features (Weeks 3-4)
-- Implement dependency resolver
-- Add batch operations
-- Optimize memory usage
-- Add performance monitoring
-
-#### Phase 3: Testing and Optimization (Week 5)
-- Comprehensive testing
-- Performance benchmarking
-- Bug fixes
-- Documentation
-
-### 13. Risks and Mitigations
-
-#### Risk 1: WASM Loading Failures
-**Mitigation**: Robust fallback to TypeScript implementations
-
-#### Risk 2: Performance Regression
-**Mitigation**: Comprehensive benchmarking and monitoring
-
-#### Risk 3: Binary Size Bloat
-**Mitigation**: Careful feature selection, tree shaking, compression
-
-#### Risk 4: Compatibility Issues
-**Mitigation**: Feature detection, polyfills, graceful degradation
-
-### 14. Success Metrics
-
-- **Performance**: 3-8x improvement in target operations
-- **Memory Usage**: < 10MB overhead for WASM module
-- **Reliability**: 99.9% success rate with fallbacks
-- **Compatibility**: Works in all modern browsers
-- **Bundle Size**: < 500KB additional bundle size
-
-### 15. Future Enhancements
-
-1. **Threading**: Use SharedArrayBuffer and Web Workers
-2. **Streaming**: Stream large datasets through WASM
-3. **SIMD**: Leverage SIMD instructions for parallel processing
-4. **Custom Allocators**: Implement domain-specific memory allocators
-5. **Caching**: Cache compiled WASM modules for reuse
-
-## Conclusion
-
-WebAssembly integration will provide significant performance improvements for the Unreal Engine MCP Server's most computationally intensive operations. By carefully targeting specific operations and providing robust fallbacks, we can achieve 3-8x performance gains while maintaining full compatibility and reliability.
-
-The Rust-based implementation offers the best balance of performance, safety, and developer productivity. With proper testing, monitoring, and optimization, WASM integration will be a valuable addition to the MCP server's capabilities.