unreal-engine-mcp-server 0.4.0 → 0.4.4

package/dist/tools/landscape.js

@@ -1,115 +1,246 @@
+import { bestEffortInterpretedText, coerceBoolean, coerceString, interpretStandardResult } from '../utils/result-helpers.js';
+import { ensureVector3 } from '../utils/validation.js';
+import { escapePythonString } from '../utils/python.js';
 export class LandscapeTools {
     bridge;
     constructor(bridge) {
         this.bridge = bridge;
     }
-    // Execute console command
-    async _executeCommand(command) {
-        return this.bridge.httpCall('/remote/object/call', 'PUT', {
-            objectPath: '/Script/Engine.Default__KismetSystemLibrary',
-            functionName: 'ExecuteConsoleCommand',
-            parameters: {
-                WorldContextObject: null,
-                Command: command,
-                SpecificPlayer: null
-            },
-            generateTransaction: false
-        });
-    }
     // Create landscape with World Partition support (UE 5.6)
     async createLandscape(params) {
-        // Try Python API with World Partition support for UE 5.6
-        try {
-            const pythonScript = `
+        const name = params.name?.trim();
+        if (!name) {
+            return { success: false, error: 'Landscape name is required' };
+        }
+        if (typeof params.sizeX === 'number' && params.sizeX <= 0) {
+            return {
+                success: false,
+                error: 'Landscape sizeX must be a positive number'
+            };
+        }
+        if (typeof params.sizeY === 'number' && params.sizeY <= 0) {
+            return {
+                success: false,
+                error: 'Landscape sizeY must be a positive number'
+            };
+        }
+        const [locX, locY, locZ] = ensureVector3(params.location ?? [0, 0, 0], 'landscape location');
+        const sectionsPerComponent = Math.max(1, Math.floor(params.sectionsPerComponent ?? 1));
+        const quadsPerSection = Math.max(1, Math.floor(params.quadsPerSection ?? 63));
+        const componentCount = Math.max(1, Math.floor(params.componentCount ?? 1));
+        const defaultSize = 1000;
+        const scaleX = params.sizeX ? Math.max(0.1, params.sizeX / defaultSize) : 1;
+        const scaleY = params.sizeY ? Math.max(0.1, params.sizeY / defaultSize) : 1;
+        const escapedName = escapePythonString(name);
+        const escapedMaterial = params.materialPath && params.materialPath.trim().length > 0
+            ? escapePythonString(params.materialPath.trim())
+            : '';
+        const runtimeGridFlag = params.runtimeGrid ? 'True' : 'False';
+        const spatiallyLoadedFlag = params.isSpatiallyLoaded ? 'True' : 'False';
+        const runtimeGridValue = params.runtimeGrid ? escapePythonString(params.runtimeGrid.trim()) : '';
+        const dataLayerNames = Array.isArray(params.dataLayers)
+            ? params.dataLayers
+                .map(layer => layer?.trim())
+                .filter((layer) => Boolean(layer))
+                .map(layer => escapePythonString(layer))
+            : [];
+        const pythonScript = `
 import unreal
 import json
 
-# Get the editor world using the proper subsystem
+result = {
+  "success": False,
+  "message": "",
+  "error": "",
+  "warnings": [],
+  "details": [],
+  "landscapeName": "",
+  "landscapeActor": "",
+  "worldPartition": False,
+  "runtimeGridRequested": ${runtimeGridFlag},
+  "spatiallyLoaded": ${spatiallyLoadedFlag}
+}
+
 try:
-    editor_subsystem = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
-    world = editor_subsystem.get_editor_world() if hasattr(editor_subsystem, 'get_editor_world') else None
-except:
-    # Fallback for older API
+  editor_subsystem = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
+  world = editor_subsystem.get_editor_world() if editor_subsystem and hasattr(editor_subsystem, 'get_editor_world') else None
+  data_layer_manager = None
+  if world:
     try:
-        world = unreal.EditorLevelLibrary.get_editor_world()
-    except:
-        world = None
+      world_partition = world.get_world_partition()
+      result["worldPartition"] = world_partition is not None
+      if result["worldPartition"] and hasattr(unreal, "WorldPartitionBlueprintLibrary"):
+        data_layer_manager = unreal.WorldPartitionBlueprintLibrary.get_data_layer_manager(world)
+    except Exception as wp_error:
+      result["warnings"].append(f"Failed to inspect world partition: {wp_error}")
 
-is_world_partition = False
-data_layer_manager = None
-
-if world:
+  actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+  if not actor_subsystem:
+    result["error"] = "EditorActorSubsystem unavailable"
+  else:
+    existing = None
     try:
-        # Check if World Partition is enabled (UE 5.6)
-        world_partition = world.get_world_partition()
-        is_world_partition = world_partition is not None
-        if is_world_partition:
-            # Get Data Layer Manager for UE 5.6
-            data_layer_manager = unreal.WorldPartitionBlueprintLibrary.get_data_layer_manager(world)
-    except:
-        pass
+      for actor in actor_subsystem.get_all_level_actors():
+        if actor and actor.get_actor_label() == "${escapedName}":
+          existing = actor
+          break
+    except Exception as scan_error:
+      result["warnings"].append(f"Actor scan failed: {scan_error}")
 
-# Try to create a basic landscape using available API
-try:
-    # Use EditorLevelLibrary to spawn a landscape actor
-    location = unreal.Vector(${params.location?.[0] || 0}, ${params.location?.[1] || 0}, ${params.location?.[2] || 0})
-    rotation = unreal.Rotator(0, 0, 0)
-    
-    # Check if LandscapeSubsystem is available (not LandscapeEditorSubsystem)
-    landscape_subsystem = None
-    try:
-        landscape_subsystem = unreal.get_editor_subsystem(unreal.LandscapeSubsystem)
-    except:
+    if existing:
+      result["success"] = True
+      result["message"] = "Landscape already exists"
+      result["landscapeName"] = existing.get_actor_label()
+      try:
+        result["landscapeActor"] = existing.get_path_name()
+      except Exception:
         pass
-    
-    if landscape_subsystem:
-        # Use subsystem if available
-        result = {"success": False, "error": "LandscapeSubsystem API limited via Python", "world_partition": is_world_partition}
     else:
-        # Landscape actors cannot be properly spawned via Python API
-        # The component registration issues are inherent to how landscapes work
-        # Direct users to the proper workflow
-        result = {
-            "success": False, 
-            "error": "Landscape creation is not supported via Python API",
-            "suggestion": "Please use Landscape Mode in the Unreal Editor toolbar:",
-            "steps": [
-                "1. Click 'Modes' dropdown in toolbar",
-                "2. Select 'Landscape'",
-                "3. Configure size and materials",
-                "4. Click 'Create' to generate landscape"
-            ],
-            "world_partition": is_world_partition
-        }
-    
-    print(f'RESULT:{json.dumps(result)}')
+      landscape_class = getattr(unreal, "Landscape", None)
+      if not landscape_class:
+        result["error"] = "Landscape class unavailable"
+      else:
+        location = unreal.Vector(${locX}, ${locY}, ${locZ})
+        rotation = unreal.Rotator(0.0, 0.0, 0.0)
+        landscape_actor = actor_subsystem.spawn_actor_from_class(landscape_class, location, rotation)
+        if not landscape_actor:
+          result["error"] = "Failed to spawn landscape actor"
+        else:
+          try:
+            landscape_actor.set_actor_label("${escapedName}", True)
+          except TypeError:
+            landscape_actor.set_actor_label("${escapedName}")
+          except Exception as label_error:
+            result["warnings"].append(f"Failed to set landscape label: {label_error}")
+
+          try:
+            landscape_actor.set_actor_scale3d(unreal.Vector(${scaleX.toFixed(4)}, ${scaleY.toFixed(4)}, 1.0))
+            result["details"].append(f"Actor scale set to (${scaleX.toFixed(2)}, ${scaleY.toFixed(2)}, 1.0)")
+          except Exception as scale_error:
+            result["warnings"].append(f"Failed to set landscape scale: {scale_error}")
+
+          landscape_editor = None
+          try:
+            landscape_editor = unreal.get_editor_subsystem(unreal.LandscapeEditorSubsystem)
+          except Exception as editor_error:
+            result["warnings"].append(f"LandscapeEditorSubsystem unavailable: {editor_error}")
+
+          if landscape_editor:
+            try:
+              landscape_editor.set_component_size(${sectionsPerComponent}, ${quadsPerSection})
+              landscape_editor.set_component_count(${componentCount}, ${componentCount})
+              result["details"].append(f"Component size ${sectionsPerComponent}x${quadsPerSection}, count ${componentCount}x${componentCount}")
+            except Exception as config_error:
+              result["warnings"].append(f"Landscape configuration limited: {config_error}")
+
+          ${escapedMaterial ? `try:
+            material = unreal.EditorAssetLibrary.load_asset("${escapedMaterial}")
+            if material:
+              try:
+                landscape_actor.set_landscape_material(material)
+              except Exception:
+                landscape_actor.editor_set_landscape_material(material)
+              result["details"].append("Landscape material applied")
+            else:
+              result["warnings"].append("Landscape material asset not found: ${escapedMaterial}")
+          except Exception as material_error:
+            result["warnings"].append(f"Failed to apply landscape material: {material_error}")
+          ` : ''}
+          ${runtimeGridValue ? `if result["worldPartition"] and hasattr(unreal, "WorldPartitionBlueprintLibrary"):
+            try:
+              unreal.WorldPartitionBlueprintLibrary.set_actor_runtime_grid(landscape_actor, "${runtimeGridValue}")
+              result["details"].append("Runtime grid assigned: ${runtimeGridValue}")
+            except Exception as grid_error:
+              result["warnings"].append(f"Failed to assign runtime grid: {grid_error}")
+          ` : ''}
+          ${params.isSpatiallyLoaded ? `if result["worldPartition"] and hasattr(unreal, "WorldPartitionBlueprintLibrary"):
+            try:
+              unreal.WorldPartitionBlueprintLibrary.set_actor_spatially_loaded(landscape_actor, True)
+              result["details"].append("Actor marked as spatially loaded")
+            except Exception as spatial_error:
+              result["warnings"].append(f"Failed to mark as spatially loaded: {spatial_error}")
+          ` : ''}
+          ${dataLayerNames.length ? `if result["worldPartition"] and data_layer_manager:
+            for layer_name in ${JSON.stringify(dataLayerNames)}:
+              try:
+                data_layer = data_layer_manager.get_data_layer(layer_name)
+                if data_layer:
+                  unreal.WorldPartitionBlueprintLibrary.add_actor_to_data_layer(landscape_actor, data_layer)
+                  result["details"].append(f"Added to data layer {layer_name}")
+                else:
+                  result["warnings"].append(f"Data layer not found: {layer_name}")
+              except Exception as data_layer_error:
+                result["warnings"].append(f"Failed to assign data layer {layer_name}: {data_layer_error}")
+          ` : ''}
+
+          try:
+            result["landscapeName"] = landscape_actor.get_actor_label()
+            result["landscapeActor"] = landscape_actor.get_path_name()
+          except Exception:
+            pass
+
+          result["success"] = True
+          result["message"] = "Landscape actor created"
 except Exception as e:
-    print(f'RESULT:{{"success": false, "error": "{str(e)}"}}')
+  result["error"] = str(e)
+
+if result.get("success"):
+  result.pop("error", None)
+else:
+  if not result.get("error"):
+    result["error"] = "Failed to create landscape actor"
+  if not result.get("message"):
+    result["message"] = result["error"]
+
+if not result.get("warnings"):
+  result.pop("warnings", None)
+if not result.get("details"):
+  result.pop("details", None)
+
+print("RESULT:" + json.dumps(result))
 `.trim();
+        try {
             const response = await this.bridge.executePython(pythonScript);
-            const output = typeof response === 'string' ? response : JSON.stringify(response);
-            const match = output.match(/RESULT:({.*})/);
-            if (match) {
-                try {
-                    const result = JSON.parse(match[1]);
-                    if (result.world_partition) {
-                        result.message = 'World Partition detected. Manual landscape creation required in editor.';
-                    }
-                    return result;
-                }
-                catch { }
+            const interpreted = interpretStandardResult(response, {
+                successMessage: 'Landscape actor created',
+                failureMessage: 'Failed to create landscape actor'
+            });
+            if (!interpreted.success) {
+                return {
+                    success: false,
+                    error: interpreted.error || interpreted.message
+                };
+            }
+            const result = {
+                success: true,
+                message: interpreted.message,
+                landscapeName: coerceString(interpreted.payload.landscapeName) ?? name,
+                worldPartition: coerceBoolean(interpreted.payload.worldPartition)
+            };
+            const actorPath = coerceString(interpreted.payload.landscapeActor);
+            if (actorPath) {
+                result.landscapeActor = actorPath;
             }
+            if (interpreted.warnings?.length) {
+                result.warnings = interpreted.warnings;
+            }
+            if (interpreted.details?.length) {
+                result.details = interpreted.details;
+            }
+            if (params.runtimeGrid) {
+                result.runtimeGrid = params.runtimeGrid;
+            }
+            if (typeof params.isSpatiallyLoaded === 'boolean') {
+                result.spatiallyLoaded = params.isSpatiallyLoaded;
+            }
+            return result;
         }
-        catch {
-            // Continue to fallback
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to create landscape actor: ${error}`
+            };
         }
-        // Fallback message with World Partition info
-        return {
-            success: false,
-            error: 'Landscape creation via API is limited. Please use the Unreal Editor UI to create landscapes.',
-            worldPartitionSupport: params.enableWorldPartition ? 'Requested' : 'Not requested',
-            suggestion: 'Use the Landscape Mode in the editor toolbar to create and configure landscapes'
-        };
     }
     // Sculpt landscape
     async sculptLandscape(_params) {
@@ -129,9 +260,7 @@ except Exception as e:
         if (params.blendMode) {
             commands.push(`SetLayerBlendMode ${params.layerName} ${params.blendMode}`);
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: `Layer ${params.layerName} added to landscape` };
     }
     // Create landscape spline
