unreal-engine-mcp-server 0.4.6 → 0.5.0

package/dist/tools/actors.js

@@ -1,10 +1,8 @@
 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;
+import { BaseTool } from './base-tool.js';
+export class ActorTools extends BaseTool {
     constructor(bridge) {
-        this.bridge = bridge;
+        super(bridge);
     }
     async spawn(params) {
         if (!params.classPath || typeof params.classPath !== 'string' || params.classPath.trim().length === 0) {
@@ -28,305 +26,121 @@ export class ActorTools {
         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": "",
-  "error": "",
-  "actorName": "",
-  "requestedClass": "${escapedRequestedPath}",
-  "resolvedClass": "${escapedResolvedClassPath}",
-  "location": [${locX}, ${locY}, ${locZ}],
-  "rotation": [${rotPitch}, ${rotYaw}, ${rotRoll}],
-  "requestedActorName": "${escapedRequestedActorName}",
-  "warnings": [],
-  "details": []
-}
-
-${this.getPythonSpawnHelper()}
-
-abstract_classes = ['PlaneReflectionCapture', 'ReflectionCapture', 'Actor', 'Pawn', 'Character']
-
-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:
-    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:
-          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);
-            const interpreted = interpretStandardResult(response, {
-                successMessage: `Spawned actor ${className}`,
-                failureMessage: `Failed to spawn actor ${className}`
-            });
-            if (!interpreted.success) {
-                throw new Error(interpreted.error || interpreted.message);
+            const bridge = this.getAutomationBridge();
+            const timeoutMs = typeof params.timeoutMs === 'number' && params.timeoutMs > 0 ? params.timeoutMs : undefined;
+            const response = await bridge.sendAutomationRequest('control_actor', {
+                action: 'spawn',
+                classPath: mappedClassPath,
+                location: { x: locX, y: locY, z: locZ },
+                rotation: { pitch: rotPitch, yaw: rotYaw, roll: rotRoll },
+                actorName: sanitizedActorName,
+                meshPath: params.meshPath
+            }, timeoutMs ? { timeoutMs } : undefined);
+            if (!response || !response.success) {
+                throw new Error(response?.error || response?.message || 'Failed to spawn actor');
             }
-            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 data = response.data || {};
             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] }
+                message: response.message || `Spawned actor ${className}`,
+                actorName: data.name || response.actorName,
+                actorPath: data.objectPath || response.actorPath,
+                resolvedClass: mappedClassPath,
+                requestedClass: className,
+                location: { x: locX, y: locY, z: locZ },
+                rotation: { pitch: rotPitch, yaw: rotYaw, roll: rotRoll },
+                data: data,
+                actor: {
+                    name: data.name || response.actorName,
+                    path: data.objectPath || response.actorPath || mappedClassPath
+                }
             };
-            if (interpreted.warnings?.length) {
-                result.warnings = interpreted.warnings;
+            if (response.warnings?.length) {
+                result.warnings = response.warnings;
             }
-            if (interpreted.details?.length) {
-                result.details = interpreted.details;
+            if (response.details?.length) {
+                result.details = response.details;
+            }
+            if (response.componentPaths?.length) {
+                result.componentPaths = response.componentPaths;
             }
             return result;
         }
         catch (err) {
-            throw new Error(`Failed to spawn actor via Python: ${err}`);
+            throw new Error(`Failed to spawn actor: ${err}`);
         }
     }
