unreal-engine-mcp-server 0.2.1

package/dist/tools/materials.d.ts

@@ -0,0 +1,34 @@
+import { UnrealBridge } from '../unreal-bridge.js';
+export declare class MaterialTools {
+    private bridge;
+    constructor(bridge: UnrealBridge);
+    createMaterial(name: string, path: string): Promise<{
+        success: boolean;
+        path: string;
+        message: string;
+        error?: undefined;
+        debug?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        path?: undefined;
+        message?: undefined;
+        debug?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        debug: string;
+        path?: undefined;
+        message?: undefined;
+    }>;
+    applyMaterialToActor(actorPath: string, materialPath: string, slotIndex?: number): Promise<{
+        success: boolean;
+        message: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        message?: undefined;
+    }>;
+}
+//# sourceMappingURL=materials.d.ts.map

package/dist/tools/materials.js

@@ -0,0 +1,146 @@
+export class MaterialTools {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    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
+            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 materialPath = `${cleanPath}/${name}`;
+            // Use the correct Unreal Engine 5 Python API
+            const pythonCode = `
+import unreal
+import json
+
+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}))
+    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}',
+            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}))
+        else:
+            print(json.dumps({"success": False, "error": "Failed to create material"}))
+except Exception as e:
+    print(json.dumps({"success": False, "error": str(e)}))
+`.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' };
+                    }
+                }
+            }
+            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
+                    }
+                });
+            }
+            catch { }
+            const exists = verify?.ReturnValue === true || verify?.Result === true;
+            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 };
+            }
+        }
+        catch (err) {
+            return { success: false, error: `Failed to create material: ${err}` };
+        }
+    }
+    async applyMaterialToActor(actorPath, materialPath, slotIndex = 0) {
+        try {
+            await this.bridge.httpCall('/remote/object/property', 'PUT', {
+                objectPath: actorPath,
+                propertyName: `StaticMeshComponent.Materials[${slotIndex}]`,
+                propertyValue: materialPath
+            });
+            return { success: true, message: 'Material applied' };
+        }
+        catch (err) {
+            return { success: false, error: `Failed to apply material: ${err}` };
+        }
+    }
+}
+//# sourceMappingURL=materials.js.map

package/dist/tools/niagara.d.ts

@@ -0,0 +1,145 @@
+import { UnrealBridge } from '../unreal-bridge.js';
+export declare class NiagaraTools {
+    private bridge;
+    constructor(bridge: UnrealBridge);
+    /**
+     * Create Niagara System (real asset via Python)
+     */
+    createSystem(params: {
+        name: string;
+        savePath?: string;
+        template?: 'Empty' | 'Fountain' | 'Ambient' | 'Projectile' | 'Custom';
+        emitters?: Array<{
+            name: string;
+            spawnRate?: number;
+            lifetime?: number;
+            shape?: 'Point' | 'Sphere' | 'Box' | 'Cylinder' | 'Cone';
+            shapeSize?: [number, number, number];
+        }>;
+    }): Promise<{
+        success: boolean;
+        path: any;
+        message: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        path?: undefined;
+        message?: undefined;
+    }>;
+    /**
+     * Add Emitter to System (left as-is; console commands may be placeholders)
+     */
+    addEmitter(params: {
+        systemName: string;
+        emitterName: string;
+        emitterType: 'Sprite' | 'Mesh' | 'Ribbon' | 'Beam' | 'GPU';
+        properties?: {
+            spawnRate?: number;
+            lifetime?: number;
+            velocityMin?: [number, number, number];
+            velocityMax?: [number, number, number];
+            size?: number;
+            color?: [number, number, number, number];
+            material?: string;
+            mesh?: string;
+        };
+    }): Promise<{
+        success: boolean;
+        message: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        message?: undefined;
+    }>;
+    setParameter(params: {
+        systemName: string;
+        parameterName: string;
+        parameterType: 'Float' | 'Vector' | 'Color' | 'Bool' | 'Int';
+        value: any;
+        isUserParameter?: boolean;
+    }): Promise<{
+        success: boolean;
+        message: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        message?: undefined;
+    }>;
+    /**
+     * Create Preset Effect (now creates a real Niagara system asset)
+     */
+    createEffect(params: {
+        effectType: 'Fire' | 'Smoke' | 'Explosion' | 'Water' | 'Rain' | 'Snow' | 'Magic' | 'Lightning' | 'Dust' | 'Steam';
+        name: string;
+        location: [number, number, number] | {
+            x: number;
+            y: number;
+            z: number;
+        };
+        scale?: number;
+        intensity?: number;
+        customParameters?: {
+            [key: string]: any;
+        };
+    }): Promise<{
+        success: boolean;
+        error: any;
+        message?: undefined;
+        path?: undefined;
+    } | {
+        success: boolean;
+        message: string;
+        path: string;
+        error?: undefined;
+    }>;
+    createGPUSimulation(params: {
+        name: string;
+        simulationType: 'Fluid' | 'Hair' | 'Cloth' | 'Debris' | 'Crowd';
+        particleCount: number;
+        savePath?: string;
+        gpuSettings?: {
+            computeShader?: string;
+            textureFormat?: 'RGBA8' | 'RGBA16F' | 'RGBA32F';
+            gridResolution?: [number, number, number];
+            iterations?: number;
+        };
+    }): Promise<{
+        success: boolean;
+        message: string;
+        path: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        message?: undefined;
+        path?: undefined;
+    }>;
+    /**
+     * Spawn Niagara Effect in Level using Python (NiagaraActor)
+     */
+    spawnEffect(params: {
+        systemPath: string;
+        location: [number, number, number] | {
+            x: number;
+            y: number;
+            z: number;
+        };
+        rotation?: [number, number, number];
+        scale?: [number, number, number] | number;
+        autoDestroy?: boolean;
+        attachToActor?: string;
+    }): Promise<{
+        success: boolean;
+        message: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        message?: undefined;
+    }>;
+    private _executeCommand;
+}
+//# sourceMappingURL=niagara.d.ts.map