@@ -150,9 +279,7 @@ except Exception as e:
         if (params.meshPath) {
             commands.push(`SetSplineMesh ${params.splineName} ${params.meshPath}`);
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: `Landscape spline ${params.splineName} created` };
     }
     // Import heightmap
@@ -179,9 +306,7 @@ except Exception as e:
         if (params.lodDistribution !== undefined) {
             commands.push(`SetLandscapeLODDistribution ${params.landscapeName} ${params.lodDistribution}`);
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: 'Landscape LOD settings updated' };
     }
     // Create landscape grass
@@ -197,9 +322,7 @@ except Exception as e:
         if (params.randomRotation !== undefined) {
             commands.push(`SetGrassRandomRotation ${params.grassType} ${params.randomRotation}`);
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: `Grass type ${params.grassType} created on landscape` };
     }
     // Landscape collision
@@ -212,9 +335,7 @@ except Exception as e:
             commands.push(`SetLandscapeSimpleCollision ${params.landscapeName} ${params.simpleCollision}`);
         }
         commands.push(`UpdateLandscapeCollision ${params.landscapeName}`);
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: 'Landscape collision updated' };
     }
     // Retopologize landscape
@@ -227,9 +348,7 @@ except Exception as e:
             commands.push(`SetRetopologizePreserveDetails ${params.preserveDetails}`);
         }
         commands.push(`RetopologizeLandscape ${params.landscapeName}`);
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: 'Landscape retopologized' };
     }
     // Create water body
