unreal-engine-mcp-server 0.2.1

package/src/python/editor_compat.py

@@ -0,0 +1,181 @@
+"""
+Compatibility module for handling deprecated Unreal Engine Python API calls.
+Provides wrapper functions that use the newer recommended APIs where available.
+"""
+
+import unreal
+
+def get_editor_world():
+    """
+    Get the current editor world using the recommended API.
+    """
+    try:
+        # Use new recommended API
+        if hasattr(unreal, 'UnrealEditorSubsystem'):
+            subsystem = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
+            if hasattr(subsystem, 'get_editor_world'):
+                return subsystem.get_editor_world()
+    except:
+        pass
+    
+    return None
+
+def get_all_level_actors():
+    """
+    Get all actors in the current level using the recommended API.
+    """
+    try:
+        # Use new recommended API - EditorActorSubsystem
+        if hasattr(unreal, 'EditorActorSubsystem'):
+            subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+            if hasattr(subsystem, 'get_all_level_actors'):
+                return subsystem.get_all_level_actors()
+    except:
+        pass
+    
+    return []
+
+def spawn_actor_from_class(actor_class, location, rotation):
+    """
+    Spawn an actor in the level using the recommended API.
+    """
+    try:
+        # Use new recommended API
+        if hasattr(unreal, 'EditorActorSubsystem'):
+            subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+            if hasattr(subsystem, 'spawn_actor_from_class'):
+                return subsystem.spawn_actor_from_class(actor_class, location, rotation)
+    except:
+        pass
+    
+    return None
+
+def destroy_actor(actor):
+    """
+    Destroy an actor in the level using the recommended API.
+    """
+    try:
+        # Use new recommended API
+        if hasattr(unreal, 'EditorActorSubsystem'):
+            subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+            if hasattr(subsystem, 'destroy_actor'):
+                return subsystem.destroy_actor(actor)
+    except:
+        pass
+    
+    return False
+
+def save_current_level():
+    """
+    Save the current level using the recommended API.
+    """
+    try:
+        # Use new recommended API - LevelEditorSubsystem
+        if hasattr(unreal, 'LevelEditorSubsystem'):
+            subsystem = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
+            if hasattr(subsystem, 'save_current_level'):
+                return subsystem.save_current_level()
+    except:
+        pass
+    
+    return False
+
+def get_level_viewport_camera_info():
+    """
+    Get level viewport camera information using the recommended API.
+    """
+    try:
+        # Use new recommended API
+        if hasattr(unreal, 'UnrealEditorSubsystem'):
+            subsystem = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
+            if hasattr(subsystem, 'get_level_viewport_camera_info'):
+                return subsystem.get_level_viewport_camera_info()
+    except:
+        pass
+    
+    return None
+
+# Blueprint compatibility functions
+def get_blueprint_generated_class(blueprint):
+    """
+    Get the generated class from a blueprint using the recommended API.
+    """
+    try:
+        # Try using BlueprintEditorLibrary
+        if hasattr(unreal, 'BlueprintEditorLibrary'):
+            return unreal.BlueprintEditorLibrary.generated_class(blueprint)
+    except:
+        pass
+    
+    # Try getting it as a property (might not work)
+    try:
+        return blueprint.get_editor_property('generated_class')
+    except:
+        pass
+    
+    return None
+
+def get_blueprint_parent_class(blueprint):
+    """
+    Get the parent class from a blueprint.
+    """
+    try:
+        # Try getting it as a property
+        return blueprint.get_editor_property('parent_class')
+    except:
+        pass
+    
+    # Default to Actor for most blueprints
+    return unreal.Actor if hasattr(unreal, 'Actor') else None
+
+def get_class_name(unreal_class):
+    """
+    Get the name of an Unreal class object safely.
+    """
+    if not unreal_class:
+        return "None"
+    
+    # Try various methods to get the class name
+    try:
+        if hasattr(unreal_class, '__name__'):
+            return unreal_class.__name__
+    except:
+        pass
+    
+    try:
+        if hasattr(unreal_class, 'get_name'):
+            # get_name() is a method on instances, not classes
+            # So we need to be careful here
+            return str(unreal_class).split('.')[-1].replace("'", "").replace('>', '')
+    except:
+        pass
+    
+    # Fallback to string representation
+    class_str = str(unreal_class)
+    if '.' in class_str:
+        return class_str.split('.')[-1].replace("'", "").replace('>', '')
+    
+    return class_str
+
+def ensure_kismet_system_library():
+    """
+    Try to import KismetSystemLibrary if available.
+    Note: This library might not be available in all UE versions or configurations.
+    """
+    try:
+        # KismetSystemLibrary is part of the BlueprintGraph module
+        # It might not be exposed to Python in all versions
+        if hasattr(unreal, 'KismetSystemLibrary'):
+            return unreal.KismetSystemLibrary
+        
+        # Try alternate import methods
+        import importlib
+        try:
+            kismet = importlib.import_module('unreal.KismetSystemLibrary')
+            return kismet
+        except:
+            pass
+    except:
+        pass
+    
+    return None

