unreal-engine-mcp-server 0.4.0 → 0.4.4

package/dist/tools/animation.js

@@ -1,297 +1,61 @@
-import { validateAssetParams, concurrencyDelay } from '../utils/validation.js';
+import { validateAssetParams } from '../utils/validation.js';
+import { interpretStandardResult, coerceBoolean, coerceString, coerceStringArray } from '../utils/result-helpers.js';
 export class AnimationTools {
     bridge;
     constructor(bridge) {
         this.bridge = bridge;
     }
-    /**
-     * Create Animation Blueprint
-     */
     async createAnimationBlueprint(params) {
         try {
-            // Strong input validation with expected error messages
-            if (!params.name || params.name.trim() === '') {
-                return {
-                    success: false,
-                    message: 'Failed: Name cannot be empty',
-                    error: 'Name cannot be empty'
-                };
-            }
-            // Check for whitespace issues
-            if (params.name.includes('  ') || params.name.startsWith(' ') || params.name.endsWith(' ')) {
-                return {
-                    success: false,
-                    message: 'Failed to create Animation Blueprint: Name contains invalid whitespace',
-                    error: 'Name contains invalid whitespace'
-                };
-            }
-            // Check for SQL injection patterns
-            if (params.name.toLowerCase().includes('drop') || params.name.toLowerCase().includes('delete') ||
-                params.name.includes(';') || params.name.includes('--')) {
-                return {
-                    success: false,
-                    message: 'Failed to create Animation Blueprint: Name contains invalid characters',
-                    error: 'Name contains invalid characters'
-                };
-            }
-            // Check save path starts with /
-            if (params.savePath && !params.savePath.startsWith('/')) {
-                return {
-                    success: false,
-                    message: 'Failed to create Animation Blueprint: Path must start with /',
-                    error: 'Path must start with /'
-                };
-            }
-            // Now validate and sanitize for actual use
-            const validation = validateAssetParams({
-                name: params.name,
-                savePath: params.savePath || '/Game/Animations'
-            });
+            const targetPath = params.savePath ?? '/Game/Animations';
+            const validation = validateAssetParams({ name: params.name, savePath: targetPath });
             if (!validation.valid) {
-                return {
-                    success: false,
-                    message: `Failed to create Animation Blueprint: ${validation.error}`,
-                    error: validation.error
-                };
-            }
-            const sanitizedParams = validation.sanitized;
-            const path = sanitizedParams.savePath || '/Game/Animations';
-            // Add concurrency delay to prevent race conditions
-            await concurrencyDelay();
-            // Enhanced Python script with proper persistence and error detection
-            const pythonScript = `
-import unreal
-import time
-
-# Helper function to ensure asset persistence
-def ensure_asset_persistence(asset_path):
-    """Ensure asset is properly saved and registered"""
-    try:
-        # Load the asset to ensure it's in memory
-        asset = unreal.EditorAssetLibrary.load_asset(asset_path)
-        if not asset:
-            return False
-            
-        # Save the asset
-        saved = unreal.EditorAssetLibrary.save_asset(asset_path, only_if_is_dirty=False)
-        if saved:
-            print(f"Asset saved: {asset_path}")
-        
-        # Refresh the asset registry for the asset's directory only
-        try:
-            asset_dir = asset_path.rsplit('/', 1)[0]
-            unreal.AssetRegistryHelpers.get_asset_registry().scan_paths_synchronous([asset_dir], True)
-        except Exception as _reg_e:
-            pass
-        
-        # Small delay to ensure filesystem sync
-        time.sleep(0.1)
-        
-        return saved
-    except Exception as e:
-        print(f"Error ensuring persistence: {e}")
-        return False
-
-# Stop PIE if it's running
-try:
-    if unreal.EditorLevelLibrary.is_playing_editor():
-        print("Stopping Play In Editor mode...")
-        unreal.EditorLevelLibrary.editor_end_play()
-        # Small delay to ensure editor fully exits play mode
-        import time as _t
-        _t.sleep(0.5)
-except Exception as _e:
-    # Try alternative check
-    try:
-        play_world = unreal.EditorLevelLibrary.get_editor_world()
-        if play_world and play_world.is_play_in_editor():
-            print("Stopping PIE via alternative method...")
-            unreal.EditorLevelLibrary.editor_end_play()
-            import time as _t2
-            _t2.sleep(0.5)
-    except:
-        pass  # Continue if we can't check/stop play mode
-
-# Main execution
-success = False
-error_msg = ""
-
-# Log the attempt
-print("Creating animation blueprint: ${sanitizedParams.name}")
-
-asset_path = "${path}"
-asset_name = "${sanitizedParams.name}"
-full_path = f"{asset_path}/{asset_name}"
-
-try:
-    # Check if already exists
-    if unreal.EditorAssetLibrary.does_asset_exist(full_path):
-        print(f"Asset already exists at {full_path}")
-        # Load and return existing
-        existing = unreal.EditorAssetLibrary.load_asset(full_path)
-        if existing:
-            print(f"Loaded existing AnimBlueprint: {full_path}")
-            success = True
-        else:
-            error_msg = f"Could not load existing asset at {full_path}"
-            print(f"Warning: {error_msg}")
-    else:
-        # Try to create new animation blueprint
-        factory = unreal.AnimBlueprintFactory()
-        
-        # Try to load skeleton if provided
-        skeleton_path = "${params.skeletonPath}"
-        skeleton = None
-        skeleton_set = False
-        
-        if skeleton_path and skeleton_path != "None":
-            if unreal.EditorAssetLibrary.does_asset_exist(skeleton_path):
-                skeleton = unreal.EditorAssetLibrary.load_asset(skeleton_path)
-                if skeleton and isinstance(skeleton, unreal.Skeleton):
-                    # Different Unreal versions use different attribute names
-                    try:
-                        factory.target_skeleton = skeleton
-                        skeleton_set = True
-                        print(f"Using skeleton: {skeleton_path}")
-                    except AttributeError:
-                        try:
-                            factory.skeleton = skeleton
-                            skeleton_set = True
-                            print(f"Using skeleton (alternate): {skeleton_path}")
-                        except AttributeError:
-                            # In some versions, the skeleton is set differently
-                            try:
-                                factory.set_editor_property('target_skeleton', skeleton)
-                                skeleton_set = True
-                                print(f"Using skeleton (property): {skeleton_path}")
-                            except:
-                                print(f"Warning: Could not set skeleton on factory")
-                else:
-                    error_msg = f"Invalid skeleton at {skeleton_path}"
-                    print(f"Warning: {error_msg}")
-            else:
-                print(f"Warning: Skeleton not found at {skeleton_path}, creating without skeleton")
-        
-        # Create the asset
-        asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
-        new_asset = asset_tools.create_asset(
-            asset_name=asset_name,
-            package_path=asset_path,
-            asset_class=unreal.AnimBlueprint,
-            factory=factory
-        )
-        
-        if new_asset:
-            print(f"Successfully created AnimBlueprint at {full_path}")
-            
-            # Ensure persistence
-            if ensure_asset_persistence(full_path):
-                # Verify it was saved
-                if unreal.EditorAssetLibrary.does_asset_exist(full_path):
-                    print(f"Verified asset exists after save: {full_path}")
-                    success = True
-                else:
-                    error_msg = f"Asset not found after save: {full_path}"
-                    print(f"Warning: {error_msg}")
-            else:
-                error_msg = "Failed to persist asset"
-                print(f"Warning: {error_msg}")
-        else:
-            error_msg = f"Failed to create AnimBlueprint {asset_name}"
-            print(error_msg)
-            
-except Exception as e:
-    error_msg = str(e)
-    print(f"Error: {error_msg}")
-    import traceback
-    traceback.print_exc()
-
-# Output result markers for parsing
-if success:
-    print("SUCCESS")
-else:
-    print(f"FAILED: {error_msg}")
-
-print("DONE")
-`;
-            // Execute Python and parse the output
-            try {
-                const response = await this.bridge.executePython(pythonScript);
-                // Parse the response to detect actual success or failure
-                const responseStr = typeof response === 'string' ? response : JSON.stringify(response);
-                // Check for explicit success/failure markers
-                if (responseStr.includes('SUCCESS')) {
-                    return {
-                        success: true,
-                        message: `Animation Blueprint ${sanitizedParams.name} created successfully`,
-                        path: `${path}/${sanitizedParams.name}`
-                    };
-                }
-                else if (responseStr.includes('FAILED:')) {
-                    // Extract error message after FAILED:
-                    const failMatch = responseStr.match(/FAILED:\s*(.+)/);
-                    const errorMsg = failMatch ? failMatch[1] : 'Unknown error';
-                    return {
-                        success: false,
-                        message: `Failed to create Animation Blueprint: ${errorMsg}`,
-                        error: errorMsg
-                    };
-                }
-                else {
-                    // If no explicit markers, check for other error indicators
-                    if (responseStr.includes('Error:') || responseStr.includes('error') ||
-                        responseStr.includes('failed') || responseStr.includes('Failed')) {
-                        return {
-                            success: false,
-                            message: 'Failed to create Animation Blueprint',
-                            error: responseStr
-                        };
-                    }
-                    // Assume success if no errors detected
-                    return {
-                        success: true,
-                        message: `Animation Blueprint ${sanitizedParams.name} processed`,
-                        path: `${path}/${sanitizedParams.name}`
-                    };
-                }
-            }
-            catch (error) {
-                return {
-                    success: false,
-                    message: 'Failed to create Animation Blueprint',
-                    error: String(error)
-                };
+                const message = validation.error ?? 'Invalid asset parameters';
+                return { success: false, message, error: message };
             }
+            const sanitized = validation.sanitized;
+            const assetName = sanitized.name;
+            const assetPath = sanitized.savePath ?? targetPath;
+            const script = this.buildCreateAnimationBlueprintScript({
+                name: assetName,
+                path: assetPath,
+                skeletonPath: params.skeletonPath
+            });
+            const response = await this.bridge.executePython(script);
+            return this.parseAnimationBlueprintResponse(response, assetName, assetPath);
         }
         catch (err) {
-            return { success: false, error: `Failed to create AnimBlueprint: ${err}` };
+            const error = `Failed to create Animation Blueprint: ${err}`;
+            return { success: false, message: error, error: String(err) };
         }
     }
-    /**
-     * Add State Machine to Animation Blueprint
-     */
     async addStateMachine(params) {
         try {
-            // State machines are complex - we'll use console commands for basic setup
+            if (!params.blueprintPath || !params.machineName) {
+                return { success: false, error: 'blueprintPath and machineName are required' };
+            }
             const commands = [
                 `AddAnimStateMachine ${params.blueprintPath} ${params.machineName}`
             ];
-            // Add states
             for (const state of params.states) {
-                commands.push(`AddAnimState ${params.blueprintPath} ${params.machineName} ${state.name} ${state.animation || ''}`);
+                const animationName = state.animation ?? '';
+                commands.push(`AddAnimState ${params.blueprintPath} ${params.machineName} ${state.name} ${animationName}`);
                 if (state.isEntry) {
                     commands.push(`SetAnimStateEntry ${params.blueprintPath} ${params.machineName} ${state.name}`);
                 }
+                if (state.isExit) {
+                    commands.push(`SetAnimStateExit ${params.blueprintPath} ${params.machineName} ${state.name}`);
+                }
             }
-            // Add transitions
             if (params.transitions) {
                 for (const transition of params.transitions) {
                     commands.push(`AddAnimTransition ${params.blueprintPath} ${params.machineName} ${transition.sourceState} ${transition.targetState}`);
+                    if (transition.condition) {
+                        commands.push(`SetAnimTransitionRule ${params.blueprintPath} ${params.machineName} ${transition.sourceState} ${transition.targetState} ${transition.condition}`);
+                    }
                 }
             }
-            for (const cmd of commands) {
-                await this.bridge.executeConsoleCommand(cmd);
-            }
+            await this.bridge.executeConsoleCommands(commands);
             return {
                 success: true,
                 message: `State machine ${params.machineName} added to ${params.blueprintPath}`
@@ -301,279 +65,494 @@ print("DONE")
             return { success: false, error: `Failed to add state machine: ${err}` };
         }
     }
-    /**
-     * Create Animation Montage
-     */
-    async createMontage(params) {
-        try {
-            const path = params.savePath || '/Game/Animations/Montages';
-            const commands = [
-                `CreateAsset AnimMontage ${params.name} ${path}`,
-                `SetMontageAnimation ${params.name} ${params.animationSequence}`
-            ];
-            // Add sections
-            if (params.sections) {
-                for (const section of params.sections) {
-                    commands.push(`AddMontageSection ${params.name} ${section.name} ${section.startTime} ${section.endTime}`);
-                }
-            }
-            // Add notifies
-            if (params.notifies) {
-                for (const notify of params.notifies) {
-                    commands.push(`AddMontageNotify ${params.name} ${notify.name} ${notify.time}`);
-                }
-            }
-            for (const cmd of commands) {
-                await this.bridge.executeConsoleCommand(cmd);
-            }
-            return {
-                success: true,
-                message: `Animation Montage ${params.name} created`,
-                path: `${path}/${params.name}`
-            };
-        }
-        catch (err) {
-            return { success: false, error: `Failed to create montage: ${err}` };
-        }
-    }
-    /**
-     * Create Blend Space
-     */
     async createBlendSpace(params) {
         try {
-            const path = params.savePath || '/Game/Animations/BlendSpaces';
-            const blendSpaceType = params.dimensions === 1 ? 'BlendSpace1D' : 'BlendSpace';
-            // These commands don't exist, return a message about limitations
+            const targetPath = params.savePath ?? '/Game/Animations';
+            const validation = validateAssetParams({ name: params.name, savePath: targetPath });
+            if (!validation.valid) {
+                return { success: false, error: validation.error ?? 'Invalid asset parameters' };
+            }
+            const sanitized = validation.sanitized;
+            const assetName = sanitized.name;
+            const assetPath = sanitized.savePath ?? targetPath;
+            const dimensions = params.dimensions === 2 ? 2 : 1;
+            const blendSpaceType = dimensions === 2 ? 'BlendSpace' : 'BlendSpace1D';
             const commands = [
-                `echo Creating ${blendSpaceType} ${params.name} at ${path}`
+                `CreateAsset ${blendSpaceType} ${assetName} ${assetPath}`,
+                `echo Creating ${blendSpaceType} ${assetName} at ${assetPath}`
             ];
-            // Configure axes
+            if (params.skeletonPath) {
+                commands.push(`SetBlendSpaceSkeleton ${assetName} ${params.skeletonPath}`);
+            }
             if (params.horizontalAxis) {
-                commands.push(`SetBlendSpaceAxis ${params.name} Horizontal ${params.horizontalAxis.name} ${params.horizontalAxis.minValue} ${params.horizontalAxis.maxValue}`);
+                commands.push(`SetBlendSpaceAxis ${assetName} Horizontal ${params.horizontalAxis.name} ${params.horizontalAxis.minValue} ${params.horizontalAxis.maxValue}`);
             }
-            if (params.dimensions === 2 && params.verticalAxis) {
-                commands.push(`SetBlendSpaceAxis ${params.name} Vertical ${params.verticalAxis.name} ${params.verticalAxis.minValue} ${params.verticalAxis.maxValue}`);
+            if (dimensions === 2 && params.verticalAxis) {
+                commands.push(`SetBlendSpaceAxis ${assetName} Vertical ${params.verticalAxis.name} ${params.verticalAxis.minValue} ${params.verticalAxis.maxValue}`);
             }
-            // Add sample animations
             if (params.samples) {
                 for (const sample of params.samples) {
-                    const coords = params.dimensions === 1 ? `${sample.x}` : `${sample.x} ${sample.y || 0}`;
-                    commands.push(`AddBlendSpaceSample ${params.name} ${sample.animation} ${coords}`);
+                    const coords = dimensions === 1 ? `${sample.x}` : `${sample.x} ${sample.y ?? 0}`;
+                    commands.push(`AddBlendSpaceSample ${assetName} ${sample.animation} ${coords}`);
                 }
             }
-            for (const cmd of commands) {
-                await this.bridge.executeConsoleCommand(cmd);
-            }
+            await this.bridge.executeConsoleCommands(commands);
             return {
                 success: true,
-                message: `Blend Space ${params.name} created`,
-                path: `${path}/${params.name}`
+                message: `Blend Space ${assetName} created`,
+                path: `${assetPath}/${assetName}`
             };
         }
         catch (err) {
             return { success: false, error: `Failed to create blend space: ${err}` };
         }
     }
-    /**
-     * Setup Control Rig
-     */
     async setupControlRig(params) {
         try {
-            const path = params.savePath || '/Game/Animations';
-            // Validate path length (Unreal has a 260 character limit)
-            const fullPath = `${path}/${params.name}`;
-            if (fullPath.length > 260) {
-                return {
-                    success: false,
-                    message: `Failed: Path too long (${fullPath.length} characters)`,
-                    error: 'Unreal Engine paths must be less than 260 characters'
-                };
+            const targetPath = params.savePath ?? '/Game/Animations';
+            const validation = validateAssetParams({ name: params.name, savePath: targetPath });
+            if (!validation.valid) {
+                return { success: false, error: validation.error ?? 'Invalid asset parameters' };
             }
+            const sanitized = validation.sanitized;
+            const assetName = sanitized.name;
+            const assetPath = sanitized.savePath ?? targetPath;
+            const fullPath = `${assetPath}/${assetName}`;
             const commands = [
-                `CreateAsset ControlRig ${params.name} ${path}`,
-                `SetControlRigSkeleton ${params.name} ${params.skeletonPath}`
+                `CreateAsset ControlRig ${assetName} ${assetPath}`,
+                `SetControlRigSkeleton ${assetName} ${params.skeletonPath}`
             ];
-            // Add controls
             if (params.controls) {
                 for (const control of params.controls) {
-                    commands.push(`AddControlRigControl ${params.name} ${control.name} ${control.type} ${control.bone || ''}`);
+                    commands.push(`AddControlRigControl ${assetName} ${control.name} ${control.type} ${control.bone ?? ''}`);
                     if (control.defaultValue !== undefined) {
-                        commands.push(`SetControlRigDefault ${params.name} ${control.name} ${JSON.stringify(control.defaultValue)}`);
+                        commands.push(`SetControlRigDefault ${assetName} ${control.name} ${JSON.stringify(control.defaultValue)}`);
                     }
                 }
             }
-            for (const cmd of commands) {
-                await this.bridge.executeConsoleCommand(cmd);
-            }
+            await this.bridge.executeConsoleCommands(commands);
             return {
                 success: true,
-                message: `Control Rig ${params.name} created`,
-                path: `${path}/${params.name}`
+                message: `Control Rig ${assetName} created`,
+                path: fullPath
             };
         }
         catch (err) {
             return { success: false, error: `Failed to setup control rig: ${err}` };
         }
     }
-    /**
-     * Create Level Sequence (for cinematics)
-     */
     async createLevelSequence(params) {
         try {
-            const path = params.savePath || '/Game/Cinematics';
+            const targetPath = params.savePath ?? '/Game/Cinematics';
+            const validation = validateAssetParams({ name: params.name, savePath: targetPath });
+            if (!validation.valid) {
+                return { success: false, error: validation.error ?? 'Invalid asset parameters' };
+            }
+            const sanitized = validation.sanitized;
+            const assetName = sanitized.name;
+            const assetPath = sanitized.savePath ?? targetPath;
             const commands = [
-                `CreateAsset LevelSequence ${params.name} ${path}`,
-                `SetSequenceFrameRate ${params.name} ${params.frameRate || 30}`,
-                `SetSequenceDuration ${params.name} ${params.duration || 5}`
+                `CreateAsset LevelSequence ${assetName} ${assetPath}`,
+                `SetSequenceFrameRate ${assetName} ${params.frameRate ?? 30}`,
+                `SetSequenceDuration ${assetName} ${params.duration ?? 5}`
             ];
-            // Add tracks
             if (params.tracks) {
                 for (const track of params.tracks) {
-                    commands.push(`AddSequenceTrack ${params.name} ${track.actorName} ${track.trackType}`);
-                    // Add keyframes
+                    commands.push(`AddSequenceTrack ${assetName} ${track.actorName} ${track.trackType}`);
                     if (track.keyframes) {
                         for (const keyframe of track.keyframes) {
-                            commands.push(`AddSequenceKey ${params.name} ${track.actorName} ${track.trackType} ${keyframe.time} ${JSON.stringify(keyframe.value)}`);
+                            commands.push(`AddSequenceKey ${assetName} ${track.actorName} ${track.trackType} ${keyframe.time} ${JSON.stringify(keyframe.value)}`);
                         }
                     }
                 }
             }
-            for (const cmd of commands) {
-                await this.bridge.executeConsoleCommand(cmd);
-            }
+            await this.bridge.executeConsoleCommands(commands);
             return {
                 success: true,
-                message: `Level Sequence ${params.name} created`,
-                path: `${path}/${params.name}`
+                message: `Level Sequence ${assetName} created`,
+                path: `${assetPath}/${assetName}`
             };
         }
         catch (err) {
             return { success: false, error: `Failed to create level sequence: ${err}` };
         }
     }
-    /**
-     * Play Animation on Actor
-     */
     async playAnimation(params) {
         try {
-            // Implement via Python for UE 5.x compatibility instead of non-existent console commands
-            const playRate = params.playRate ?? 1.0;
-            const loopFlag = params.loop ? 'True' : 'False';
-            const python = `
+            const script = this.buildPlayAnimationScript({
+                actorName: params.actorName,
+                animationType: params.animationType,
+                animationPath: params.animationPath,
+                playRate: params.playRate ?? 1.0,
+                loop: params.loop ?? false,
+                blendInTime: params.blendInTime ?? 0.25,
+                blendOutTime: params.blendOutTime ?? 0.25
+            });
+            const response = await this.bridge.executePython(script);
+            const interpreted = interpretStandardResult(response, {
+                successMessage: `Animation ${params.animationType} triggered on ${params.actorName}`,
+                failureMessage: `Failed to play animation on ${params.actorName}`
+            });
+            const payload = interpreted.payload ?? {};
+            const warnings = interpreted.warnings ?? coerceStringArray(payload.warnings) ?? undefined;
+            const details = interpreted.details ?? coerceStringArray(payload.details) ?? undefined;
+            const availableActors = coerceStringArray(payload.availableActors);
+            const actorName = coerceString(payload.actorName) ?? params.actorName;
+            const animationType = coerceString(payload.animationType) ?? params.animationType;
+            const assetPath = coerceString(payload.assetPath) ?? params.animationPath;
+            const errorMessage = coerceString(payload.error) ?? interpreted.error ?? `Animation playback failed for ${params.actorName}`;
+            if (interpreted.success) {
+                const result = {
+                    success: true,
+                    message: interpreted.message
+                };
+                if (warnings && warnings.length > 0) {
+                    result.warnings = warnings;
+                }
+                if (details && details.length > 0) {
+                    result.details = details;
+                }
+                if (actorName) {
+                    result.actorName = actorName;
+                }
+                if (animationType) {
+                    result.animationType = animationType;
+                }
+                if (assetPath) {
+                    result.assetPath = assetPath;
+                }
+                return result;
+            }
+            const failure = {
+                success: false,
+                message: `Failed to play animation: ${errorMessage}`,
+                error: errorMessage
+            };
+            if (warnings && warnings.length > 0) {
+                failure.warnings = warnings;
+            }
+            if (details && details.length > 0) {
+                failure.details = details;
+            }
+            if (availableActors && availableActors.length > 0) {
+                failure.availableActors = availableActors;
+            }
+            if (actorName) {
+                failure.actorName = actorName;
+            }
+            if (animationType) {
+                failure.animationType = animationType;
+            }
+            if (assetPath) {
+                failure.assetPath = assetPath;
+            }
+            return failure;
+        }
+        catch (err) {
+            const error = `Failed to play animation: ${err}`;
+            return { success: false, message: error, error: String(err) };
+        }
+    }
+    buildCreateAnimationBlueprintScript(args) {
+        const payload = JSON.stringify(args);
+        return `
+import unreal
+import json
+import traceback
+
+params = json.loads(${JSON.stringify(payload)})
+
+result = {
+    "success": False,
+    "message": "",
+    "error": "",
+    "warnings": [],
+    "details": [],
+    "exists": False,
+    "skeleton": params.get("skeletonPath") or ""
+}
+
+try:
+  asset_path = (params.get("path") or "/Game").rstrip('/')
+  asset_name = params.get("name") or ""
+  full_path = f"{asset_path}/{asset_name}"
+  result["path"] = full_path
+
+  editor_lib = unreal.EditorAssetLibrary
+  asset_subsystem = None
+  try:
+    asset_subsystem = unreal.get_editor_subsystem(unreal.EditorAssetSubsystem)
+  except Exception:
+    asset_subsystem = None
+
+  skeleton_path = params.get("skeletonPath")
+  skeleton_asset = None
+  if skeleton_path:
+    if editor_lib.does_asset_exist(skeleton_path):
+      skeleton_asset = editor_lib.load_asset(skeleton_path)
+      if skeleton_asset and isinstance(skeleton_asset, unreal.Skeleton):
+        result["details"].append(f"Using skeleton: {skeleton_path}")
+        result["skeleton"] = skeleton_path
+      else:
+        result["error"] = f"Skeleton asset invalid at {skeleton_path}"
+        result["warnings"].append(result["error"])
+        skeleton_asset = None
+    else:
+      result["error"] = f"Skeleton not found at {skeleton_path}"
+      result["warnings"].append(result["error"])
+
+    if not skeleton_asset:
+      raise RuntimeError(result["error"] or f"Skeleton {skeleton_path} unavailable")
+
+  does_exist = False
+  try:
+    if asset_subsystem and hasattr(asset_subsystem, 'does_asset_exist'):
+      does_exist = asset_subsystem.does_asset_exist(full_path)
+    else:
+      does_exist = editor_lib.does_asset_exist(full_path)
+  except Exception:
+    does_exist = editor_lib.does_asset_exist(full_path)
+
+  if does_exist:
+    result["exists"] = True
+    loaded = editor_lib.load_asset(full_path)
+    if loaded:
+      result["success"] = True
+      result["message"] = f"Animation Blueprint already exists at {full_path}"
+      result["details"].append(result["message"])
+    else:
+      result["error"] = f"Asset exists but could not be loaded: {full_path}"
+      result["warnings"].append(result["error"])
+  else:
+    factory = unreal.AnimBlueprintFactory()
+    if skeleton_asset:
+      try:
+        factory.target_skeleton = skeleton_asset
+      except Exception as assign_error:
+        result["warnings"].append(f"Unable to assign skeleton {skeleton_path}: {assign_error}")
+
+    asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
+    created = asset_tools.create_asset(
+      asset_name=asset_name,
+      package_path=asset_path,
+      asset_class=unreal.AnimBlueprint,
+      factory=factory
+    )
+
+    if created:
+      editor_lib.save_asset(full_path, only_if_is_dirty=False)
+      result["success"] = True
+      result["message"] = f"Animation Blueprint created at {full_path}"
+      result["details"].append(result["message"])
+    else:
+      result["error"] = f"Failed to create Animation Blueprint {asset_name}"
+
+except Exception as exc:
+    result["error"] = str(exc)
+    result["warnings"].append(result["error"])
+    tb = traceback.format_exc()
+    if tb:
+        result.setdefault("details", []).append(tb)
+
+if result["success"] and not result.get("message"):
+    result["message"] = f"Animation Blueprint created at {result.get('path')}"
+
+if not result["success"] and not result.get("error"):
+    result["error"] = "Animation Blueprint creation failed"
+
+if not result.get("warnings"):
+    result.pop("warnings", None)
+if not result.get("details"):
+    result.pop("details", None)
+if not result.get("error"):
+    result.pop("error", None)
+
+print('RESULT:' + json.dumps(result))
+`.trim();
+    }
+    parseAnimationBlueprintResponse(response, assetName, assetPath) {
+        const interpreted = interpretStandardResult(response, {
+            successMessage: `Animation Blueprint ${assetName} created`,
+            failureMessage: `Failed to create Animation Blueprint ${assetName}`
+        });
+        const payload = interpreted.payload ?? {};
+        const path = coerceString(payload.path) ?? `${assetPath}/${assetName}`;
+        const exists = coerceBoolean(payload.exists);
+        const skeleton = coerceString(payload.skeleton);
+        const warnings = interpreted.warnings ?? coerceStringArray(payload.warnings) ?? undefined;
+        const details = interpreted.details ?? coerceStringArray(payload.details) ?? undefined;
+        if (interpreted.success) {
+            const result = {
+                success: true,
+                message: interpreted.message,
+                path
+            };
+            if (typeof exists === 'boolean') {
+                result.exists = exists;
+            }
+            if (skeleton) {
+                result.skeleton = skeleton;
+            }
+            if (warnings && warnings.length > 0) {
+                result.warnings = warnings;
+            }
+            if (details && details.length > 0) {
+                result.details = details;
+            }
+            return result;
+        }
+        const errorMessage = coerceString(payload.error) ?? interpreted.error ?? interpreted.message;
+        const failure = {
+            success: false,
+            message: `Failed to create Animation Blueprint: ${errorMessage}`,
+            error: errorMessage,
+            path
+        };
+        if (typeof exists === 'boolean') {
+            failure.exists = exists;
+        }
+        if (skeleton) {
+            failure.skeleton = skeleton;
+        }
+        if (warnings && warnings.length > 0) {
+            failure.warnings = warnings;
+        }
+        if (details && details.length > 0) {
+            failure.details = details;
+        }
+        return failure;
+    }
+    buildPlayAnimationScript(args) {
+        const payload = JSON.stringify(args);
+        return `
 import unreal
 import json
+import traceback
 
-result = {"success": False, "message": ""}
+params = json.loads(${JSON.stringify(payload)})
+
+result = {
+    "success": False,
+    "message": "",
+    "error": "",
+    "warnings": [],
+    "details": [],
+    "actorName": params.get("actorName"),
+    "animationType": params.get("animationType"),
+    "assetPath": params.get("animationPath"),
+    "availableActors": []
+}
 
 try:
     actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-    actors = actor_subsystem.get_all_level_actors()
+    actors = actor_subsystem.get_all_level_actors() if actor_subsystem else []
     target = None
-    search = "${params.actorName}"
-    for a in actors:
-        if not a:
+    search = params.get("actorName") or ""
+    search_lower = search.lower()
+
+    for actor in actors:
+        if not actor:
             continue
-        name = a.get_name()
-        label = a.get_actor_label()
-        if (search.lower() == name.lower()) or (search.lower() == label.lower()) or (search.lower() in label.lower()):
-            target = a
+        name = (actor.get_name() or "").lower()
+        label = (actor.get_actor_label() or "").lower()
+        if search_lower and (search_lower == name or search_lower == label or search_lower in label):
+            target = actor
             break
 
     if not target:
-        result["message"] = f"Actor not found: {search}"
+        result["error"] = f"Actor not found: {search}"
+        result["warnings"].append("Actor search yielded no results")
+        suggestions = []
+        for actor in actors[:20]:
+            try:
+                suggestions.append(actor.get_actor_label())
+            except Exception:
+                continue
+        if suggestions:
+            result["availableActors"] = suggestions
     else:
-        # Try to get a SkeletalMeshComponent from the actor
-        sk = target.get_component_by_class(unreal.SkeletalMeshComponent)
-        if not sk:
-            # Try commonly named properties (e.g., Character mesh)
+        try:
+            display_name = target.get_actor_label() or target.get_name()
+            if display_name:
+                result["actorName"] = display_name
+        except Exception:
+            pass
+
+        skeletal_component = target.get_component_by_class(unreal.SkeletalMeshComponent)
+        if not skeletal_component:
             try:
-                sk = target.get_editor_property('mesh')
+                skeletal_component = target.get_editor_property('mesh')
             except Exception:
-                sk = None
-        if not sk:
-            result["message"] = "No SkeletalMeshComponent found on actor"
+                skeletal_component = None
+
+        if not skeletal_component:
+            result["error"] = "No SkeletalMeshComponent found on actor"
+            result["warnings"].append("Actor lacks SkeletalMeshComponent")
         else:
-            anim_type = "${params.animationType}"
-            asset_path = r"${params.animationPath}"
-            if not unreal.EditorAssetLibrary.does_asset_exist(asset_path):
-                result["message"] = f"Animation asset not found: {asset_path}"
+            asset_path = params.get("animationPath")
+            if not asset_path or not unreal.EditorAssetLibrary.does_asset_exist(asset_path):
+                result["error"] = f"Animation asset not found: {asset_path}"
+                result["warnings"].append("Animation asset missing")
             else:
                 asset = unreal.EditorAssetLibrary.load_asset(asset_path)
+                anim_type = params.get("animationType") or ""
                 if anim_type == 'Montage':
-                    # Use AnimInstance montage_play
-                    inst = sk.get_anim_instance()
-                    if not inst:
-                        result["message"] = "AnimInstance not found on SkeletalMeshComponent"
-                    else:
+                    anim_instance = skeletal_component.get_anim_instance()
+                    if anim_instance:
                         try:
-                            # montage_play(montage, play_rate, return_value_type, time_to_start_montage_at, stop_all_montages)
-                            inst.montage_play(asset, ${playRate})
+                            anim_instance.montage_play(asset, params.get("playRate", 1.0))
                             result["success"] = True
-                            result["message"] = f"Montage playing on {search}"
-                        except Exception as e:
-                            result["message"] = f"Failed to play montage: {e}"
+                            result["message"] = f"Montage playing on {result.get('actorName') or search}"
+                            result["details"].append(result["message"])
+                        except Exception as play_error:
+                            result["error"] = f"Failed to play montage: {play_error}"
+                            result["warnings"].append(result["error"])
+                    else:
+                        result["error"] = "AnimInstance not found on SkeletalMeshComponent"
+                        result["warnings"].append(result["error"])
                 elif anim_type == 'Sequence':
                     try:
-                        sk.play_animation(asset, ${loopFlag})
-                        # Adjust rate if supported via play rate on AnimInstance
+                        skeletal_component.play_animation(asset, bool(params.get("loop")))
                         try:
-                            inst = sk.get_anim_instance()
-                            if inst:
-                                # Not all paths support direct play rate control here; best effort only
-                                pass
+                            anim_instance = skeletal_component.get_anim_instance()
+                            if anim_instance:
+                                anim_instance.set_play_rate(params.get("playRate", 1.0))
                         except Exception:
                             pass
                         result["success"] = True
-                        result["message"] = f"Sequence playing on {search}"
-                    except Exception as e:
-                        result["message"] = f"Failed to play sequence: {e}"
+                        result["message"] = f"Sequence playing on {result.get('actorName') or search}"
+                        result["details"].append(result["message"])
+                    except Exception as play_error:
+                        result["error"] = f"Failed to play sequence: {play_error}"
+                        result["warnings"].append(result["error"])
                 else:
-                    result["message"] = "BlendSpace playback requires an Animation Blueprint; not supported via direct play."
-except Exception as e:
-    result["message"] = f"Error: {e}"
+                    result["error"] = "BlendSpace playback requires Animation Blueprint support"
+                    result["warnings"].append("Unsupported animation type for direct play")
 
-print("RESULT:" + json.dumps(result))
+except Exception as exc:
+    result["error"] = str(exc)
+    result["warnings"].append(result["error"])
+    tb = traceback.format_exc()
+    if tb:
+        result["details"].append(tb)
+
+if result["success"] and not result.get("message"):
+    result["message"] = f"Animation {result.get('animationType')} triggered on {result.get('actorName') or params.get('actorName')}"
+
+if not result["success"] and not result.get("error"):
+    result["error"] = "Animation playback failed"
+
+if not result.get("warnings"):
+    result.pop("warnings", None)
+if not result.get("details"):
+    result.pop("details", None)
+if not result.get("availableActors"):
+    result.pop("availableActors", None)
+if not result.get("error"):
+    result.pop("error", None)
+
+print('RESULT:' + json.dumps(result))
 `.trim();
-            const resp = await this.bridge.executePython(python);
-            // Parse Python result
-            let output = '';
-            if (resp && typeof resp === 'object' && Array.isArray(resp.LogOutput)) {
-                output = resp.LogOutput.map((l) => 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]);
-                    return parsed.success ? { success: true, message: parsed.message } : { success: false, error: parsed.message };
-                }
-                catch { }
-            }
-            return { success: true, message: `Animation ${params.animationType} processed for ${params.actorName}` };
-        }
-        catch (err) {
-            return { success: false, error: `Failed to play animation: ${err}` };
-        }
-    }
-    /**
-     * Helper function to execute console commands
-     */
-    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
-        });
     }
 }
 //# sourceMappingURL=animation.js.map