package/dist/tools/niagara.js

@@ -0,0 +1,289 @@
+import { sanitizeAssetName, validateAssetParams } from '../utils/validation.js';
+export class NiagaraTools {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    /**
+     * Create Niagara System (real asset via Python)
+     */
+    async createSystem(params) {
+        try {
+            const path = params.savePath || '/Game/Effects/Niagara';
+            // const fullPath = `${path}/${params.name}`; // Currently unused
+            const python = `
+import unreal
+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}")
+else:
+    asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
+    factory = None
+    try:
+        factory = unreal.NiagaraSystemFactoryNew()
+    except Exception as e:
+        factory = None
+    if factory is None:
+        print("RESULT:{'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 + "'}")
+        else:
+            print("RESULT:{'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('');
+            }
+            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' };
+        }
+        catch (err) {
+            return { success: false, error: `Failed to create Niagara system: ${err}` };
+        }
+    }
+    /**
+     * Add Emitter to System (left as-is; console commands may be placeholders)
+     */
+    async addEmitter(params) {
+        try {
+            const commands = [
+                `AddNiagaraEmitter ${params.systemName} ${params.emitterName} ${params.emitterType}`
+            ];
+            if (params.properties) {
+                const props = params.properties;
+                if (props.spawnRate !== undefined) {
+                    commands.push(`SetEmitterSpawnRate ${params.systemName} ${params.emitterName} ${props.spawnRate}`);
+                }
+                if (props.lifetime !== undefined) {
+                    commands.push(`SetEmitterLifetime ${params.systemName} ${params.emitterName} ${props.lifetime}`);
+                }
+                if (props.velocityMin && props.velocityMax) {
+                    const min = props.velocityMin;
+                    const max = props.velocityMax;
+                    commands.push(`SetEmitterVelocity ${params.systemName} ${params.emitterName} ${min[0]} ${min[1]} ${min[2]} ${max[0]} ${max[1]} ${max[2]}`);
+                }
+                if (props.size !== undefined) {
+                    commands.push(`SetEmitterSize ${params.systemName} ${params.emitterName} ${props.size}`);
+                }
+                if (props.color) {
+                    const color = props.color;
+                    commands.push(`SetEmitterColor ${params.systemName} ${params.emitterName} ${color[0]} ${color[1]} ${color[2]} ${color[3]}`);
+                }
+                if (props.material) {
+                    commands.push(`SetEmitterMaterial ${params.systemName} ${params.emitterName} ${props.material}`);
+                }
+                if (props.mesh && params.emitterType === 'Mesh') {
+                    commands.push(`SetEmitterMesh ${params.systemName} ${params.emitterName} ${props.mesh}`);
+                }
+            }
+            for (const cmd of commands) {
+                await this.bridge.executeConsoleCommand(cmd);
+            }
+            return { success: true, message: `Emitter ${params.emitterName} added to ${params.systemName}` };
+        }
+        catch (err) {
+            return { success: false, error: `Failed to add emitter: ${err}` };
+        }
+    }
+    async setParameter(params) {
+        try {
+            const paramType = params.isUserParameter ? 'User' : 'System';
+            let valueStr = '';
+            switch (params.parameterType) {
+                case 'Float':
+                case 'Int':
+                case 'Bool':
+                    valueStr = String(params.value);
+                    break;
+                case 'Vector': {
+                    const v = params.value;
+                    valueStr = `${v[0]} ${v[1]} ${v[2]}`;
+                    break;
+                }
+                case 'Color': {
+                    const c = params.value;
+                    valueStr = `${c[0]} ${c[1]} ${c[2]} ${c[3] || 1}`;
+                    break;
+                }
+            }
+            const command = `SetNiagara${paramType}Parameter ${params.systemName} ${params.parameterName} ${params.parameterType} ${valueStr}`;
+            await this.bridge.executeConsoleCommand(command);
+            return { success: true, message: `Parameter ${params.parameterName} set on ${params.systemName}` };
+        }
+        catch (err) {
+            return { success: false, error: `Failed to set parameter: ${err}` };
+        }
+    }
+    /**
+     * Create Preset Effect (now creates a real Niagara system asset)
+     */
+    async createEffect(params) {
+        try {
+            // Validate effect type at runtime (inputs can come from JSON)
+            const allowedTypes = ['Fire', 'Smoke', 'Explosion', 'Water', 'Rain', 'Snow', 'Magic', 'Lightning', 'Dust', 'Steam'];
+            if (!params || !allowedTypes.includes(String(params.effectType))) {
+                return { success: false, error: `Invalid effectType: ${String(params?.effectType)}` };
+            }
+            // Sanitize and validate name and path
+            const defaultPath = '/Game/Effects/Niagara';
+            const nameToUse = sanitizeAssetName(params.name);
+            const validation = validateAssetParams({ name: nameToUse, savePath: defaultPath });
+            if (!validation.valid) {
+                return { success: false, error: validation.error || 'Invalid asset parameters' };
+            }
+            const safeName = validation.sanitized.name;
+            const savePath = validation.sanitized.savePath || defaultPath;
+            const fullPath = `${savePath}/${safeName}`;
+            // Create or ensure the Niagara system asset exists
+            const createRes = await this.createSystem({ name: safeName, savePath, template: 'Empty' });
+            if (!createRes.success) {
+                return { success: false, error: createRes.error || 'Failed creating Niagara system' };
+            }
+            // Verify existence via Python to avoid RC EditorAssetLibrary issues
+            const verifyPy = `
+import unreal
+p = r"${fullPath}"
+print("RESULT:{'success': True, 'exists': %s}" % ('True' if unreal.EditorAssetLibrary.does_asset_exist(p) else 'False'))
+`.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 { }
+            }
+            return { success: true, message: `${params.effectType} effect ${safeName} created`, path: fullPath };
+        }
+        catch (err) {
+            return { success: false, error: `Failed to create effect: ${err}` };
+        }
+    }
+    async createGPUSimulation(params) {
+        try {
+            const path = params.savePath || '/Game/Effects/GPUSimulations';
+            const commands = [`CreateGPUSimulation ${params.name} ${params.simulationType} ${params.particleCount} ${path}`];
+            if (params.gpuSettings) {
+                const s = params.gpuSettings;
+                if (s.computeShader)
+                    commands.push(`SetGPUComputeShader ${params.name} ${s.computeShader}`);
+                if (s.textureFormat)
+                    commands.push(`SetGPUTextureFormat ${params.name} ${s.textureFormat}`);
+                if (s.gridResolution) {
+                    const r = s.gridResolution;
+                    commands.push(`SetGPUGridResolution ${params.name} ${r[0]} ${r[1]} ${r[2]}`);
+                }
+                if (s.iterations !== undefined)
+                    commands.push(`SetGPUIterations ${params.name} ${s.iterations}`);
+            }
+            for (const cmd of commands)
+                await this.bridge.executeConsoleCommand(cmd);
+            return { success: true, message: `GPU simulation ${params.name} created`, path: `${path}/${params.name}` };
+        }
+        catch (err) {
+            return { success: false, error: `Failed to create GPU simulation: ${err}` };
+        }
+    }
+    /**
+     * Spawn Niagara Effect in Level using Python (NiagaraActor)
+     */
+    async spawnEffect(params) {
+        try {
+            const loc = Array.isArray(params.location) ? { x: params.location[0], y: params.location[1], z: params.location[2] } : params.location;
+            const rot = params.rotation || [0, 0, 0];
+            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
+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'}")
+else:
+    print("RESULT:{'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 { }
+            }
+            return { success: true, message: 'Niagara effect spawn attempted' };
+        }
+        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