unreal-engine-mcp-server 0.3.1 → 0.4.3

package/dist/tools/rc.js

@@ -1,4 +1,5 @@
 import { Logger } from '../utils/logger.js';
+import { interpretStandardResult } from '../utils/result-helpers.js';
 export class RcTools {
     bridge;
     log = new Logger('RcTools');
@@ -31,33 +32,38 @@ export class RcTools {
      * Parse Python execution result with better error handling
      */
     parsePythonResult(resp, operationName) {
-        let out = '';
-        if (resp?.LogOutput && Array.isArray(resp.LogOutput)) {
-            out = resp.LogOutput.map((l) => 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}`);
-            }
+        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
     async createPreset(params) {
@@ -65,6 +71,9 @@ export class RcTools {
         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
@@ -142,7 +151,72 @@ except Exception as e:
     }
     // Expose an actor by label/name into a preset
     async exposeActor(params) {
-        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');
         const result = this.parsePythonResult(resp, 'exposeActor');
         // Clear cache for this preset to force refresh
@@ -153,7 +227,7 @@ except Exception as e:
     }
     // Expose a property on an object into a preset
     async exposeProperty(params) {
-        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');
         const result = this.parsePythonResult(resp, 'exposeProperty');
         // Clear cache for this preset to force refresh

package/dist/tools/sequence.d.ts

@@ -24,6 +24,7 @@ export declare class SequenceTools {
     private retryAttempts;
     private retryDelay;
     constructor(bridge: UnrealBridge);
+    private ensureSequencerPrerequisites;
     /**
      * Execute with retry logic for transient failures
      */

package/dist/tools/sequence.js

@@ -1,4 +1,5 @@
 import { Logger } from '../utils/logger.js';
+import { interpretStandardResult } from '../utils/result-helpers.js';
 export class SequenceTools {
     bridge;
     log = new Logger('SequenceTools');
@@ -8,6 +9,10 @@ export class SequenceTools {
     constructor(bridge) {
         this.bridge = bridge;
     }
+    async ensureSequencerPrerequisites(operation) {
+        const missing = await this.bridge.ensurePluginsEnabled(['LevelSequenceEditor', 'Sequencer'], operation);
+        return missing.length ? missing : null;
+    }
     /**
      * Execute with retry logic for transient failures
      */
@@ -31,39 +36,55 @@ export class SequenceTools {
      * Parse Python execution result with better error handling
      */
     parsePythonResult(resp, operationName) {
-        let out = '';
-        if (resp?.LogOutput && Array.isArray(resp.LogOutput)) {
-            out = resp.LogOutput.map((l) => 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}`);
-            }
+        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: 'Sequencer module not available. Ensure Sequencer is enabled.' };
         }
-        if (out.includes('AttributeError')) {
+        if (rawOutput.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)}` };
+        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) {
         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}"
@@ -104,6 +125,13 @@ except Exception as e:
         return result;
     }
     async open(params) {
+        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}"
@@ -121,6 +149,17 @@ except Exception as e:
         return this.parsePythonResult(resp, 'openSequence');
     }
     async addCamera(params) {
+        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:
@@ -191,6 +230,13 @@ except Exception as e:
         return this.parsePythonResult(resp, 'addCamera');
     }
     async addActor(params) {
+        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:
@@ -282,12 +328,43 @@ except Exception as e:
      * Play the current level sequence
      */
     async play(params) {
+        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();
@@ -298,6 +375,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:
@@ -313,6 +397,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:
@@ -328,6 +419,37 @@ except Exception as e:
      * Set sequence properties including frame rate and length
      */
     async setSequenceProperties(params) {
+        const missingPlugins = await this.ensureSequencerPrerequisites('SequenceTools.setSequenceProperties');
+        if (missingPlugins) {
+            this.log.warn('Sequencer plugins missing for setSequenceProperties; returning simulated success', { missingPlugins, params });
+            const changes = [];
+            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:

package/dist/tools/ui.d.ts

@@ -2,7 +2,6 @@ import { UnrealBridge } from '../unreal-bridge.js';
 export declare class UITools {
     private bridge;
     constructor(bridge: UnrealBridge);
-    private _executeCommand;
     createWidget(params: {
         name: string;
         type?: 'HUD' | 'Menu' | 'Inventory' | 'Dialog' | 'Custom';
@@ -11,10 +10,17 @@ export declare class UITools {
         success: boolean;
         message: string;
         error?: undefined;
+        details?: undefined;
     } | {
         success: boolean;
-        error: any;
+        error: string;
+        details: string | undefined;
         message?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        message?: undefined;
+        details?: undefined;
     }>;
     addWidgetComponent(params: {
         widgetName: string;
@@ -66,7 +72,21 @@ export declare class UITools {
         widgetName: string;
         visible: boolean;
         playerIndex?: number;
-    }): Promise<any>;
+    }): Promise<{
+        success: boolean;
+        error: string;
+        message?: undefined;
+        command?: undefined;
+        output?: undefined;
+        logLines?: undefined;
+    } | {
+        success: boolean;
+        message: string;
+        command: string;
+        output: string | undefined;
+        logLines: any[] | undefined;
+        error?: undefined;
+    }>;
     addWidgetToViewport(params: {
         widgetClass: string;
         zOrder?: number;
@@ -75,10 +95,17 @@ export declare class UITools {
         success: boolean;
         message: string;
         error?: undefined;
+        details?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        details: string | undefined;
+        message?: undefined;
     } | {
         success: boolean;
-        error: any;
+        error: string;
         message?: undefined;
+        details?: undefined;
     }>;
     removeWidgetFromViewport(params: {
         widgetName: string;