package/src/python-utils.ts

@@ -0,0 +1,57 @@
+/**
+ * Python Utilities for Modern Unreal Engine API
+ * 
+ * This module provides Python code snippets that use the modern
+ * Unreal Engine Python API instead of deprecated functions.
+ */
+
+export class PythonUtils {
+  /**
+   * Get all actors in the level using modern API
+   * @returns Python code to get all level actors
+   */
+  static getAllLevelActors(): string {
+    return `
+# Use modern EditorActorSubsystem instead of deprecated EditorLevelLibrary
+editor_actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+actors = editor_actor_subsystem.get_all_level_actors()
+`.trim();
+  }
+
+  /**
+   * Get selected actors using modern API
+   * @returns Python code to get selected actors
+   */
+  static getSelectedActors(): string {
+    return `
+editor_actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+selected_actors = editor_actor_subsystem.get_selected_level_actors()
+`.trim();
+  }
+
+  /**
+   * Spawn actor from class using modern API
+   * @returns Python code to spawn actor
+   */
+  static spawnActorFromClass(): string {
+    return `
+editor_actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+# Use spawn_actor_from_class for spawning
+`.trim();
+  }
+
+  /**
+   * Get a safe way to access actors
+   * @returns Python code with modern API
+   */
+  static getSafeActorAccess(): string {
+    return `
+# Use modern API
+try:
+    editor_actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+    actors = editor_actor_subsystem.get_all_level_actors() if editor_actor_subsystem else []
+except:
+    actors = []
+`.trim();
+  }
+}

package/src/resources/actors.ts

@@ -0,0 +1,92 @@
+import { UnrealBridge } from '../unreal-bridge.js';
+
+interface CacheEntry {
+  data: any;
+  timestamp: number;
+}
+
+export class ActorResources {
+  private cache = new Map<string, CacheEntry>();
+  private readonly CACHE_TTL_MS = 5000; // 5 seconds cache for actors (they change more frequently)
+  
+  constructor(private bridge: UnrealBridge) {}
+  
+  private getFromCache(key: string): any | null {
+    const entry = this.cache.get(key);
+    if (entry && (Date.now() - entry.timestamp) < this.CACHE_TTL_MS) {
+      return entry.data;
+    }
+    this.cache.delete(key);
+    return null;
+  }
+  
+  private setCache(key: string, data: any): void {
+    this.cache.set(key, { data, timestamp: Date.now() });
+  }
+
+  async listActors() {
+    // Check cache first
+    const cached = this.getFromCache('listActors');
+    if (cached !== null) {
+      return cached;
+    }
+    
+    // Use Python to get actors via EditorActorSubsystem
+    try {
+      const pythonCode = `
+import unreal
+actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+actors = actor_subsystem.get_all_level_actors()
+actor_list = []
+for actor in actors:
+    if actor:
+        actor_list.append({
+            'name': actor.get_name(),
+            'class': actor.get_class().get_name(),
+            'path': actor.get_path_name()
+        })
+print(f"Found {len(actor_list)} actors")
+      `.trim();
+      
+      const result = await this.bridge.executePython(pythonCode);
+      this.setCache('listActors', result);
+      return result;
+    } catch (err) {
+      return { error: `Failed to list actors: ${err}` };
+    }
+  }
+
+  async getActorByName(actorName: string) {
+    // GetActorOfClass expects a class, not a name. Use Python to find by name
+    try {
+      const pythonCode = `
+import unreal
+actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+actors = actor_subsystem.get_all_level_actors()
+for actor in actors:
+    if actor and actor.get_name() == "${actorName}":
+        print(f"Found actor: {actor.get_path_name()}")
+        break
+else:
+    print(f"Actor not found: ${actorName}")
+      `.trim();
+      
+      const result = await this.bridge.executePython(pythonCode);
+      return result;
+    } catch (err) {
+      return { error: `Failed to get actor: ${err}` };
+    }
+  }
+
+  async getActorTransform(actorPath: string) {
+    try {
+      const res = await this.bridge.httpCall('/remote/object/property', 'GET', {
+        objectPath: actorPath,
+        propertyName: 'ActorTransform'
+      });
+      return res;
+    } catch (err) {
+      return { error: `Failed to get transform: ${err}` };
+    }
+  }
+}