@@ -245,68 +364,96 @@ except Exception as e:
         try {
             const pythonScript = `
 import unreal
+import json
+
+result = {'success': False, 'error': 'Landscape not found'}
 
 try:
-    # Get the landscape actor
-    actors = unreal.EditorLevelLibrary.get_all_level_actors()
-    landscape = None
-    
-    for actor in actors:
-        if actor.get_name() == "${params.landscapeName}" or actor.get_actor_label() == "${params.landscapeName}":
-            if isinstance(actor, unreal.LandscapeProxy) or isinstance(actor, unreal.Landscape):
-                landscape = actor
-                break
-    
-    if not landscape:
-        print('RESULT:{"success": false, "error": "Landscape not found"}')
+  # Get the landscape actor using modern EditorActorSubsystem
+  actors = []
+  try:
+    actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+    if actor_subsystem and hasattr(actor_subsystem, 'get_all_level_actors'):
+      actors = actor_subsystem.get_all_level_actors()
+  except Exception:
+    actors = []
+  landscape = None
+
+  for actor in actors:
+    if actor.get_name() == "${params.landscapeName}" or actor.get_actor_label() == "${params.landscapeName}":
+      if isinstance(actor, unreal.LandscapeProxy) or isinstance(actor, unreal.Landscape):
+        landscape = actor
+        break
+
+  if landscape:
+    changes_made = []
+
+    # Configure spatial loading (UE 5.6)
+    if ${params.enableSpatialLoading !== undefined ? 'True' : 'False'}:
+      try:
+        landscape.set_editor_property('is_spatially_loaded', ${params.enableSpatialLoading || false})
+        changes_made.append("Spatial loading: ${params.enableSpatialLoading}")
+      except:
+        pass
+
+    # Set runtime grid (UE 5.6 World Partition)
+    if "${params.runtimeGrid || ''}":
+      try:
+        landscape.set_editor_property('runtime_grid', unreal.Name("${params.runtimeGrid}"))
+        changes_made.append("Runtime grid: ${params.runtimeGrid}")
+      except:
+        pass
+
+    # Configure data layers (UE 5.6)
+    if ${params.dataLayers ? 'True' : 'False'}:
+      try:
+        # Try modern subsystem first
+        try:
+          world = None
+          editor_subsystem = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
+          if editor_subsystem and hasattr(editor_subsystem, 'get_editor_world'):
+            world = editor_subsystem.get_editor_world()
+          if world is None:
+            world = unreal.EditorSubsystemLibrary.get_editor_world()
+        except Exception:
+          world = unreal.EditorSubsystemLibrary.get_editor_world()
+        data_layer_manager = unreal.WorldPartitionBlueprintLibrary.get_data_layer_manager(world)
+        if data_layer_manager:
+          # Note: Full data layer API requires additional setup
+          changes_made.append("Data layers: Requires manual configuration")
+      except:
+        pass
+
+    if changes_made:
+      result = {
+        'success': True,
+        'message': 'World Partition configured',
+        'changes': changes_made
+      }
     else:
-        changes_made = []
-        
-        # Configure spatial loading (UE 5.6)
-        if ${params.enableSpatialLoading !== undefined ? 'True' : 'False'}:
-            try:
-                landscape.set_editor_property('is_spatially_loaded', ${params.enableSpatialLoading || false})
-                changes_made.append("Spatial loading: ${params.enableSpatialLoading}")
-            except:
-                pass
-        
-        # Set runtime grid (UE 5.6 World Partition)
-        if "${params.runtimeGrid || ''}":
-            try:
-                landscape.set_editor_property('runtime_grid', unreal.Name("${params.runtimeGrid}"))
-                changes_made.append("Runtime grid: ${params.runtimeGrid}")
-            except:
-                pass
-        
-        # Configure data layers (UE 5.6)
-        if ${params.dataLayers ? 'True' : 'False'}:
-            try:
-                world = unreal.EditorLevelLibrary.get_editor_world()
-                data_layer_manager = unreal.WorldPartitionBlueprintLibrary.get_data_layer_manager(world)
-                if data_layer_manager:
-                    # Note: Full data layer API requires additional setup
-                    changes_made.append("Data layers: Requires manual configuration")
-            except:
-                pass
-        
-        if changes_made:
-            print('RESULT:{"success": true, "message": "World Partition configured", "changes": ' + str(changes_made).replace("'", '"') + '}')
-        else:
-            print('RESULT:{"success": false, "error": "No World Partition changes applied"}')
-            
+      result = {
+        'success': False,
+        'error': 'No World Partition changes applied'
+      }
+
 except Exception as e:
-    print(f'RESULT:{{"success": false, "error": "{str(e)}"}}')
+  result = {'success': False, 'error': str(e)}
+
+print('RESULT:' + json.dumps(result))
 `.trim();
             const response = await this.bridge.executePython(pythonScript);
-            const output = typeof response === 'string' ? response : JSON.stringify(response);
-            const match = output.match(/RESULT:({.*})/);
-            if (match) {
-                try {
-                    return JSON.parse(match[1]);
-                }
-                catch { }
+            const interpreted = interpretStandardResult(response, {
+                successMessage: 'World Partition configuration attempted',
+                failureMessage: 'World Partition configuration failed'
+            });
+            if (interpreted.success) {
+                return interpreted.payload;
             }
-            return { success: true, message: 'World Partition configuration attempted' };
+            return {
+                success: false,
+                error: interpreted.error ?? 'World Partition configuration failed',
+                details: bestEffortInterpretedText(interpreted)
+            };
         }
         catch (err) {
             return { success: false, error: `Failed to configure World Partition: ${err}` };
@@ -328,9 +475,7 @@ except Exception as e:
                 }
             }
             // Execute commands
