unreal-engine-mcp-server 0.4.0 → 0.4.3

package/dist/tools/actors.js

@@ -1,326 +1,252 @@
+import { ensureRotation, ensureVector3 } from '../utils/validation.js';
+import { coerceString, coerceVector3, interpretStandardResult } from '../utils/result-helpers.js';
+import { escapePythonString } from '../utils/python.js';
 export class ActorTools {
     bridge;
     constructor(bridge) {
         this.bridge = bridge;
     }
     async spawn(params) {
-        // Validate classPath
-        if (!params.classPath || typeof params.classPath !== 'string') {
+        if (!params.classPath || typeof params.classPath !== 'string' || params.classPath.trim().length === 0) {
             throw new Error(`Invalid classPath: ${params.classPath}`);
         }
-        // Auto-map common shape names to proper asset paths
+        const className = params.classPath.trim();
+        const requestedActorName = typeof params.actorName === 'string' ? params.actorName.trim() : undefined;
+        if (params.actorName !== undefined && (!requestedActorName || requestedActorName.length === 0)) {
+            throw new Error(`Invalid actorName: ${params.actorName}`);
+        }
+        const sanitizedActorName = requestedActorName?.replace(/[^A-Za-z0-9_-]/g, '_');
+        const lowerName = className.toLowerCase();
         const shapeMapping = {
-            'cube': '/Engine/BasicShapes/Cube',
-            'sphere': '/Engine/BasicShapes/Sphere',
-            'cylinder': '/Engine/BasicShapes/Cylinder',
-            'cone': '/Engine/BasicShapes/Cone',
-            'plane': '/Engine/BasicShapes/Plane',
-            'torus': '/Engine/BasicShapes/Torus',
-            'box': '/Engine/BasicShapes/Cube', // Common alias
-            'ball': '/Engine/BasicShapes/Sphere', // Common alias
+            cube: '/Engine/BasicShapes/Cube',
+            sphere: '/Engine/BasicShapes/Sphere',
+            cylinder: '/Engine/BasicShapes/Cylinder',
+            cone: '/Engine/BasicShapes/Cone',
+            plane: '/Engine/BasicShapes/Plane',
+            torus: '/Engine/BasicShapes/Torus'
         };
-        // Check if classPath is just a simple shape name (case-insensitive)
-        const lowerPath = params.classPath.toLowerCase();
-        if (shapeMapping[lowerPath]) {
-            params.classPath = shapeMapping[lowerPath];
-        }
-        // Auto-detect and handle asset paths (like /Engine/BasicShapes/Cube)
-        // The Python code will automatically spawn a StaticMeshActor and assign the mesh
-        // So we don't reject asset paths anymore - let Python handle them intelligently
-        // Only reject obviously invalid patterns
-        if (params.classPath === 'InvalidActorClass' ||
-            params.classPath === 'NoSlash' ||
-            params.classPath.startsWith('/Invalid/') ||
-            params.classPath.startsWith('/NotExist/')) {
-            throw new Error(`Invalid actor class: ${params.classPath}`);
-        }
-        // Try Python API first for better control and naming
-        try {
-            return await this.spawnViaPython(params);
-        }
-        catch (pythonErr) {
-            // Check if this is a known failure that shouldn't fall back
-            const errorStr = String(pythonErr).toLowerCase();
-            if (errorStr.includes('abstract') || errorStr.includes('class not found')) {
-                // Don't try console fallback for abstract or non-existent classes
-                throw pythonErr;
-            }
-            // Check if the error is because of PIE mode
-            if (String(pythonErr).includes('Play In Editor mode')) {
-                // Don't fall back to console if we're in PIE mode
-                throw pythonErr;
-            }
-            // Fallback to console if Python fails for other reasons
-            // Only log if not a known/expected error
-            if (!String(pythonErr).includes('No valid result from Python')) {
-                console.error('Python spawn failed, falling back to console:', pythonErr);
-            }
-            return this.spawnViaConsole(params);
-        }
-    }
-    async spawnViaPython(params) {
-        try {
-            // Normalize and validate location
-            const loc = params.location ?? { x: 0, y: 0, z: 100 };
-            if (loc === null) {
-                throw new Error('Invalid location: null is not allowed');
-            }
-            if (typeof loc !== 'object' ||
-                typeof loc.x !== 'number' ||
-                typeof loc.y !== 'number' ||
-                typeof loc.z !== 'number') {
-                throw new Error('Invalid location: must have numeric x, y, z properties');
-            }
-            // Normalize and validate rotation
-            const rot = params.rotation ?? { pitch: 0, yaw: 0, roll: 0 };
-            if (rot === null) {
-                throw new Error('Invalid rotation: null is not allowed');
-            }
-            if (typeof rot !== 'object' ||
-                typeof rot.pitch !== 'number' ||
-                typeof rot.yaw !== 'number' ||
-                typeof rot.roll !== 'number') {
-                throw new Error('Invalid rotation: must have numeric pitch, yaw, roll properties');
-            }
-            // Resolve the class path
-            const fullClassPath = this.resolveActorClass(params.classPath);
-            let className = params.classPath;
-            // Extract simple class name for naming the actor
-            if (fullClassPath.includes('.')) {
-                className = fullClassPath.split('.').pop() || params.classPath;
-            }
-            const pythonCmd = `
+        const mappedClassPath = shapeMapping[lowerName] ?? this.resolveActorClass(className);
+        const [locX, locY, locZ] = ensureVector3(params.location ?? { x: 0, y: 0, z: 100 }, 'actor location');
+        const [rotPitch, rotYaw, rotRoll] = ensureRotation(params.rotation ?? { pitch: 0, yaw: 0, roll: 0 }, 'actor rotation');
+        const escapedResolvedClassPath = escapePythonString(mappedClassPath);
+        const escapedRequestedPath = escapePythonString(className);
+        const escapedRequestedActorName = sanitizedActorName ? escapePythonString(sanitizedActorName) : '';
+        const pythonCmd = `
 import unreal
 import json
+import time
 
-result = {"success": False, "message": "", "actor_name": ""}
+result = {
+  "success": False,
+  "message": "",
+  "error": "",
+  "actorName": "",
+  "requestedClass": "${escapedRequestedPath}",
+  "resolvedClass": "${escapedResolvedClassPath}",
+  "location": [${locX}, ${locY}, ${locZ}],
+  "rotation": [${rotPitch}, ${rotYaw}, ${rotRoll}],
+  "requestedActorName": "${escapedRequestedActorName}",
+  "warnings": [],
+  "details": []
+}
 
-# Check if editor is in play mode first
-try:
-    les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
-    if les and les.is_in_play_in_editor():
-        result["message"] = "Cannot spawn actors while in Play In Editor mode. Please stop PIE first."
-        print(f"RESULT:{json.dumps(result)}")
-        # Exit early from this script
-        raise SystemExit(0)
-except SystemExit:
-    # Re-raise the SystemExit to exit properly
-    raise
-except:
-    pass  # Continue if we can't check PIE state
+${this.getPythonSpawnHelper()}
 
-# List of abstract classes that cannot be spawned
 abstract_classes = ['PlaneReflectionCapture', 'ReflectionCapture', 'Actor', 'Pawn', 'Character']
 
-# Check for abstract classes
-if "${params.classPath}" in abstract_classes:
-    result["message"] = f"Cannot spawn ${params.classPath}: class is abstract and cannot be instantiated"
-    print(f"RESULT:{json.dumps(result)}")
+def finalize():
+  data = dict(result)
+  if data.get("success"):
+    if not data.get("message"):
+      data["message"] = "Actor spawned successfully"
+    data.pop("error", None)
+  else:
+    if not data.get("error"):
+      data["error"] = data.get("message") or "Failed to spawn actor"
+    if not data.get("message"):
+      data["message"] = data["error"]
+  if not data.get("warnings"):
+    data.pop("warnings", None)
+  if not data.get("details"):
+    data.pop("details", None)
+  return data
+
+try:
+  les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
+  if les and les.is_in_play_in_editor():
+    result["message"] = "Cannot spawn actors while in Play In Editor mode. Please stop PIE first."
+    result["error"] = result["message"]
+    result["details"].append("Play In Editor mode detected")
+    print('RESULT:' + json.dumps(finalize()))
+    raise SystemExit(0)
+except SystemExit:
+  raise
+except Exception:
+  result["warnings"].append("Unable to determine Play In Editor state")
+
+if result["requestedClass"] in abstract_classes:
+  result["message"] = f"Cannot spawn {result['requestedClass']}: class is abstract and cannot be instantiated"
+  result["error"] = result["message"]
 else:
-    try:
-        # Get the world using the modern subsystem API
-        editor_subsystem = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
-        world = editor_subsystem.get_editor_world() if hasattr(editor_subsystem, 'get_editor_world') else None
-        if not world:
-            # Try LevelEditorSubsystem as fallback
-            level_subsystem = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
-            if hasattr(level_subsystem, 'get_editor_world'):
-                world = level_subsystem.get_editor_world()
-        
-        # Handle content paths (assets) vs class names
-        class_path = "${params.classPath}"
-        location = unreal.Vector(${loc.x}, ${loc.y}, ${loc.z})
-        rotation = unreal.Rotator(${rot.pitch}, ${rot.yaw}, ${rot.roll})
-        actor = None
-        
-        # Check if this is a content path (starts with /Game or /Engine)
-        if class_path.startswith('/Game') or class_path.startswith('/Engine'):
-            # This is a content asset path - try to load and spawn it
-            try:
-                # For blueprint classes or static meshes
-                asset = unreal.EditorAssetLibrary.load_asset(class_path)
-                if asset:
-                    # If it's a blueprint class
-                    if isinstance(asset, unreal.Blueprint):
-                        actor_class = asset.generated_class()
-                        if actor_class:
-                            # Use modern EditorActorSubsystem API
-                            actor_subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-                            actor = actor_subsys.spawn_actor_from_class(
-                                actor_class,
-                                location,
-                                rotation
-                            )
-                    # If it's a static mesh, spawn a StaticMeshActor and assign the mesh
-                    elif isinstance(asset, unreal.StaticMesh):
-                        # Use modern EditorActorSubsystem API
-                        actor_subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-                        actor = actor_subsys.spawn_actor_from_class(
-                            unreal.StaticMeshActor,
-                            location,
-                            rotation
-                        )
-                        if actor:
-                            mesh_component = actor.get_component_by_class(unreal.StaticMeshComponent)
-                            if mesh_component:
-                                mesh_component.set_static_mesh(asset)
-                                # Make it movable so physics can be applied
-                                mesh_component.set_editor_property('mobility', unreal.ComponentMobility.MOVABLE)
-            except Exception as load_err:
-                # If asset loading fails, try basic shapes from Engine content
-                shape_map = {
-                    'cube': '/Engine/BasicShapes/Cube',
-                    'sphere': '/Engine/BasicShapes/Sphere',
-                    'cylinder': '/Engine/BasicShapes/Cylinder',
-                    'cone': '/Engine/BasicShapes/Cone',
-                    'plane': '/Engine/BasicShapes/Plane',
-                    'torus': '/Engine/BasicShapes/Torus'
-                }
-                
-                # Check if it's a basic shape name or path
-                mesh_path = None
-                lower_path = class_path.lower()
-                for shape_name, shape_path in shape_map.items():
-                    if shape_name in lower_path:
-                        mesh_path = shape_path
-                        break
-                
-                if mesh_path:
-                    # Use Engine's basic shape
-                    shape_mesh = unreal.EditorAssetLibrary.load_asset(mesh_path)
-                    if shape_mesh:
-                        # Use modern EditorActorSubsystem API
-                        actor_subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-                        actor = actor_subsys.spawn_actor_from_class(
-                            unreal.StaticMeshActor,
-                            location,
-                            rotation
-                        )
-                        if actor:
-                            mesh_component = actor.get_component_by_class(unreal.StaticMeshComponent)
-                            if mesh_component:
-                                mesh_component.set_static_mesh(shape_mesh)
-                                # Make it movable so physics can be applied
-                                mesh_component.set_editor_property('mobility', unreal.ComponentMobility.MOVABLE)
-        
-        # If not a content path or content spawn failed, try as a class name
-        if not actor:
-            if class_path == "StaticMeshActor":
-                # Use modern EditorActorSubsystem API
-                actor_subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-                actor = actor_subsys.spawn_actor_from_class(
-                    unreal.StaticMeshActor, 
-                    location, 
-                    rotation
-                )
-                    
-                if actor:
-                    # Assign a default mesh (cube)
-                    cube_mesh = unreal.EditorAssetLibrary.load_asset('/Engine/BasicShapes/Cube')
-                    if cube_mesh:
-                        mesh_component = actor.get_component_by_class(unreal.StaticMeshComponent)
-                        if mesh_component:
-                            mesh_component.set_static_mesh(cube_mesh)
-                            # Make it movable so physics can be applied
-                            mesh_component.set_editor_property('mobility', unreal.ComponentMobility.MOVABLE)
-                            
-            elif class_path == "CameraActor":
-                # Use modern EditorActorSubsystem API
-                actor_subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-                actor = actor_subsys.spawn_actor_from_class(
-                    unreal.CameraActor,
-                    location,
-                    rotation
-                )
-            else:
-                # Try to get the class by name for other actors (e.g., PointLight)
-                actor_class = None
-                if hasattr(unreal, class_path):
-                    actor_class = getattr(unreal, class_path)
-                
-                if actor_class:
-                    # Use modern EditorActorSubsystem API
-                    actor_subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-                    actor = actor_subsys.spawn_actor_from_class(
-                        actor_class, 
-                        location, 
-                        rotation
-                    )
-        
-        # Set the actor label and return result
+  try:
+    class_path = result["resolvedClass"]
+    requested_path = result["requestedClass"]
+    location = unreal.Vector(${locX}, ${locY}, ${locZ})
+    rotation = unreal.Rotator(${rotPitch}, ${rotYaw}, ${rotRoll})
+    actor = None
+
+    simple_name = requested_path.split('/')[-1] if '/' in requested_path else requested_path
+    if '.' in simple_name:
+      simple_name = simple_name.split('.')[-1]
+    simple_name_lower = simple_name.lower()
+    class_lookup_name = class_path.split('.')[-1] if '.' in class_path else simple_name
+
+    result["details"].append(f"Attempting spawn using class path: {class_path}")
+
+    if class_path.startswith('/Game') or class_path.startswith('/Engine'):
+      try:
+        asset = unreal.EditorAssetLibrary.load_asset(class_path)
+      except Exception as asset_error:
+        asset = None
+        result["warnings"].append(f"Failed to load asset for {class_path}: {asset_error}")
+      if asset:
+        if isinstance(asset, unreal.Blueprint):
+          try:
+            actor_class = asset.generated_class()
+          except Exception as blueprint_error:
+            actor_class = None
+            result["warnings"].append(f"Failed to resolve blueprint class: {blueprint_error}")
+          if actor_class:
+            actor = spawn_actor_from_class(actor_class, location, rotation)
+            if actor:
+              result["details"].append("Spawned using Blueprint generated class")
+        elif isinstance(asset, unreal.StaticMesh):
+          actor = spawn_actor_from_class(unreal.StaticMeshActor, location, rotation)
+          if actor:
+            mesh_component = actor.get_component_by_class(unreal.StaticMeshComponent)
+            if mesh_component:
+              mesh_component.set_static_mesh(asset)
+              mesh_component.set_editor_property('mobility', unreal.ComponentMobility.MOVABLE)
+              result["details"].append("Applied static mesh to spawned StaticMeshActor")
+
+    if not actor:
+      shape_map = {
+        'cube': '/Engine/BasicShapes/Cube',
+        'sphere': '/Engine/BasicShapes/Sphere',
+        'cylinder': '/Engine/BasicShapes/Cylinder',
+        'cone': '/Engine/BasicShapes/Cone',
+        'plane': '/Engine/BasicShapes/Plane',
+        'torus': '/Engine/BasicShapes/Torus'
+      }
+      mesh_path = shape_map.get(simple_name_lower)
+      if not mesh_path and class_path.startswith('/Engine/BasicShapes'):
+        mesh_path = class_path
+      if mesh_path:
+        try:
+          shape_mesh = unreal.EditorAssetLibrary.load_asset(mesh_path)
+        except Exception as shape_error:
+          shape_mesh = None
+          result["warnings"].append(f"Failed to load shape mesh {mesh_path}: {shape_error}")
+        if shape_mesh:
+          actor = spawn_actor_from_class(unreal.StaticMeshActor, location, rotation)
+          if actor:
+            mesh_component = actor.get_component_by_class(unreal.StaticMeshComponent)
+            if mesh_component:
+              mesh_component.set_static_mesh(shape_mesh)
+              mesh_component.set_editor_property('mobility', unreal.ComponentMobility.MOVABLE)
+              result["details"].append(f"Spawned StaticMeshActor with mesh {mesh_path}")
+
+    if not actor:
+      if class_lookup_name == "StaticMeshActor":
+        actor = spawn_actor_from_class(unreal.StaticMeshActor, location, rotation)
         if actor:
-            import time
-            timestamp = int(time.time() * 1000) % 10000
-            base_name = class_path.split('/')[-1] if '/' in class_path else class_path
-            actor_name = f"{base_name}_{timestamp}"
-            actor.set_actor_label(actor_name)
-            result["success"] = True
-            result["message"] = f"Spawned {actor_name} at ({location.x}, {location.y}, {location.z})"
-            result["actor_name"] = actor_name
-        else:
-            result["message"] = f"Failed to spawn actor from: {class_path}. Try using /Engine/BasicShapes/Cube or StaticMeshActor"
-                
-    except Exception as e:
-        result["message"] = f"Error spawning actor: {e}"
-        
-print(f"RESULT:{json.dumps(result)}")
+          try:
+            cube_mesh = unreal.EditorAssetLibrary.load_asset('/Engine/BasicShapes/Cube')
+          except Exception as cube_error:
+            cube_mesh = None
+            result["warnings"].append(f"Failed to load default cube mesh: {cube_error}")
+          if cube_mesh:
+            mesh_component = actor.get_component_by_class(unreal.StaticMeshComponent)
+            if mesh_component:
+              mesh_component.set_static_mesh(cube_mesh)
+              mesh_component.set_editor_property('mobility', unreal.ComponentMobility.MOVABLE)
+              result["details"].append("Applied default cube mesh to StaticMeshActor")
+      elif class_lookup_name == "CameraActor":
+        actor = spawn_actor_from_class(unreal.CameraActor, location, rotation)
+        if actor:
+          result["details"].append("Spawned CameraActor via reflected class lookup")
+      else:
+        actor_class = getattr(unreal, class_lookup_name, None)
+        if actor_class:
+          actor = spawn_actor_from_class(actor_class, location, rotation)
+          if actor:
+            result["details"].append(f"Spawned {class_lookup_name} via reflected class lookup")
+
+    if actor:
+      desired_name = (result.get("requestedActorName") or "").strip()
+      actor_name = ""
+      if desired_name:
+        try:
+          try:
+            actor.set_actor_label(desired_name, True)
+          except TypeError:
+            actor.set_actor_label(desired_name)
+          actor_name = actor.get_actor_label() or desired_name
+        except Exception as label_error:
+          result["warnings"].append(f"Failed to honor requested actor name '{desired_name}': {label_error}")
+      if not actor_name:
+        timestamp = int(time.time() * 1000) % 10000
+        base_name = simple_name or class_lookup_name or class_path.split('/')[-1]
+        fallback_name = f"{base_name}_{timestamp}"
+        try:
+          actor.set_actor_label(fallback_name)
+        except Exception as label_error:
+          result["warnings"].append(f"Failed to set actor label: {label_error}")
+        actor_name = actor.get_actor_label() or fallback_name
+      result["success"] = True
+      result["actorName"] = actor_name
+      if not result["message"]:
+        result["message"] = f"Spawned {actor_name} at ({location.x}, {location.y}, {location.z})"
+    else:
+      result["message"] = f"Failed to spawn actor from: {class_path}. Try using /Engine/BasicShapes/Cube or StaticMeshActor"
+      result["error"] = result["message"]
+  except Exception as spawn_error:
+    result["error"] = f"Error spawning actor: {spawn_error}"
+    if not result["message"]:
+      result["message"] = result["error"]
+
+print('RESULT:' + json.dumps(finalize()))
 `.trim();
+        try {
             const response = await this.bridge.executePython(pythonCmd);
-            // Extract output from Python response
-            let outputStr = '';
-            if (typeof response === 'object' && response !== null) {
-                // Check if it has LogOutput (standard Python execution response)
-                if (response.LogOutput && Array.isArray(response.LogOutput)) {
-                    // Concatenate all log outputs
-                    outputStr = response.LogOutput
-                        .map((log) => log.Output || '')
-                        .join('');
-                }
-                else if ('result' in response) {
-                    outputStr = String(response.result);
-                }
-                else if ('ReturnValue' in response && typeof response.ReturnValue === 'string') {
-                    outputStr = response.ReturnValue;
-                }
-                else {
-                    outputStr = JSON.stringify(response);
-                }
-            }
-            else {
-                outputStr = String(response || '');
+            const interpreted = interpretStandardResult(response, {
+                successMessage: `Spawned actor ${className}`,
+                failureMessage: `Failed to spawn actor ${className}`
+            });
+            if (!interpreted.success) {
+                throw new Error(interpreted.error || interpreted.message);
             }
-            // Parse the result from Python output
-            const resultMatch = outputStr.match(/RESULT:({.*})/);
-            if (resultMatch) {
-                try {
-                    const result = JSON.parse(resultMatch[1]);
-                    if (!result.success) {
-                        throw new Error(result.message || 'Spawn failed');
-                    }
-                    return result;
-                }
-                catch {
-                    // If we can't parse, check for common success patterns
-                    if (outputStr.includes('Spawned')) {
-                        return { success: true, message: outputStr };
-                    }
-                    throw new Error(`Failed to parse Python result: ${outputStr}`);
-                }
+            const actorName = coerceString(interpreted.payload.actorName);
+            const resolvedClass = coerceString(interpreted.payload.resolvedClass) ?? mappedClassPath;
+            const requestedClass = coerceString(interpreted.payload.requestedClass) ?? className;
+            const locationVector = coerceVector3(interpreted.payload.location) ?? [locX, locY, locZ];
+            const rotationVector = coerceVector3(interpreted.payload.rotation) ?? [rotPitch, rotYaw, rotRoll];
+            const result = {
+                success: true,
+                message: interpreted.message,
+                actorName: actorName ?? undefined,
+                resolvedClass,
+                requestedClass,
+                location: { x: locationVector[0], y: locationVector[1], z: locationVector[2] },
+                rotation: { pitch: rotationVector[0], yaw: rotationVector[1], roll: rotationVector[2] }
+            };
+            if (interpreted.warnings?.length) {
+                result.warnings = interpreted.warnings;
             }
-            else {
-                // Check output for success/failure patterns
-                if (outputStr.includes('Failed') || outputStr.includes('Error') || outputStr.includes('not found')) {
-                    throw new Error(outputStr || 'Spawn failed');
-                }
-                // Default fallback - but this shouldn't report success for failed operations
-                // Only report success if Python execution was successful and no error markers
-                if (response?.ReturnValue === true && !outputStr.includes('abstract')) {
-                    return { success: true, message: `Actor spawned: ${className} at ${loc.x},${loc.y},${loc.z}` };
-                }
-                else {
-                    throw new Error(`Failed to spawn ${className}: No valid result from Python`);
-                }
+            if (interpreted.details?.length) {
+                result.details = interpreted.details;
             }
+            return result;
         }
         catch (err) {
             throw new Error(`Failed to spawn actor via Python: ${err}`);
@@ -328,6 +254,7 @@ print(f"RESULT:{json.dumps(result)}")
     }
     async spawnViaConsole(params) {
         try {
+            const [locX, locY, locZ] = ensureVector3(params.location ?? { x: 0, y: 0, z: 100 }, 'actor location');
             // Check if editor is in play mode first
             try {
                 const pieCheckPython = `
@@ -360,8 +287,7 @@ else:
             // Get the console-friendly class name
             const spawnClass = this.getConsoleClassName(params.classPath);
             // Use summon command with location if provided
-            const loc = params.location || { x: 0, y: 0, z: 100 };
-            const command = `summon ${spawnClass} ${loc.x} ${loc.y} ${loc.z}`;
+            const command = `summon ${spawnClass} ${locX} ${locY} ${locZ}`;
             await this.bridge.httpCall('/remote/object/call', 'PUT', {
                 objectPath: '/Script/Engine.Default__KismetSystemLibrary',
                 functionName: 'ExecuteConsoleCommand',
@@ -376,7 +302,7 @@ else:
             // We can't guarantee this actually worked, so indicate uncertainty
             return {
                 success: true,
-                message: `Actor spawn attempted via console: ${spawnClass} at ${loc.x},${loc.y},${loc.z}`,
+                message: `Actor spawn attempted via console: ${spawnClass} at ${locX},${locY},${locZ}`,
                 note: 'Console spawn result uncertain - verify in editor'
             };
         }
@@ -384,6 +310,21 @@ else:
             throw new Error(`Failed to spawn actor: ${err}`);
         }
     }
+    getPythonSpawnHelper() {
+        return `
+def spawn_actor_from_class(actor_class, location, rotation):
+  actor = None
+  try:
+    actor_subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+    if actor_subsys:
+      actor = actor_subsys.spawn_actor_from_class(actor_class, location, rotation)
+  except Exception:
+    actor = None
+  if not actor:
+    raise RuntimeError('EditorActorSubsystem unavailable or failed to spawn actor. Enable Editor Scripting Utilities plugin and verify class path.')
+  return actor
+`.trim();
+    }
     resolveActorClass(classPath) {
         // Map common names to full Unreal class paths
         const classMap = {
@@ -419,6 +360,9 @@ else:
         if (classPath.startsWith('/Script/') || classPath.startsWith('/Game/')) {
             return classPath;
         }
+        if (classPath.startsWith('/Engine/')) {
+            return classPath;
+        }
         // Check for Blueprint paths
         if (classPath.includes('Blueprint') || classPath.includes('BP_')) {
             // Ensure it has the proper prefix