-    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 = `
-import unreal
-les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
-if les and les.is_in_play_in_editor():
-    print("PIE_ACTIVE")
-else:
-    print("PIE_INACTIVE")
-        `.trim();
-                const pieCheckResult = await this.bridge.executePython(pieCheckPython);
-                const outputStr = typeof pieCheckResult === 'string' ? pieCheckResult : JSON.stringify(pieCheckResult);
-                if (outputStr.includes('PIE_ACTIVE')) {
-                    throw new Error('Cannot spawn actors while in Play In Editor mode. Please stop PIE first.');
-                }
+    async delete(params) {
+        if (params.actorNames && Array.isArray(params.actorNames)) {
+            const names = params.actorNames
+                .filter(name => typeof name === 'string')
+                .map(name => name.trim())
+                .filter(name => name.length > 0);
+            if (names.length === 0) {
+                return {
+                    success: true,
+                    message: 'No actors provided for deletion; no-op',
+                    deleted: [],
+                    noOp: true
+                };
             }
-            catch (pieErr) {
-                // If the error is about PIE, throw it
-                if (String(pieErr).includes('Play In Editor')) {
-                    throw pieErr;
-                }
-                // Otherwise ignore and continue
+            const bridge = this.getAutomationBridge();
+            const response = await bridge.sendAutomationRequest('control_actor', {
+                action: 'delete',
+                actorNames: names
+            });
+            const result = (response?.data || response?.result || response) ?? {};
+            const deleted = result.deleted ?? names;
+            const missing = result.missing ?? [];
+            const errorObj = response?.error;
+            const errorCode = (typeof errorObj === 'object' ? errorObj.code : String(errorObj || result.error || '')).toUpperCase();
+            if (response && response.success === false && errorCode === 'DELETE_PARTIAL') {
+                return {
+                    success: true,
+                    message: errorObj?.message || response.message || 'Some actors could not be deleted',
+                    deleted,
+                    missing,
+                    partial: true
+                };
             }
-            // List of known abstract classes that cannot be spawned
-            const abstractClasses = ['PlaneReflectionCapture', 'ReflectionCapture', 'Actor'];
-            // Check if this is an abstract class
-            if (abstractClasses.includes(params.classPath)) {
-                throw new Error(`Cannot spawn ${params.classPath}: class is abstract and cannot be instantiated`);
+            if (!response || response.success === false) {
+                throw new Error(errorObj?.message || response?.message || 'Failed to delete actors');
             }
-            // Get the console-friendly class name
-            const spawnClass = this.getConsoleClassName(params.classPath);
-            // Use summon command with location if provided
-            const command = `summon ${spawnClass} ${locX} ${locY} ${locZ}`;
-            await this.bridge.httpCall('/remote/object/call', 'PUT', {
-                objectPath: '/Script/Engine.Default__KismetSystemLibrary',
-                functionName: 'ExecuteConsoleCommand',
-                parameters: {
-                    WorldContextObject: null,
-                    Command: command,
-                    SpecificPlayer: null
-                },
-                generateTransaction: false
-            });
-            // Console commands don't reliably report success/failure
-            // We can't guarantee this actually worked, so indicate uncertainty
             return {
                 success: true,
-                message: `Actor spawn attempted via console: ${spawnClass} at ${locX},${locY},${locZ}`,
-                note: 'Console spawn result uncertain - verify in editor'
+                message: response.message || 'Deleted actors',
+                deleted: result.deleted || deleted,
+                ...result
             };
         }
-        catch (err) {
-            throw new Error(`Failed to spawn actor: ${err}`);
+        if (!params.actorName || typeof params.actorName !== 'string') {
+            throw new Error('Invalid actorName');
         }
+        return this.sendRequest('delete', { actorName: params.actorName }, 'control_actor');
     }
-    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();
+    async applyForce(params) {
+        if (!params.actorName || typeof params.actorName !== 'string') {
+            throw new Error('Invalid actorName');
+        }
+        if (!params.force || typeof params.force !== 'object') {
+            throw new Error('Invalid force vector');
+        }
+        const [forceX, forceY, forceZ] = ensureVector3(params.force, 'force vector');
+        if (forceX === 0 && forceY === 0 && forceZ === 0) {
+            return {
+                success: true,
+                message: `Zero force provided for ${params.actorName}; no-op`,
+                physicsEnabled: false,
+                noOp: true
+            };
+        }
+        return this.sendRequest('apply_force', {
+            actorName: params.actorName,
+            force: { x: forceX, y: forceY, z: forceZ }
+        }, 'control_actor');
     }
     resolveActorClass(classPath) {
-        // Map common names to full Unreal class paths
         const classMap = {
             'PointLight': '/Script/Engine.PointLight',
             'DirectionalLight': '/Script/Engine.DirectionalLight',
@@ -349,55 +163,280 @@ def spawn_actor_from_class(actor_class, location, rotation):
             'AtmosphericFog': '/Script/Engine.AtmosphericFog',
             'SphereReflectionCapture': '/Script/Engine.SphereReflectionCapture',
             'BoxReflectionCapture': '/Script/Engine.BoxReflectionCapture',
-            // PlaneReflectionCapture is abstract and cannot be spawned
             'DecalActor': '/Script/Engine.DecalActor'
         };
-        // Check if it's a simple name that needs mapping
         if (classMap[classPath]) {
             return classMap[classPath];
         }
-        // Check if it already looks like a full path
         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
             if (!classPath.startsWith('/Game/')) {
                 return '/Game/' + classPath;
             }
             return classPath;
         }
-        // Default: assume it's an engine class
         return '/Script/Engine.' + classPath;
     }
-    getConsoleClassName(classPath) {
-        // Normalize class path for console 'summon'
-        const input = classPath;
-        // Engine classes: reduce '/Script/Engine.ClassName' to 'ClassName'
-        if (input.startsWith('/Script/Engine.')) {
-            return input.replace('/Script/Engine.', '');
-        }
-        // If it's already a simple class name (no path) and not a /Game asset, strip optional _C and return
-        if (!input.startsWith('/Game/') && !input.includes('/')) {
-            if (input.endsWith('_C'))
-                return input.slice(0, -2);
-            return input;
-        }
-        // Blueprint assets under /Game: ensure '/Game/Path/Asset.Asset_C'
-        if (input.startsWith('/Game/')) {
-            // Remove any existing ".Something" suffix to rebuild normalized class ref
-            const pathWithoutSuffix = input.split('.')[0];
-            const parts = pathWithoutSuffix.split('/');
-            const assetName = parts[parts.length - 1].replace(/_C$/, '');
-            const normalized = `${pathWithoutSuffix}.${assetName}_C`;
-            return normalized;
-        }
-        // Fallback: return input unchanged
-        return input;
+    async spawnBlueprint(params) {
+        const blueprintPath = typeof params.blueprintPath === 'string' ? params.blueprintPath.trim() : '';
+        if (!blueprintPath) {
+            throw new Error('Invalid blueprintPath');
+        }
+        const actorName = typeof params.actorName === 'string' && params.actorName.trim().length > 0 ? params.actorName.trim() : undefined;
+        const location = params.location ? ensureVector3(params.location, 'spawn_blueprint location') : undefined;
+        const rotation = params.rotation ? ensureRotation(params.rotation, 'spawn_blueprint rotation') : undefined;
+        const payload = { blueprintPath };
+        if (actorName)
+            payload.actorName = actorName;
+        if (location)
+            payload.location = { x: location[0], y: location[1], z: location[2] };
+        if (rotation)
+            payload.rotation = { pitch: rotation[0], yaw: rotation[1], roll: rotation[2] };
+        return this.sendRequest('spawn_blueprint', payload, 'control_actor');
+    }
+    async setTransform(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        if (!actorName) {
+            throw new Error('Invalid actorName');
+        }
+        const payload = { actorName };
+        if (params.location) {
+            const loc = ensureVector3(params.location, 'set_transform location');
+            payload.location = { x: loc[0], y: loc[1], z: loc[2] };
+        }
+        if (params.rotation) {
+            const rot = ensureRotation(params.rotation, 'set_transform rotation');
+            payload.rotation = { pitch: rot[0], yaw: rot[1], roll: rot[2] };
+        }
+        if (params.scale) {
+            const scl = ensureVector3(params.scale, 'set_transform scale');
+            payload.scale = { x: scl[0], y: scl[1], z: scl[2] };
+        }
+        return this.sendRequest('set_transform', payload, 'control_actor');
+    }
+    async getTransform(actorName) {
+        if (typeof actorName !== 'string' || actorName.trim().length === 0) {
+            throw new Error('Invalid actorName');
+        }
+        return this.sendRequest('get_transform', { actorName }, 'control_actor')
+            .then(response => {
+            return response;
+        });
+    }
+    async setVisibility(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        if (!actorName) {
+            throw new Error('Invalid actorName');
+        }
+        return this.sendRequest('set_visibility', { actorName, visible: Boolean(params.visible) }, 'control_actor');
+    }
+    async addComponent(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        const componentType = typeof params.componentType === 'string' ? params.componentType.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        if (!componentType)
+            throw new Error('Invalid componentType');
+        return this.sendRequest('add_component', {
+            actorName,
+            componentType,
+            componentName: typeof params.componentName === 'string' ? params.componentName : undefined,
+            properties: params.properties
+        }, 'control_actor');
+    }
+    async setComponentProperties(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        const componentName = typeof params.componentName === 'string' ? params.componentName.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        if (!componentName)
+            throw new Error('Invalid componentName');
+        return this.sendRequest('set_component_properties', {
+            actorName,
+            componentName,
+            properties: params.properties ?? {}
+        }, 'control_actor');
+    }
+    async getComponents(actorName) {
+        if (typeof actorName !== 'string' || actorName.trim().length === 0) {
+            throw new Error('Invalid actorName');
+        }
+        const response = await this.sendRequest('get_components', { actorName }, 'control_actor');
+        if (!response.success) {
+            return { success: false, error: response.error || `Failed to get components for actor ${actorName}` };
+        }
+        const data = response.data ?? response.result ?? response;
+        const components = Array.isArray(data)
+            ? data
+            : (Array.isArray(data?.components) ? data.components : []);
+        const count = typeof data?.count === 'number' ? data.count : components.length;
+        return {
+            success: true,
+            message: 'Actor components retrieved',
+            components,
+            count
+        };
+    }
+    async duplicate(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        const payload = { actorName };
+        if (typeof params.newName === 'string' && params.newName.trim().length > 0) {
+            payload.newName = params.newName.trim();
+        }
+        if (params.offset) {
+            const offs = ensureVector3(params.offset, 'duplicate offset');
+            payload.offset = { x: offs[0], y: offs[1], z: offs[2] };
+        }
+        return this.sendRequest('duplicate', payload, 'control_actor');
+    }
+    async addTag(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        const tag = typeof params.tag === 'string' ? params.tag.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        if (!tag)
+            throw new Error('Invalid tag');
+        return this.sendRequest('add_tag', { actorName, tag }, 'control_actor');
+    }
+    async removeTag(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        const tag = typeof params.tag === 'string' ? params.tag.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        if (!tag)
+            throw new Error('Invalid tag');
+        return this.sendRequest('remove_tag', { actorName, tag }, 'control_actor');
+    }
+    async findByTag(params) {
+        const tag = typeof params.tag === 'string' ? params.tag.trim() : '';
+        if (!tag) {
+            return {
+                success: true,
+                message: 'Empty tag query; no actors matched',
+                data: {
+                    actors: [],
+                    count: 0
+                }
+            };
+        }
+        return this.sendRequest('find_by_tag', {
+            tag,
+            matchType: typeof params.matchType === 'string' ? params.matchType : undefined
+        }, 'control_actor');
+    }
+    async findByName(name) {
+        if (typeof name !== 'string' || name.trim().length === 0) {
+            throw new Error('Invalid actor name query');
+        }
+        return this.sendRequest('find_by_name', { name: name.trim() }, 'control_actor');
+    }
+    async detach(actorName) {
+        if (typeof actorName !== 'string' || actorName.trim().length === 0) {
+            throw new Error('Invalid actorName');
+        }
+        return this.sendRequest('detach', { actorName }, 'control_actor');
+    }
+    async attach(params) {
+        const child = typeof params.childActor === 'string' ? params.childActor.trim() : '';
+        const parent = typeof params.parentActor === 'string' ? params.parentActor.trim() : '';
+        if (!child)
+            throw new Error('Invalid childActor');
+        if (!parent)
+            throw new Error('Invalid parentActor');
+        return this.sendRequest('attach', { childActor: child, parentActor: parent }, 'control_actor');
+    }
+    async deleteByTag(tag) {
+        if (typeof tag !== 'string' || tag.trim().length === 0) {
+            throw new Error('Invalid tag');
+        }
+        return this.sendRequest('delete_by_tag', { tag: tag.trim() }, 'control_actor');
+    }
+    async setBlueprintVariables(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        return this.sendRequest('set_blueprint_variables', { actorName, variables: params.variables ?? {} }, 'control_actor');
+    }
+    async createSnapshot(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        const snapshotName = typeof params.snapshotName === 'string' ? params.snapshotName.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        if (!snapshotName)
+            throw new Error('Invalid snapshotName');
+        return this.sendRequest('create_snapshot', { actorName, snapshotName }, 'control_actor');
+    }
+    async restoreSnapshot(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        const snapshotName = typeof params.snapshotName === 'string' ? params.snapshotName.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        if (!snapshotName)
+            throw new Error('Invalid snapshotName');
+        return this.sendRequest('restore_snapshot', { actorName, snapshotName }, 'control_actor');
+    }
+    async exportActor(params) {
+        const actorName = typeof params.actorName === 'string' ? params.actorName.trim() : '';
+        if (!actorName)
+            throw new Error('Invalid actorName');
+        return this.sendRequest('export', {
+            actorName,
+            destinationPath: params.destinationPath
+        }, 'control_actor');
+    }
+    async getBoundingBox(actorName) {
+        if (typeof actorName !== 'string' || actorName.trim().length === 0) {
+            throw new Error('Invalid actorName');
+        }
+        const response = await this.sendRequest('get_bounding_box', { actorName }, 'control_actor');
+        if (!response.success) {
+            return { success: false, error: response.error || `Failed to get bounding box for actor ${actorName}` };
+        }
+        return {
+            success: true,
+            message: 'Bounding box retrieved',
+            boundingBox: response.data || response.result || {}
+        };
+    }
+    async getMetadata(actorName) {
+        if (typeof actorName !== 'string' || actorName.trim().length === 0) {
+            throw new Error('Invalid actorName');
+        }
+        const response = await this.sendRequest('get_metadata', { actorName }, 'control_actor');
+        if (!response.success) {
+            return { success: false, error: response.error || `Failed to get metadata for actor ${actorName}` };
+        }
+        return {
+            success: true,
+            message: 'Actor metadata retrieved',
+            metadata: response.data || response.result || {}
+        };
+    }
+    async listActors(params) {
+        const payload = {};
+        if (params?.filter) {
+            payload.filter = params.filter;
+        }
+        const response = await this.sendRequest('list_actors', payload, 'control_actor');
+        if (!response.success) {
+            return { success: false, error: response.error || 'Failed to list actors' };
+        }
+        const dataObj = response.data || response.result || {};
+        const actorsRaw = response.actors || (dataObj && dataObj.actors) || (Array.isArray(dataObj) ? dataObj : []);
+        const actors = Array.isArray(actorsRaw) ? actorsRaw : [];
+        return {
+            success: true,
+            message: `Found ${actors.length} actors`,
+            actors,
+            count: actors.length
+        };
     }
 }
 //# sourceMappingURL=actors.js.map