-            for (const cmd of commands) {
-                await this.bridge.executeConsoleCommand(cmd);
-            }
+            await this.bridge.executeConsoleCommands(commands);
             return {
                 success: true,
                 message: `Data layers ${params.operation === 'add' ? 'added' : params.operation === 'remove' ? 'removed' : 'set'} for landscape`,
@@ -354,9 +499,7 @@ except Exception as e:
         // Debug visualization commands
         commands.push('wp.Runtime.ToggleDrawRuntimeHash2D'); // Show 2D grid
         try {
-            for (const cmd of commands) {
-                await this.bridge.executeConsoleCommand(cmd);
-            }
+            await this.bridge.executeConsoleCommands(commands);
             return {
                 success: true,
                 message: 'Streaming cells configured for World Partition',

package/dist/tools/level.d.ts

@@ -2,7 +2,6 @@ import { UnrealBridge } from '../unreal-bridge.js';
 export declare class LevelTools {
     private bridge;
     constructor(bridge: UnrealBridge);
-    private _executeCommand;
     loadLevel(params: {
         levelPath: string;
         streaming?: boolean;
@@ -11,28 +10,12 @@ export declare class LevelTools {
     saveLevel(_params: {
         levelName?: string;
         savePath?: string;
-    }): Promise<{
-        success: boolean;
-        message: string;
-        error?: undefined;
-    } | {
-        success: boolean;
-        error: any;
-        message?: undefined;
-    }>;
+    }): Promise<Record<string, unknown>>;
     createLevel(params: {
         levelName: string;
         template?: 'Empty' | 'Default' | 'VR' | 'TimeOfDay';
         savePath?: string;
-    }): Promise<{
-        success: boolean;
-        message: any;
-        error?: undefined;
-    } | {
-        success: boolean;
-        error: any;
-        message?: undefined;
-    }>;
+    }): Promise<Record<string, unknown>>;
     streamLevel(params: {
         levelName: string;
         shouldBeLoaded: boolean;
@@ -79,15 +62,7 @@ export declare class LevelTools {
     buildNavMesh(params: {
         rebuildAll?: boolean;
         selectedOnly?: boolean;
-    }): Promise<{
-        success: boolean;
-        message: any;
-        error?: undefined;
-    } | {
-        success: boolean;
-        error: any;
-        message?: undefined;
-    }>;
+    }): Promise<Record<string, unknown>>;
     setLevelVisibility(params: {
         levelName: string;
         visible: boolean;