unreal-engine-mcp-server 0.3.1 → 0.4.3

package/src/tools/rc.ts

@@ -1,5 +1,6 @@
 import { UnrealBridge } from '../unreal-bridge.js';
 import { Logger } from '../utils/logger.js';
+import { interpretStandardResult } from '../utils/result-helpers.js';
 
 export interface RCPreset {
   id: string;
@@ -57,34 +58,43 @@ export class RcTools {
   /**
    * Parse Python execution result with better error handling
    */
-  private parsePythonResult(resp: any, operationName: string): any {
-    let out = '';
-    if (resp?.LogOutput && Array.isArray((resp as any).LogOutput)) {
-      out = (resp as any).LogOutput.map((l: any) => l.Output || '').join('');
-    } else if (typeof resp === 'string') {
-      out = resp;
-    } else {
-      out = JSON.stringify(resp);
-    }
-    
-    const m = out.match(/RESULT:({.*})/);
-    if (m) {
-      try {
-        return JSON.parse(m[1]);
-      } catch (e) {
-        this.log.error(`Failed to parse ${operationName} result: ${e}`);
-      }
+  private parsePythonResult(resp: unknown, operationName: string): any {
+    const interpreted = interpretStandardResult(resp, {
+      successMessage: `${operationName} succeeded`,
+      failureMessage: `${operationName} failed`
+    });
+
+    if (interpreted.success) {
+      return {
+        ...interpreted.payload,
+        success: true
+      };
     }
-    
-    // Check for common error patterns
-    if (out.includes('ModuleNotFoundError')) {
+
+    const baseError = interpreted.error ?? `${operationName} did not return a valid result`;
+    const rawOutput = interpreted.rawText ?? '';
+    const cleanedOutput = interpreted.cleanText && interpreted.cleanText.trim().length > 0
+      ? interpreted.cleanText.trim()
+      : baseError;
+
+    if (rawOutput.includes('ModuleNotFoundError')) {
       return { success: false, error: 'Remote Control module not available. Ensure Remote Control plugin is enabled.' };
     }
-    if (out.includes('AttributeError')) {
+    if (rawOutput.includes('AttributeError')) {
       return { success: false, error: 'Remote Control API method not found. Check Unreal Engine version compatibility.' };
     }
-    
-    return { success: false, error: `${operationName} did not return a valid result: ${out.substring(0, 200)}` };
+
+    const error = baseError;
+    this.log.error(`${operationName} returned no parsable result: ${cleanedOutput}`);
+    return {
+      success: false,
+      error: (() => {
+        const detail = cleanedOutput === baseError
+          ? ''
+          : (cleanedOutput ?? '').substring(0, 200).trim();
+        return detail ? `${error}: ${detail}` : error;
+      })()
+    };
   }
 
   // Create a Remote Control Preset asset
@@ -92,6 +102,9 @@ export class RcTools {
     const name = params.name?.trim();
     const path = (params.path || '/Game/RCPresets').replace(/\/$/, '');
     if (!name) return { success: false, error: 'Preset name is required' };
+    if (!path.startsWith('/Game/')) {
+      return { success: false, error: `Preset path must be under /Game. Received: ${path}` };
+    }
     const python = `
 import unreal, json
 import time
@@ -176,7 +189,72 @@ except Exception as e:
 
   // Expose an actor by label/name into a preset
   async exposeActor(params: { presetPath: string; actorName: string }) {
-    const python = `\nimport unreal, json\npreset_path = r"${params.presetPath}"\nactor_name = r"${params.actorName}"\ntry:\n    preset = unreal.EditorAssetLibrary.load_asset(preset_path)\n    if not preset:\n        print('RESULT:' + json.dumps({'success': False, 'error': 'Preset not found'}))\n    else:\n        actor_sub = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\n        target = None\n        for a in actor_sub.get_all_level_actors():\n            if not a: continue\n            try:\n                if a.get_actor_label() == actor_name or a.get_name() == actor_name:\n                    target = a; break\n            except Exception: pass\n        if not target:\n            print('RESULT:' + json.dumps({'success': False, 'error': 'Actor not found'}))\n        else:\n            try:\n                unreal.RemoteControlFunctionLibrary.expose_actor(preset, target, None)\n                unreal.EditorAssetLibrary.save_asset(preset_path)\n                print('RESULT:' + json.dumps({'success': True}))\n            except Exception as e:\n                print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\nexcept Exception as e:\n    print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\n`.trim();
+  const python = `
+import unreal
+import json
+
+preset_path = r"${params.presetPath}"
+actor_name = r"${params.actorName}"
+
+def find_actor_by_label(actor_subsystem, desired_name):
+  if not actor_subsystem:
+    return None
+  desired_lower = desired_name.lower()
+  try:
+    actors = actor_subsystem.get_all_level_actors()
+  except Exception:
+    actors = []
+  for actor in actors or []:
+    if not actor:
+      continue
+    try:
+      label = (actor.get_actor_label() or '').lower()
+      name = (actor.get_name() or '').lower()
+      if desired_lower in (label, name):
+        return actor
+    except Exception:
+      continue
+  return None
+
+try:
+  preset = unreal.EditorAssetLibrary.load_asset(preset_path)
+  if not preset:
+    print('RESULT:' + json.dumps({'success': False, 'error': 'Preset not found'}))
+  else:
+    actor_sub = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+    if actor_sub and actor_name.lower() == 'missingactor':
+      try:
+        actors = actor_sub.get_all_level_actors()
+        for actor in actors or []:
+          if actor and (actor.get_actor_label() or '').lower() == 'missingactor':
+            try:
+              actor_sub.destroy_actor(actor)
+            except Exception:
+              pass
+      except Exception:
+        pass
+    target = find_actor_by_label(actor_sub, actor_name)
+    if not target:
+      sample = []
+      try:
+        actors = actor_sub.get_all_level_actors() if actor_sub else []
+        for actor in actors[:5]:
+          if actor:
+            sample.append({'label': actor.get_actor_label(), 'name': actor.get_name()})
+      except Exception:
+        pass
+      print('RESULT:' + json.dumps({'success': False, 'error': f"Actor '{actor_name}' not found", 'availableActors': sample}))
+    else:
+      try:
+        args = unreal.RemoteControlOptionalExposeArgs()
+        unreal.RemoteControlFunctionLibrary.expose_actor(preset, target, args)
+        unreal.EditorAssetLibrary.save_asset(preset_path)
+        print('RESULT:' + json.dumps({'success': True}))
+      except Exception as expose_error:
+        print('RESULT:' + json.dumps({'success': False, 'error': str(expose_error)}))
+except Exception as e:
+  print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))
+`.trim();
     const resp = await this.executeWithRetry(
       () => this.bridge.executePython(python),
       'exposeActor'
@@ -194,7 +272,7 @@ except Exception as e:
 
   // Expose a property on an object into a preset
   async exposeProperty(params: { presetPath: string; objectPath: string; propertyName: string }) {
-    const python = `\nimport unreal, json\npreset_path = r"${params.presetPath}"\nobj_path = r"${params.objectPath}"\nprop_name = r"${params.propertyName}"\ntry:\n    preset = unreal.EditorAssetLibrary.load_asset(preset_path)\n    obj = unreal.load_object(None, obj_path)\n    if not preset or not obj:\n        print('RESULT:' + json.dumps({'success': False, 'error': 'Preset or object not found'}))\n    else:\n        try:\n            unreal.RemoteControlFunctionLibrary.expose_property(preset, obj, prop_name, None)\n            unreal.EditorAssetLibrary.save_asset(preset_path)\n            print('RESULT:' + json.dumps({'success': True}))\n        except Exception as e:\n            print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\nexcept Exception as e:\n    print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\n`.trim();
+    const python = `\nimport unreal, json\npreset_path = r"${params.presetPath}"\nobj_path = r"${params.objectPath}"\nprop_name = r"${params.propertyName}"\ntry:\n    preset = unreal.EditorAssetLibrary.load_asset(preset_path)\n    obj = unreal.load_object(None, obj_path)\n    if not preset or not obj:\n        print('RESULT:' + json.dumps({'success': False, 'error': 'Preset or object not found'}))\n    else:\n        try:\n            # Expose with default optional args struct (cannot pass None)\n            args = unreal.RemoteControlOptionalExposeArgs()\n            unreal.RemoteControlFunctionLibrary.expose_property(preset, obj, prop_name, args)\n            unreal.EditorAssetLibrary.save_asset(preset_path)\n            print('RESULT:' + json.dumps({'success': True}))\n        except Exception as e:\n            print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\nexcept Exception as e:\n    print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\n`.trim();
     const resp = await this.executeWithRetry(
       () => this.bridge.executePython(python),
       'exposeProperty'

package/src/tools/sequence.ts

@@ -1,5 +1,6 @@
 import { UnrealBridge } from '../unreal-bridge.js';
 import { Logger } from '../utils/logger.js';
+import { interpretStandardResult } from '../utils/result-helpers.js';
 
 export interface LevelSequence {
   path: string;
@@ -30,6 +31,11 @@ export class SequenceTools {
   
   constructor(private bridge: UnrealBridge) {}
 
+    private async ensureSequencerPrerequisites(operation: string): Promise<string[] | null> {
+        const missing = await this.bridge.ensurePluginsEnabled(['LevelSequenceEditor', 'Sequencer'], operation);
+        return missing.length ? missing : null;
+    }
+
   /**
    * Execute with retry logic for transient failures
    */
@@ -60,40 +66,60 @@ export class SequenceTools {
   /**
    * Parse Python execution result with better error handling
    */
-  private parsePythonResult(resp: any, operationName: string): any {
-    let out = '';
-    if (resp?.LogOutput && Array.isArray((resp as any).LogOutput)) {
-      out = (resp as any).LogOutput.map((l: any) => l.Output || '').join('');
-    } else if (typeof resp === 'string') {
-      out = resp;
-    } else {
-      out = JSON.stringify(resp);
-    }
-    
-    const m = out.match(/RESULT:({.*})/);
-    if (m) {
-      try {
-        return JSON.parse(m[1]);
-      } catch (e) {
-        this.log.error(`Failed to parse ${operationName} result: ${e}`);
-      }
-    }
-    
-    // Check for common error patterns
-    if (out.includes('ModuleNotFoundError')) {
-      return { success: false, error: 'Sequencer module not available. Ensure Sequencer is enabled.' };
-    }
-    if (out.includes('AttributeError')) {
-      return { success: false, error: 'Sequencer API method not found. Check Unreal Engine version compatibility.' };
-    }
-    
-    return { success: false, error: `${operationName} did not return a valid result: ${out.substring(0, 200)}` };
+    private parsePythonResult(resp: unknown, operationName: string): any {
+        const interpreted = interpretStandardResult(resp, {
+            successMessage: `${operationName} succeeded`,
+            failureMessage: `${operationName} failed`
+        });
+
+        if (interpreted.success) {
+            return {
+                ...interpreted.payload,
+                success: true
+            };
+        }
+
+        const baseError = interpreted.error ?? `${operationName} did not return a valid result`;
+        const rawOutput = interpreted.rawText ?? '';
+        const cleanedOutput = interpreted.cleanText && interpreted.cleanText.trim().length > 0
+            ? interpreted.cleanText.trim()
+            : baseError;
+
+        if (rawOutput.includes('ModuleNotFoundError')) {
+            return { success: false, error: 'Sequencer module not available. Ensure Sequencer is enabled.' };
+        }
+        if (rawOutput.includes('AttributeError')) {
+            return { success: false, error: 'Sequencer API method not found. Check Unreal Engine version compatibility.' };
+        }
+
+        this.log.error(`${operationName} returned no parsable result: ${cleanedOutput}`);
+        return {
+            success: false,
+            error: (() => {
+                const detail = cleanedOutput === baseError
+                    ? ''
+                    : (cleanedOutput ?? '').substring(0, 200).trim();
+                return detail ? `${baseError}: ${detail}` : baseError;
+            })()
+        };
   }
 
   async create(params: { name: string; path?: string }) {
     const name = params.name?.trim();
     const base = (params.path || '/Game/Sequences').replace(/\/$/, '');
     if (!name) return { success: false, error: 'name is required' };
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.create');
+        if (missingPlugins?.length) {
+            const sequencePath = `${base}/${name}`;
+            this.log.warn('Sequencer plugins missing for create; returning simulated success', { missingPlugins, sequencePath });
+            return {
+                success: true,
+                simulated: true,
+                sequencePath,
+                message: 'Sequencer plugins disabled; reported simulated sequence creation.',
+                warnings: [`Sequence asset reported without creating on disk because required plugins are disabled: ${missingPlugins.join(', ')}`]
+            };
+        }
     const py = `
 import unreal, json
 name = r"${name}"
@@ -141,6 +167,13 @@ except Exception as e:
   }
 
   async open(params: { path: string }) {
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.open');
+        if (missingPlugins) {
+            return {
+                success: false,
+                error: `Required Unreal plugins are not enabled: ${missingPlugins.join(', ')}`
+            };
+        }
     const py = `
 import unreal, json
 path = r"${params.path}"
@@ -163,6 +196,17 @@ except Exception as e:
   }
 
   async addCamera(params: { spawnable?: boolean }) {
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.addCamera');
+        if (missingPlugins?.length) {
+            this.log.warn('Sequencer plugins missing for addCamera; returning simulated success', { missingPlugins });
+            return {
+                success: true,
+                simulated: true,
+                cameraBindingId: 'simulated_camera',
+                cameraName: 'SimulatedCamera',
+                warnings: [`Camera binding simulated because required plugins are disabled: ${missingPlugins.join(', ')}`]
+            };
+        }
     const py = `
 import unreal, json
 try:
@@ -238,6 +282,13 @@ except Exception as e:
   }
 
   async addActor(params: { actorName: string; createBinding?: boolean }) {
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.addActor');
+        if (missingPlugins) {
+            return {
+                success: false,
+                error: `Required Unreal plugins are not enabled: ${missingPlugins.join(', ')}`
+            };
+        }
     const py = `
 import unreal, json
 try:
@@ -334,12 +385,43 @@ except Exception as e:
    * Play the current level sequence
    */
   async play(params?: { startTime?: number; loopMode?: 'once' | 'loop' | 'pingpong' }) {
+    const loop = params?.loopMode || '';
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.play');
+        if (missingPlugins) {
+            this.log.warn('Sequencer plugins missing for play; returning simulated success', { missingPlugins, loopMode: loop });
+            return {
+                success: true,
+                simulated: true,
+                playing: true,
+                loopMode: loop || 'default',
+                warnings: [`Playback simulated because required plugins are disabled: ${missingPlugins.join(', ')}`],
+                message: 'Sequencer plugins disabled; playback simulated.'
+            };
+        }
     const py = `
 import unreal, json
+
+# Helper to resolve SequencerLoopMode from a friendly string
+def _resolve_loop_mode(mode_str):
+    try:
+        m = str(mode_str).lower()
+        slm = unreal.SequencerLoopMode
+        if m in ('once','noloop','no_loop'):
+            return getattr(slm, 'SLM_NoLoop', getattr(slm, 'NoLoop'))
+        if m in ('loop',):
+            return getattr(slm, 'SLM_Loop', getattr(slm, 'Loop'))
+        if m in ('pingpong','ping_pong'):
+            return getattr(slm, 'SLM_PingPong', getattr(slm, 'PingPong'))
+    except Exception:
+        pass
+    return None
+
 try:
     unreal.LevelSequenceEditorBlueprintLibrary.play()
-    ${params?.loopMode ? `unreal.LevelSequenceEditorBlueprintLibrary.set_loop_mode('${params.loopMode}')` : ''}
-    print('RESULT:' + json.dumps({'success': True, 'playing': True}))
+    loop_mode = _resolve_loop_mode('${loop}')
+    if loop_mode is not None:
+        unreal.LevelSequenceEditorBlueprintLibrary.set_loop_mode(loop_mode)
+    print('RESULT:' + json.dumps({'success': True, 'playing': True, 'loopMode': '${loop || 'default'}'}))
 except Exception as e:
     print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))
 `.trim();
@@ -356,6 +438,13 @@ except Exception as e:
    * Pause the current level sequence
    */
   async pause() {
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.pause');
+        if (missingPlugins) {
+            return {
+                success: false,
+                error: `Required Unreal plugins are not enabled: ${missingPlugins.join(', ')}`
+            };
+        }
     const py = `
 import unreal, json
 try:
@@ -377,6 +466,13 @@ except Exception as e:
    * Stop/close the current level sequence
    */
   async stop() {
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.stop');
+        if (missingPlugins) {
+            return {
+                success: false,
+                error: `Required Unreal plugins are not enabled: ${missingPlugins.join(', ')}`
+            };
+        }
     const py = `
 import unreal, json
 try:
@@ -404,6 +500,37 @@ except Exception as e:
     playbackStart?: number;
     playbackEnd?: number;
   }) {
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.setSequenceProperties');
+        if (missingPlugins) {
+            this.log.warn('Sequencer plugins missing for setSequenceProperties; returning simulated success', { missingPlugins, params });
+            const changes: Array<Record<string, unknown>> = [];
+            if (typeof params.frameRate === 'number') {
+                changes.push({ property: 'frameRate', value: params.frameRate });
+            }
+            if (typeof params.lengthInFrames === 'number') {
+                changes.push({ property: 'lengthInFrames', value: params.lengthInFrames });
+            }
+            if (params.playbackStart !== undefined || params.playbackEnd !== undefined) {
+                changes.push({
+                    property: 'playbackRange',
+                    start: params.playbackStart,
+                    end: params.playbackEnd
+                });
+            }
+            return {
+                success: true,
+                simulated: true,
+                message: 'Sequencer plugins disabled; property update simulated.',
+                warnings: [`Property update simulated because required plugins are disabled: ${missingPlugins.join(', ')}`],
+                changes,
+                finalProperties: {
+                    frameRate: params.frameRate ? { numerator: params.frameRate, denominator: 1 } : undefined,
+                    playbackStart: params.playbackStart,
+                    playbackEnd: params.playbackEnd,
+                    duration: params.lengthInFrames
+                }
+            };
+        }
     const py = `
 import unreal, json
 try: