unreal-engine-mcp-server 0.3.1 → 0.4.3

package/dist/tools/materials.js

@@ -1,3 +1,5 @@
+import { coerceBoolean, interpretStandardResult } from '../utils/result-helpers.js';
+import { escapePythonString } from '../utils/python.js';
 export class MaterialTools {
     bridge;
     constructor(bridge) {
@@ -5,125 +7,131 @@ export class MaterialTools {
     }
     async createMaterial(name, path) {
         try {
-            // Validate name
             if (!name || name.trim() === '') {
                 return { success: false, error: 'Material name cannot be empty' };
             }
-            // Check name length (Unreal has 260 char path limit)
             if (name.length > 100) {
                 return { success: false, error: `Material name too long (${name.length} chars). Maximum is 100 characters.` };
             }
-            // Validate name doesn't contain invalid characters
-            // Unreal Engine doesn't allow: spaces, dots, slashes, backslashes, pipes, angle brackets, 
-            // curly braces, square brackets, parentheses, @, #, etc.
             const invalidChars = /[\s./<>|{}[\]()@#\\]/;
             if (invalidChars.test(name)) {
                 const foundChars = name.match(invalidChars);
                 return { success: false, error: `Material name contains invalid characters: '${foundChars?.[0]}'. Avoid spaces, dots, slashes, backslashes, brackets, and special symbols.` };
             }
-            // Validate path type
             if (typeof path !== 'string') {
                 return { success: false, error: `Invalid path type: expected string, got ${typeof path}` };
             }
-            // Clean up path - remove trailing slashes
-            const cleanPath = path.replace(/\/$/, '');
-            // Validate path starts with /Game or /Engine
+            const trimmedPath = path.trim();
+            const effectivePath = trimmedPath.length === 0 ? '/Game' : trimmedPath;
+            const cleanPath = effectivePath.replace(/\/$/, '');
             if (!cleanPath.startsWith('/Game') && !cleanPath.startsWith('/Engine')) {
                 return { success: false, error: `Invalid path: must start with /Game or /Engine, got ${cleanPath}` };
             }
-            // Use Python API to create material
+            const normalizedPath = cleanPath.toLowerCase();
+            const restrictedPrefixes = ['/engine/restricted', '/engine/generated', '/engine/transient'];
+            if (restrictedPrefixes.some(prefix => normalizedPath.startsWith(prefix))) {
+                const errorMessage = `Destination path is read-only and cannot be used for material creation: ${cleanPath}`;
+                return { success: false, error: errorMessage, message: errorMessage };
+            }
             const materialPath = `${cleanPath}/${name}`;
-            // Use the correct Unreal Engine 5 Python API
+            const payload = { name, cleanPath, materialPath };
+            const escapedName = escapePythonString(name);
             const pythonCode = `
-import unreal
-import json
+import unreal, json
+
+payload = json.loads(r'''${JSON.stringify(payload)}''')
+result = {
+    'success': False,
+    'message': '',
+    'error': '',
+    'warnings': [],
+    'details': [],
+    'name': payload.get('name') or "${escapedName}",
+    'path': payload.get('materialPath')
+}
+
+material_path = result['path']
+clean_path = payload.get('cleanPath') or '/Game'
 
 try:
-    # Check if material already exists
-    material_path = '${materialPath}'
     if unreal.EditorAssetLibrary.does_asset_exist(material_path):
-        print(json.dumps({"success": True, "exists": True, "path": material_path}))
+        result['success'] = True
+        result['exists'] = True
+        result['message'] = f"Material already exists at {material_path}"
     else:
-        # Get the AssetTools
         asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
-        
-        # Create a MaterialFactoryNew
         factory = unreal.MaterialFactoryNew()
-        
-        # Clean up the path - remove trailing slashes
-        clean_path = '${cleanPath}'.rstrip('/')
-        
-        # Create the material asset at the specified path
-        # The path should be: /Game/FolderName and asset name separately
         asset = asset_tools.create_asset(
-            asset_name='${name}',
+            asset_name=payload.get('name'),
             package_path=clean_path,
             asset_class=unreal.Material,
             factory=factory
         )
-        
         if asset:
-            # Save the package
             unreal.EditorAssetLibrary.save_asset(material_path)
-            print(json.dumps({"success": True, "created": True, "path": material_path}))
+            result['success'] = True
+            result['created'] = True
+            result['message'] = f"Material created at {material_path}"
         else:
-            print(json.dumps({"success": False, "error": "Failed to create material"}))
-except Exception as e:
-    print(json.dumps({"success": False, "error": str(e)}))
+            result['error'] = 'Failed to create material'
+            result['message'] = result['error']
+except Exception as exc:
+    result['error'] = str(exc)
+    if not result['message']:
+        result['message'] = result['error']
+
+print('RESULT:' + json.dumps(result))
 `.trim();
             const pyResult = await this.bridge.executePython(pythonCode);
-            // Parse the Python response
-            let responseStr = '';
-            if (pyResult?.LogOutput && Array.isArray(pyResult.LogOutput)) {
-                responseStr = pyResult.LogOutput.map((log) => log.Output || '').join('');
-            }
-            else if (typeof pyResult === 'string') {
-                responseStr = pyResult;
-            }
-            else {
-                responseStr = JSON.stringify(pyResult);
-            }
-            // Try to extract JSON response
-            try {
-                // Look for JSON in the output
-                const jsonMatch = responseStr.match(/\{.*\}/s);
-                if (jsonMatch) {
-                    const result = JSON.parse(jsonMatch[0]);
-                    if (result.success) {
-                        if (result.exists) {
-                            return { success: true, path: materialPath, message: `Material ${name} already exists at ${path}` };
-                        }
-                        else if (result.created) {
-                            return { success: true, path: materialPath, message: `Material ${name} created at ${path}` };
-                        }
-                    }
-                    else {
-                        return { success: false, error: result.error || 'Failed to create material' };
-                    }
+            const interpreted = interpretStandardResult(pyResult, {
+                successMessage: `Material ${name} processed`,
+                failureMessage: 'Failed to create material'
+            });
+            if (interpreted.success) {
+                const exists = coerceBoolean(interpreted.payload.exists, false) === true;
+                const created = coerceBoolean(interpreted.payload.created, false) === true;
+                if (exists) {
+                    return { success: true, path: materialPath, message: `Material ${name} already exists at ${materialPath}` };
                 }
+                if (created) {
+                    return { success: true, path: materialPath, message: `Material ${name} created at ${materialPath}` };
+                }
+                return { success: true, path: materialPath, message: interpreted.message };
             }
-            catch {
-                // JSON parsing failed, fall back to verification
-            }
-            // Fallback: Verify creation using EditorAssetLibrary
-            let verify = {};
-            try {
-                verify = await this.bridge.call({
-                    objectPath: '/Script/EditorScriptingUtilities.Default__EditorAssetLibrary',
-                    functionName: 'DoesAssetExist',
-                    parameters: {
-                        AssetPath: materialPath
-                    }
-                });
+            if (interpreted.error) {
+                const exists = await this.assetExists(materialPath);
+                if (exists) {
+                    return {
+                        success: true,
+                        path: materialPath,
+                        message: `Material ${name} created at ${materialPath}`,
+                        warnings: interpreted.warnings,
+                        details: interpreted.details
+                    };
+                }
+                return {
+                    success: false,
+                    error: interpreted.error,
+                    warnings: interpreted.warnings,
+                    details: interpreted.details
+                };
             }
-            catch { }
-            const exists = verify?.ReturnValue === true || verify?.Result === true;
+            const exists = await this.assetExists(materialPath);
             if (exists) {
-                return { success: true, path: materialPath, message: `Material ${name} created at ${path}` };
-            }
-            else {
-                return { success: false, error: 'Material creation may have failed. Check Output Log for details.', debug: responseStr };
+                return {
+                    success: true,
+                    path: materialPath,
+                    message: `Material ${name} created at ${materialPath}`,
+                    warnings: interpreted.warnings,
+                    details: interpreted.details
+                };
             }
+            return {
+                success: false,
+                error: interpreted.message,
+                warnings: interpreted.warnings,
+                details: interpreted.details
+            };
         }
         catch (err) {
             return { success: false, error: `Failed to create material: ${err}` };
@@ -142,5 +150,20 @@ except Exception as e:
             return { success: false, error: `Failed to apply material: ${err}` };
         }
     }
+    async assetExists(assetPath) {
+        try {
+            const response = await this.bridge.call({
+                objectPath: '/Script/EditorScriptingUtilities.Default__EditorAssetLibrary',
+                functionName: 'DoesAssetExist',
+                parameters: {
+                    AssetPath: assetPath
+                }
+            });
+            return coerceBoolean(response?.ReturnValue ?? response?.Result ?? response, false) === true;
+        }
+        catch {
+            return false;
+        }
+    }
 }
 //# sourceMappingURL=materials.js.map

package/dist/tools/niagara.d.ts

@@ -18,14 +18,14 @@ export declare class NiagaraTools {
         }>;
     }): Promise<{
         success: boolean;
-        path: any;
-        message: string;
-        error?: undefined;
-    } | {
-        success: boolean;
-        error: any;
+        error: string;
         path?: undefined;
         message?: undefined;
+    } | {
+        success: boolean;
+        path: string;
+        message: string;
+        error?: undefined;
     }>;
     /**
      * Add Emitter to System (left as-is; console commands may be placeholders)
@@ -86,7 +86,7 @@ export declare class NiagaraTools {
         };
     }): Promise<{
         success: boolean;
-        error: any;
+        error: string;
         message?: undefined;
         path?: undefined;
     } | {
@@ -132,14 +132,12 @@ export declare class NiagaraTools {
         autoDestroy?: boolean;
         attachToActor?: string;
     }): Promise<{
-        success: boolean;
+        success: true;
         message: string;
-        error?: undefined;
+        actor?: string;
     } | {
         success: boolean;
-        error: any;
-        message?: undefined;
+        error: string;
     }>;
-    private _executeCommand;
 }
 //# sourceMappingURL=niagara.d.ts.map

package/dist/tools/niagara.js

@@ -1,4 +1,5 @@
 import { sanitizeAssetName, validateAssetParams } from '../utils/validation.js';
+import { interpretStandardResult, coerceString } from '../utils/result-helpers.js';
 export class NiagaraTools {
     bridge;
     constructor(bridge) {
@@ -10,57 +11,48 @@ export class NiagaraTools {
     async createSystem(params) {
         try {
             const path = params.savePath || '/Game/Effects/Niagara';
-            // const fullPath = `${path}/${params.name}`; // Currently unused
             const python = `
 import unreal
+import json
+
 path = r"${path}"
 name = r"${params.name}"
 full_path = f"{path}/{name}"
-# If already exists, just report success
+
 if unreal.EditorAssetLibrary.does_asset_exist(full_path):
-    print("RESULT:{'success': True, 'path': '" + full_path + "', 'existing': True}")
+    print('RESULT:' + json.dumps({'success': True, 'path': full_path, 'existing': True}))
 else:
     asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
     factory = None
     try:
         factory = unreal.NiagaraSystemFactoryNew()
-    except Exception as e:
+    except Exception:
         factory = None
+
     if factory is None:
-        print("RESULT:{'success': False, 'error': 'NiagaraSystemFactoryNew unavailable'}")
+        print('RESULT:' + json.dumps({'success': False, 'error': 'NiagaraSystemFactoryNew unavailable'}))
     else:
         asset = asset_tools.create_asset(asset_name=name, package_path=path, asset_class=unreal.NiagaraSystem, factory=factory)
         if asset:
             unreal.EditorAssetLibrary.save_asset(full_path)
-            print("RESULT:{'success': True, 'path': '" + full_path + "'}")
+            print('RESULT:' + json.dumps({'success': True, 'path': full_path}))
         else:
-            print("RESULT:{'success': False, 'error': 'AssetTools create_asset failed'}")
+            print('RESULT:' + json.dumps({'success': False, 'error': 'AssetTools create_asset failed'}))
 `.trim();
             const resp = await this.bridge.executePython(python);
-            let output = '';
-            if (resp?.LogOutput && Array.isArray(resp.LogOutput)) {
-                output = resp.LogOutput.map((l) => l.Output || '').join('');
+            const interpreted = interpretStandardResult(resp, {
+                successMessage: `Niagara system ${params.name} created`,
+                failureMessage: `Failed to create Niagara system ${params.name}`
+            });
+            if (!interpreted.success) {
+                return { success: false, error: interpreted.error ?? interpreted.message };
             }
-            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].replace(/'/g, '"'));
-                    if (parsed.success) {
-                        return { success: true, path: parsed.path, message: `Niagara system ${params.name} created` };
-                    }
-                    return { success: false, error: parsed.error || 'Unknown error creating Niagara system' };
-                }
-                catch {
-                    // fallthrough
-                }
-            }
-            return { success: false, error: 'No RESULT from Python when creating Niagara system' };
+            const pathFromPayload = coerceString(interpreted.payload.path) ?? `${path}/${params.name}`;
+            return {
+                success: true,
+                path: pathFromPayload,
+                message: interpreted.message
+            };
         }
         catch (err) {
             return { success: false, error: `Failed to create Niagara system: ${err}` };
@@ -101,9 +93,7 @@ else:
                     commands.push(`SetEmitterMesh ${params.systemName} ${params.emitterName} ${props.mesh}`);
                 }
             }
-            for (const cmd of commands) {
-                await this.bridge.executeConsoleCommand(cmd);
-            }
+            await this.bridge.executeConsoleCommands(commands);
             return { success: true, message: `Emitter ${params.emitterName} added to ${params.systemName}` };
         }
         catch (err) {
@@ -167,26 +157,22 @@ else:
             // Verify existence via Python to avoid RC EditorAssetLibrary issues
             const verifyPy = `
 import unreal
+import json
+
 p = r"${fullPath}"
-print("RESULT:{'success': True, 'exists': %s}" % ('True' if unreal.EditorAssetLibrary.does_asset_exist(p) else 'False'))
+exists = bool(unreal.EditorAssetLibrary.does_asset_exist(p))
+print('RESULT:' + json.dumps({'success': True, 'exists': exists}))
 `.trim();
             const verifyResp = await this.bridge.executePython(verifyPy);
-            let vout = '';
-            if (verifyResp?.LogOutput && Array.isArray(verifyResp.LogOutput))
-                vout = verifyResp.LogOutput.map((l) => l.Output || '').join('');
-            else if (typeof verifyResp === 'string')
-                vout = verifyResp;
-            else
-                vout = JSON.stringify(verifyResp);
-            const m = vout.match(/RESULT:({.*})/);
-            if (m) {
-                try {
-                    const parsed = JSON.parse(m[1].replace(/'/g, '"'));
-                    if (!parsed.exists) {
-                        return { success: false, error: `Asset not found after creation: ${fullPath}` };
-                    }
-                }
-                catch { }
+            const verifyResult = interpretStandardResult(verifyResp, {
+                successMessage: 'Niagara asset verification complete',
+                failureMessage: `Failed to verify Niagara asset at ${fullPath}`
+            });
+            if (!verifyResult.success) {
+                return { success: false, error: verifyResult.error ?? verifyResult.message };
+            }
+            if (verifyResult.payload.exists === false) {
+                return { success: false, error: `Asset not found after creation: ${fullPath}` };
             }
             return { success: true, message: `${params.effectType} effect ${safeName} created`, path: fullPath };
         }
@@ -211,8 +197,7 @@ print("RESULT:{'success': True, 'exists': %s}" % ('True' if unreal.EditorAssetLi
                 if (s.iterations !== undefined)
                     commands.push(`SetGPUIterations ${params.name} ${s.iterations}`);
             }
-            for (const cmd of commands)
-                await this.bridge.executeConsoleCommand(cmd);
+            await this.bridge.executeConsoleCommands(commands);
             return { success: true, message: `GPU simulation ${params.name} created`, path: `${path}/${params.name}` };
         }
         catch (err) {
@@ -229,61 +214,56 @@ print("RESULT:{'success': True, 'exists': %s}" % ('True' if unreal.EditorAssetLi
             const scl = Array.isArray(params.scale) ? params.scale : (typeof params.scale === 'number' ? [params.scale, params.scale, params.scale] : [1, 1, 1]);
             const py = `
 import unreal
+import json
+
 loc = unreal.Vector(${loc.x || 0}, ${loc.y || 0}, ${loc.z || 0})
 rot = unreal.Rotator(${rot[0]}, ${rot[1]}, ${rot[2]})
 scale = unreal.Vector(${scl[0]}, ${scl[1]}, ${scl[2]})
 sys_path = r"${params.systemPath}"
+
 if unreal.EditorAssetLibrary.does_asset_exist(sys_path):
-    sys = unreal.EditorAssetLibrary.load_asset(sys_path)
-    actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-    actor = actor_subsystem.spawn_actor_from_class(unreal.NiagaraActor, loc, rot)
-    if actor:
-        comp = actor.get_niagara_component()
-        try:
-            comp.set_asset(sys)
-        except Exception:
-            try:
-                comp.set_editor_property('asset', sys)
-            except Exception:
-                pass
-        comp.set_world_scale3d(scale)
-        comp.activate(True)
-        actor.set_actor_label(f"Niagara_{unreal.SystemLibrary.get_game_time_in_seconds(actor.get_world()):.0f}")
-        print("RESULT:{'success': True, 'actor': '" + actor.get_actor_label() + "'}")
-    else:
-        print("RESULT:{'success': False, 'error': 'Failed to spawn NiagaraActor'}")
+  sys = unreal.EditorAssetLibrary.load_asset(sys_path)
+  actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+  actor = actor_subsystem.spawn_actor_from_class(unreal.NiagaraActor, loc, rot)
+  if actor:
+    comp = actor.get_niagara_component()
+    try:
+      comp.set_asset(sys)
+    except Exception:
+      try:
+        comp.set_editor_property('asset', sys)
+      except Exception:
+        pass
+    comp.set_world_scale3d(scale)
+    comp.activate(True)
+    actor.set_actor_label(f"Niagara_{unreal.SystemLibrary.get_game_time_in_seconds(actor.get_world()):.0f}")
+    print('RESULT:' + json.dumps({'success': True, 'actor': actor.get_actor_label()}))
+  else:
+    print('RESULT:' + json.dumps({'success': False, 'error': 'Failed to spawn NiagaraActor'}))
 else:
-    print("RESULT:{'success': False, 'error': 'System asset not found'}")
+  print('RESULT:' + json.dumps({'success': False, 'error': 'System asset not found'}))
 `.trim();
             const resp = await this.bridge.executePython(py);
-            let output = '';
-            if (resp?.LogOutput && 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].replace(/'/g, '"'));
-                    return parsed.success ? { success: true, message: 'Niagara effect spawned' } : { success: false, error: parsed.error || 'Spawn failed' };
-                }
-                catch { }
+            const interpreted = interpretStandardResult(resp, {
+                successMessage: 'Niagara effect spawned',
+                failureMessage: 'Failed to spawn Niagara effect'
+            });
+            const actorLabel = coerceString(interpreted.payload.actor);
+            if (!interpreted.success) {
+                return { success: false, error: interpreted.error ?? interpreted.message };
+            }
+            const outcome = {
+                success: true,
+                message: interpreted.message
+            };
+            if (actorLabel) {
+                outcome.actor = actorLabel;
             }
-            return { success: true, message: 'Niagara effect spawn attempted' };
+            return outcome;
         }
         catch (err) {
             return { success: false, error: `Failed to spawn effect: ${err}` };
         }
     }
-    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=niagara.js.map

package/dist/tools/performance.d.ts

@@ -2,7 +2,6 @@ import { UnrealBridge } from '../unreal-bridge.js';
 export declare class PerformanceTools {
     private bridge;
     constructor(bridge: UnrealBridge);
-    private _executeCommand;
     startProfiling(params: {
         type: 'CPU' | 'GPU' | 'Memory' | 'RenderThread' | 'GameThread' | 'All';
         duration?: number;
@@ -38,15 +37,24 @@ export declare class PerformanceTools {
         category: 'ViewDistance' | 'AntiAliasing' | 'PostProcessing' | 'PostProcess' | 'Shadows' | 'GlobalIllumination' | 'Reflections' | 'Textures' | 'Effects' | 'Foliage' | 'Shading';
         level: 0 | 1 | 2 | 3 | 4;
     }): Promise<{
+        success: boolean;
+        error: string;
+        message?: undefined;
+        verified?: undefined;
+        readback?: undefined;
+        method?: undefined;
+    } | {
         success: boolean;
         message: string;
-        verified: any;
-        readback: any;
-        method: any;
+        verified: boolean;
+        readback: number;
+        method: string;
+        error?: undefined;
     } | {
         success: boolean;
         message: string;
         method: string;
+        error?: undefined;
         verified?: undefined;
         readback?: undefined;
     }>;