package/src/resources/assets.ts

@@ -0,0 +1,251 @@
+import { UnrealBridge } from '../unreal-bridge.js';
+
+export class AssetResources {
+  constructor(private bridge: UnrealBridge) {}
+
+  // Simple in-memory cache for asset listing
+  private cache = new Map<string, { timestamp: number; data: any }>();
+  private get ttlMs(): number { return Number(process.env.ASSET_LIST_TTL_MS || 10000); }
+  private makeKey(dir: string, recursive: boolean, page?: number) { 
+    return page !== undefined ? `${dir}::${recursive ? 1 : 0}::${page}` : `${dir}::${recursive ? 1 : 0}`; 
+  }
+
+  async list(dir = '/Game', recursive = false, limit = 50) {
+    // ALWAYS use non-recursive listing to show only immediate children
+    // This prevents timeouts and makes navigation clearer
+    recursive = false; // Force non-recursive
+    
+    // Cache fast-path
+    try {
+      const key = this.makeKey(dir, false);
+      const entry = this.cache.get(key);
+      const now = Date.now();
+      if (entry && (now - entry.timestamp) < this.ttlMs) {
+        return entry.data;
+      }
+    } catch {}
+    
+    // Check if bridge is connected
+    if (!this.bridge.isConnected) {
+      return {
+        assets: [],
+        warning: 'Unreal Engine is not connected. Please ensure Unreal Engine is running with Remote Control enabled.',
+        connectionStatus: 'disconnected'
+      };
+    }
+    
+    // Always use directory-only listing (immediate children)
+    return this.listDirectoryOnly(dir, false, limit);
+    // End of list method - all logic is now in listDirectoryOnly
+  }
+
+  /**
+   * List assets with pagination support
+   * @param dir Directory to list assets from
+   * @param page Page number (0-based)
+   * @param pageSize Number of assets per page (max 50 to avoid socket failures)
+   */
+  async listPaged(dir = '/Game', page = 0, pageSize = 30, recursive = false) {
+    // Ensure pageSize doesn't exceed safe limit
+    const safePageSize = Math.min(pageSize, 50);
+    const offset = page * safePageSize;
+    
+    // Check cache for this specific page
+    const cacheKey = this.makeKey(dir, recursive, page);
+    const cached = this.cache.get(cacheKey);
+    if (cached && (Date.now() - cached.timestamp) < this.ttlMs) {
+      return cached.data;
+    }
+    
+    if (!this.bridge.isConnected) {
+      return {
+        assets: [],
+        page,
+        pageSize: safePageSize,
+        warning: 'Unreal Engine is not connected.',
+        connectionStatus: 'disconnected'
+      };
+    }
+    
+    try {
+      // Use search API with pagination
+      // Use the same directory listing approach but with pagination
+      const allAssets = await this.listDirectoryOnly(dir, false, 1000);
+      
+      // Paginate the results
+      const start = offset;
+      const end = offset + safePageSize;
+      const pagedAssets = allAssets.assets ? allAssets.assets.slice(start, end) : [];
+      
+      const result = {
+        assets: pagedAssets,
+        page,
+        pageSize: safePageSize,
+        count: pagedAssets.length,
+        totalCount: allAssets.assets ? allAssets.assets.length : 0,
+        hasMore: end < (allAssets.assets ? allAssets.assets.length : 0),
+        method: 'directory_listing_paged'
+      };
+      
+      this.cache.set(cacheKey, { timestamp: Date.now(), data: result });
+      return result;
+    } catch (err: any) {
+      console.warn(`Asset listing page ${page} failed:`, err.message);
+    }
+    
+    return {
+      assets: [],
+      page,
+      pageSize: safePageSize,
+      error: 'Failed to fetch page'
+    };
+  }
+
+  /**
+   * Directory-based listing for paths with too many assets
+   * Shows only immediate children (folders and files) to avoid timeouts
+   */
+  private async listDirectoryOnly(dir: string, recursive: boolean, limit: number) {
+    // Always return only immediate children to avoid timeout and improve navigation
+    try {
+      const py = `
+import unreal
+import json
+
+_dir = r"${dir}"
+
+try:
+    # ALWAYS non-recursive - get only immediate children
+    all_paths = unreal.EditorAssetLibrary.list_assets(_dir, False, False)
+    
+    # Organize into immediate children only
+    immediate_folders = set()
+    immediate_assets = []
+    
+    for path in all_paths:
+        # Remove the base directory to get relative path
+        relative = path.replace(_dir, '').strip('/')
+        if not relative:
+            continue
+            
+        # Split to check depth
+        parts = relative.split('/')
+        
+        if len(parts) == 1:
+            # This is an immediate child asset
+            immediate_assets.append(path)
+        elif len(parts) > 1:
+            # This indicates a subfolder exists
+            immediate_folders.add(parts[0])
+    
+    result = []
+    
+    # Add folders first
+    for folder in sorted(immediate_folders):
+        result.append({
+            'n': folder,
+            'p': _dir + '/' + folder,
+            'c': 'Folder',
+            'isFolder': True
+        })
+    
+    # Add immediate assets (limit to prevent socket issues)
+    for asset_path in immediate_assets[:min(${limit}, len(immediate_assets))]:
+        name = asset_path.split('/')[-1].split('.')[0]
+        result.append({
+            'n': name,
+            'p': asset_path,
+            'c': 'Asset'
+        })
+    
+    # Always showing immediate children only
+    note = f'Showing immediate children of {_dir} ({len(immediate_folders)} folders, {len(immediate_assets)} files)'
+    
+    print("RESULT:" + json.dumps({
+        'success': True, 
+        'assets': result, 
+        'count': len(result),
+        'folders': len(immediate_folders),
+        'files': len(immediate_assets),
+        'note': note
+    }))
+except Exception as e:
+    print("RESULT:" + json.dumps({'success': False, 'error': str(e), 'assets': []}))
+`.trim();
+
+      const resp = await this.bridge.executePython(py);
+      let output = '';
+      if (resp?.LogOutput && Array.isArray(resp.LogOutput)) {
+        output = resp.LogOutput.map((l: any) => l.Output || '').join('');
+      } else if (typeof resp === 'string') {
+        output = resp;
+      } else {
+        output = JSON.stringify(resp);
+      }
+      
+      const m = output.match(/RESULT:({.*})/);
+      if (m) {
+        try {
+          const parsed = JSON.parse(m[1]);
+          if (parsed.success) {
+            // Transform to standard format
+            const assets = parsed.assets.map((a: any) => ({
+              Name: a.n,
+              Path: a.p,
+              Class: a.c,
+              isFolder: a.isFolder || false
+            }));
+            
+            return {
+              assets,
+              count: parsed.count,
+              folders: parsed.folders,
+              files: parsed.files,
+              note: parsed.note,
+              method: 'directory_listing'
+            };
+          }
+        } catch {}
+      }
+    } catch (err: any) {
+      console.warn('Engine asset listing failed:', err.message);
+    }
+    
+    // Fallback: return empty with explanation
+    return {
+      assets: [],
+      warning: 'Directory contains too many assets. Showing immediate children only.',
+      suggestion: 'Navigate to specific subdirectories for detailed listings.',
+      method: 'directory_timeout_fallback'
+    };
+  }
+
+  async find(assetPath: string) {
+    // Guard against invalid paths (trailing slash, empty, whitespace)
+    if (!assetPath || typeof assetPath !== 'string' || assetPath.trim() === '' || assetPath.endsWith('/')) {
+      return false;
+    }
+
+    const py = `
+import unreal
+apath = r"${assetPath}"
+try:
+    exists = unreal.EditorAssetLibrary.does_asset_exist(apath)
+    print("RESULT:{'success': True, 'exists': %s}" % ('True' if exists else 'False'))
+except Exception as e:
+    print("RESULT:{'success': False, 'error': '" + str(e) + "'}")
+`.trim();
+    const resp = await this.bridge.executePython(py);
+    let output = '';
+    if (resp?.LogOutput && Array.isArray(resp.LogOutput)) output = resp.LogOutput.map((l: any) => l.Output || '').join('');
+    else if (typeof resp === 'string') output = resp; else output = JSON.stringify(resp);
+    const m = output.match(/RESULT:({.*})/);
+    if (m) {
+      try {
+        const parsed = JSON.parse(m[1].replace(/'/g, '"'));
+        if (parsed.success) return !!parsed.exists;
+      } catch {}
+    }
+    return false;
+  }
+}

package/src/resources/levels.ts

@@ -0,0 +1,83 @@
+import { UnrealBridge } from '../unreal-bridge.js';
+
+export class LevelResources {
+  constructor(private bridge: UnrealBridge) {}
+
+  async getCurrentLevel() {
+    // Use UnrealEditorSubsystem instead of deprecated EditorLevelLibrary
+    try {
+      const py = '\nimport unreal, json\ntry:\n    # Use UnrealEditorSubsystem instead of deprecated EditorLevelLibrary\n    editor_subsys = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)\n    world = editor_subsys.get_editor_world()\n    name = world.get_name() if world else \'None\'\n    path = world.get_path_name() if world else \'None\'\n    print(\'RESULT:\' + json.dumps({\'success\': True, \'name\': name, \'path\': path}))\nexcept Exception as e:\n    print(\'RESULT:\' + json.dumps({\'success\': False, \'error\': str(e)}))\n'.trim();
+      const resp: any = await this.bridge.executePython(py);
+      // Handle LogOutput format from executePython
+      let out = '';
+      if (resp?.LogOutput && Array.isArray(resp.LogOutput)) {
+        out = resp.LogOutput.map((log: any) => log.Output || '').join('');
+      } else if (typeof resp === 'string') {
+        out = resp;
+      } else {
+        out = JSON.stringify(resp);
+      }
+      const m = out.match(/RESULT:({.*})/);
+      if (m) { 
+        const parsed = JSON.parse(m[1]); 
+        if (parsed.success) return parsed;
+      }
+      // If Python failed, return error
+      return { error: 'Failed to get current level', success: false };
+    } catch (err) {
+      return { error: `Failed to get current level: ${err}`, success: false };
+    }
+  }
+
+  async getLevelName() {
+    // Return camera/world info via Python first
+    try {
+      const py = '\nimport unreal, json\ntry:\n    # Use UnrealEditorSubsystem instead of deprecated EditorLevelLibrary\n    editor_subsys = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)\n    world = editor_subsys.get_editor_world()\n    path = world.get_path_name() if world else \'\'\n    print(\'RESULT:\' + json.dumps({\'success\': True, \'path\': path}))\nexcept Exception as e:\n    print(\'RESULT:\' + json.dumps({\'success\': False, \'error\': str(e)}))\n'.trim();
+      const resp: any = await this.bridge.executePython(py);
+      // Handle LogOutput format from executePython
+      let out = '';
+      if (resp?.LogOutput && Array.isArray(resp.LogOutput)) {
+        out = resp.LogOutput.map((log: any) => log.Output || '').join('');
+      } else if (typeof resp === 'string') {
+        out = resp;
+      } else {
+        out = JSON.stringify(resp);
+      }
+      const m = out.match(/RESULT:({.*})/);
+      if (m) { 
+        const parsed = JSON.parse(m[1]); 
+        if (parsed.success) return parsed;
+      }
+      // If Python failed, return error
+      return { error: 'Failed to get level name', success: false };
+    } catch (err) {
+      return { error: `Failed to get level name: ${err}`, success: false };
+    }
+  }
+
+  async saveCurrentLevel() {
+    // Prefer Python save (or LevelEditorSubsystem) then fallback
+    try {
+      const py = '\nimport unreal, json\ntry:\n    les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)\n    if les: les.save_current_level()\n    else: unreal.EditorLevelLibrary.save_current_level()\n    print(\'RESULT:\' + json.dumps({\'success\': True}))\nexcept Exception as e:\n    print(\'RESULT:\' + json.dumps({\'success\': False, \'error\': str(e)}))\n'.trim();
+      const resp: any = await this.bridge.executePython(py);
+      // Handle LogOutput format from executePython
+      let out = '';
+      if (resp?.LogOutput && Array.isArray(resp.LogOutput)) {
+        out = resp.LogOutput.map((log: any) => log.Output || '').join('');
+      } else if (typeof resp === 'string') {
+        out = resp;
+      } else {
+        out = JSON.stringify(resp);
+      }
+      const m = out.match(/RESULT:({.*})/);
+      if (m) { 
+        const parsed = JSON.parse(m[1]); 
+        if (parsed.success) return { success: true, message: 'Level saved' };
+      }
+      // If Python failed, return error
+      return { error: 'Failed to save level', success: false };
+    } catch (err) {
+      return { error: `Failed to save level: ${err}`, success: false };
+    }
+  }
+}