unreal-engine-mcp-server 0.4.7 → 0.5.0

package/dist/tools/handlers/actor-handlers.js

@@ -0,0 +1,232 @@
+import { cleanObject } from '../../utils/safe-json.js';
+import { executeAutomationRequest } from './common-handlers.js';
+import { Logger } from '../../utils/logger.js';
+import { normalizeArgs } from './argument-helper.js';
+const logger = new Logger('ActorHandlers');
+const handlers = {
+    spawn: async (args, tools) => {
+        const classAliases = {
+            'SplineActor': '/Script/Engine.Actor',
+            'Spline': '/Script/Engine.Actor',
+            'PointLight': '/Script/Engine.PointLight',
+            'SpotLight': '/Script/Engine.SpotLight',
+            'DirectionalLight': '/Script/Engine.DirectionalLight',
+            'Camera': '/Script/Engine.CameraActor',
+            'CameraActor': '/Script/Engine.CameraActor',
+            'StaticMeshActor': '/Script/Engine.StaticMeshActor',
+            'SkeletalMeshActor': '/Script/Engine.SkeletalMeshActor',
+            'PlayerStart': '/Script/Engine.PlayerStart',
+            'TriggerBox': '/Script/Engine.TriggerBox',
+            'TriggerSphere': '/Script/Engine.TriggerSphere',
+            'BlockingVolume': '/Script/Engine.BlockingVolume',
+            'Pawn': '/Script/Engine.Pawn',
+            'Character': '/Script/Engine.Character',
+            'Actor': '/Script/Engine.Actor'
+        };
+        const params = normalizeArgs(args, [
+            { key: 'classPath', aliases: ['class', 'type', 'actorClass'], required: true, map: classAliases },
+            { key: 'actorName', aliases: ['name'] },
+            { key: 'timeoutMs', default: undefined }
+        ]);
+        const timeoutMs = typeof params.timeoutMs === 'number' ? params.timeoutMs : undefined;
+        if (typeof timeoutMs === 'number' && timeoutMs > 0 && timeoutMs < 200) {
+            return cleanObject({
+                success: false,
+                error: `Timeout too small for spawn operation: ${timeoutMs}ms`,
+                message: 'Timeout too small for spawn operation'
+            });
+        }
+        const originalClass = args.classPath || args.class || args.type || args.actorClass;
+        const componentToAdd = (originalClass === 'SplineActor' || originalClass === 'Spline')
+            ? 'SplineComponent'
+            : undefined;
+        const result = await tools.actorTools.spawn({
+            classPath: params.classPath,
+            actorName: params.actorName,
+            location: args.location,
+            rotation: args.rotation,
+            meshPath: args.meshPath,
+            timeoutMs,
+            ...(componentToAdd ? { componentToAdd } : {})
+        });
+        if (result && result.success && result.actorName) {
+            return {
+                ...result,
+                message: `Spawned actor: ${result.actorName}`,
+                name: result.actorName
+            };
+        }
+        return result;
+    },
+    delete: async (args, tools) => {
+        if (args.actorNames && Array.isArray(args.actorNames)) {
+            return tools.actorTools.delete({ actorNames: args.actorNames });
+        }
+        const params = normalizeArgs(args, [
+            { key: 'actorName', aliases: ['name'], required: true }
+        ]);
+        return tools.actorTools.delete({ actorName: params.actorName });
+    },
+    apply_force: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'actorName', aliases: ['name'], required: true }
+        ]);
+        const force = args.force;
+        const tryApplyForce = async () => {
+            return await tools.actorTools.applyForce({
+                actorName: params.actorName,
+                force
+            });
+        };
+        try {
+            return await tryApplyForce();
+        }
+        catch (error) {
+            const errorMsg = error.message || String(error);
+            if (errorMsg.toUpperCase().includes('PHYSICS')) {
+                try {
+                    const compsResult = await tools.actorTools.getComponents(params.actorName);
+                    if (compsResult && compsResult.success && Array.isArray(compsResult.components)) {
+                        logger.debug('Components found:', JSON.stringify(compsResult.components));
+                        const meshComp = compsResult.components.find((c) => {
+                            const name = c.name || c;
+                            const match = typeof name === 'string' && (name.toLowerCase().includes('staticmesh') ||
+                                name.toLowerCase().includes('mesh') ||
+                                name.toLowerCase().includes('primitive'));
+                            logger.debug(`Checking component '${name}' matches? ${match}`);
+                            return match;
+                        });
+                        if (meshComp) {
+                            const compName = meshComp.name || meshComp;
+                            logger.debug(`Auto-enabling physics for component: ${compName}`);
+                            await tools.actorTools.setComponentProperties({
+                                actorName: params.actorName,
+                                componentName: compName,
+                                properties: { SimulatePhysics: true, bSimulatePhysics: true, Mobility: 2 }
+                            });
+                            return await tryApplyForce();
+                        }
+                    }
+                }
+                catch (retryError) {
+                    throw new Error(`${errorMsg} (Auto-enable physics failed: ${retryError.message})`);
+                }
+            }
+            throw error;
+        }
+    },
+    set_transform: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'actorName', aliases: ['name'], required: true }
+        ]);
+        return tools.actorTools.setTransform({
+            actorName: params.actorName,
+            location: args.location,
+            rotation: args.rotation,
+            scale: args.scale
+        });
+    },
+    get_transform: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'actorName', aliases: ['name'], required: true }
+        ]);
+        return tools.actorTools.getTransform(params.actorName);
+    },
+    duplicate: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'actorName', aliases: ['name'], required: true },
+            { key: 'newName', aliases: ['nameTo'] }
+        ]);
+        return tools.actorTools.duplicate({
+            actorName: params.actorName,
+            newName: params.newName,
+            offset: args.offset
+        });
+    },
+    attach: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'childActor', aliases: ['actorName', 'child'], required: true },
+            { key: 'parentActor', aliases: ['parent'], required: true }
+        ]);
+        return tools.actorTools.attach({ childActor: params.childActor, parentActor: params.parentActor });
+    },
+    detach: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'actorName', aliases: ['childActor', 'child'], required: true }
+        ]);
+        return tools.actorTools.detach(params.actorName);
+    },
+    add_tag: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'actorName', aliases: ['name'], required: true },
+            { key: 'tag', required: true }
+        ]);
+        return tools.actorTools.addTag({ actorName: params.actorName, tag: params.tag });
+    },
+    remove_tag: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'actorName', aliases: ['name'], required: true },
+            { key: 'tag', required: true }
+        ]);
+        return tools.actorTools.removeTag({ actorName: params.actorName, tag: params.tag });
+    },
+    find_by_tag: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'tag', default: '' }
+        ]);
+        return tools.actorTools.findByTag({ tag: params.tag, matchType: args.matchType });
+    },
+    delete_by_tag: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'tag', required: true }
+        ]);
+        return tools.actorTools.deleteByTag(params.tag);
+    },
+    spawn_blueprint: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'blueprintPath', aliases: ['path', 'bp'], required: true },
+            { key: 'actorName', aliases: ['name'] }
+        ]);
+        const result = await tools.actorTools.spawnBlueprint({
+            blueprintPath: params.blueprintPath,
+            actorName: params.actorName,
+            location: args.location,
+            rotation: args.rotation
+        });
+        if (result && result.success && result.actorName) {
+            return {
+                ...result,
+                message: `Spawned blueprint: ${result.actorName}`,
+                name: result.actorName
+            };
+        }
+        return result;
+    },
+    list: async (args, tools) => {
+        const result = await tools.actorTools.listActors();
+        if (result && result.actors && Array.isArray(result.actors)) {
+            const limit = typeof args.limit === 'number' ? args.limit : 50;
+            const count = result.actors.length;
+            const names = result.actors.slice(0, limit).map((a) => a.label || a.name).join(', ');
+            const remaining = count - limit;
+            const suffix = remaining > 0 ? `... and ${remaining} others` : '';
+            result.message = `Found ${count} actors: ${names}${suffix}`;
+        }
+        return result;
+    },
+    find_by_name: async (args, tools) => {
+        const params = normalizeArgs(args, [
+            { key: 'name', aliases: ['actorName', 'query'], required: true }
+        ]);
+        return tools.actorTools.findByName(params.name);
+    }
+};
+export async function handleActorTools(action, args, tools) {
+    const handler = handlers[action];
+    if (handler) {
+        const res = await handler(args, tools);
+        return cleanObject(res);
+    }
+    return executeAutomationRequest(tools, 'control_actor', args);
+}
+//# sourceMappingURL=actor-handlers.js.map

package/dist/tools/handlers/animation-handlers.d.ts

@@ -0,0 +1,3 @@
+import { ITools } from '../../types/tool-interfaces.js';
+export declare function handleAnimationTools(action: string, args: any, tools: ITools): Promise<any>;
+//# sourceMappingURL=animation-handlers.d.ts.map

package/dist/tools/handlers/animation-handlers.js

@@ -0,0 +1,185 @@
+import { cleanObject } from '../../utils/safe-json.js';
+import { executeAutomationRequest } from './common-handlers.js';
+export async function handleAnimationTools(action, args, tools) {
+    const animAction = String(action || '').toLowerCase();
+    if (animAction === 'create_animation_blueprint' || animAction === 'create_anim_blueprint' || animAction === 'create_animation_bp') {
+        const name = args.name ?? args.blueprintName;
+        const skeletonPath = args.skeletonPath ?? args.targetSkeleton;
+        const savePath = args.savePath ?? args.path ?? '/Game/Animations';
+        if (!skeletonPath && args.actorName) {
+            try {
+                const compsRes = await tools.actorTools.getComponents(args.actorName);
+                if (compsRes && Array.isArray(compsRes.components)) {
+                    const meshComp = compsRes.components.find((c) => c.type === 'SkeletalMeshComponent' || c.className === 'SkeletalMeshComponent');
+                    if (meshComp && meshComp.skeletalMesh) {
+                    }
+                }
+            }
+            catch (_e) { }
+        }
+        const payload = {
+            ...args,
+            name,
+            skeletonPath,
+            savePath
+        };
+        return await executeAutomationRequest(tools, 'create_animation_blueprint', payload, 'Automation bridge not available for animation blueprint creation');
+    }
+    if (animAction === 'play_anim_montage' || animAction === 'play_montage') {
+        const resp = await executeAutomationRequest(tools, 'play_anim_montage', args, 'Automation bridge not available for montage playback');
+        const result = resp?.result ?? resp ?? {};
+        const errorCode = typeof result.error === 'string' ? result.error.toUpperCase() : '';
+        const message = typeof result.message === 'string' ? result.message : '';
+        const msgLower = message.toLowerCase();
+        if (msgLower.includes('actor not found') || msgLower.includes('no animation played') || errorCode === 'ACTOR_NOT_FOUND') {
+            return cleanObject({
+                success: false,
+                error: 'ACTOR_NOT_FOUND',
+                message: message || 'Actor not found; no animation played',
+                actorName: args.actorName
+            });
+        }
+        if (errorCode === 'INVALID_ARGUMENT' &&
+            msgLower.includes('actorname required') &&
+            typeof args.playRate === 'number' &&
+            args.playRate === 0) {
+            return cleanObject({
+                success: true,
+                noOp: true,
+                message: 'Montage playback skipped: playRate 0 with missing actorName treated as no-op.'
+            });
+        }
+        return cleanObject(resp);
+    }
+    if (animAction === 'setup_ragdoll' || animAction === 'activate_ragdoll') {
+        if (args.actorName && !args.meshPath && !args.skeletonPath) {
+            try {
+                const compsRes = await tools.actorTools.getComponents(args.actorName);
+                if (compsRes && Array.isArray(compsRes.components)) {
+                    const meshComp = compsRes.components.find((c) => c.type === 'SkeletalMeshComponent' || c.className === 'SkeletalMeshComponent');
+                    if (meshComp && meshComp.path) {
+                        args.meshPath = meshComp.path;
+                    }
+                }
+            }
+            catch (_e) {
+            }
+        }
+        const resp = await executeAutomationRequest(tools, 'setup_ragdoll', args, 'Automation bridge not available for ragdoll setup');
+        const result = resp?.result ?? resp ?? {};
+        const message = typeof result.message === 'string' ? result.message : '';
+        const msgLower = message.toLowerCase();
+        if (msgLower.includes('actor not found') || msgLower.includes('no ragdoll applied')) {
+            return cleanObject({
+                success: false,
+                error: 'ACTOR_NOT_FOUND',
+                message: message || 'Actor not found; no ragdoll applied',
+                actorName: args.actorName
+            });
+        }
+        return cleanObject(resp);
+    }
+    if (animAction === 'create_blend_space' || animAction === 'create_blend_tree') {
+        if (args.horizontalAxis) {
+            args.minX = args.horizontalAxis.minValue;
+            args.maxX = args.horizontalAxis.maxValue;
+        }
+        if (args.verticalAxis) {
+            args.minY = args.verticalAxis.minValue;
+            args.maxY = args.verticalAxis.maxValue;
+        }
+    }
+    switch (animAction) {
+        case 'create_blend_space':
+            return cleanObject(await tools.animationTools.createBlendSpace({
+                name: args.name,
+                path: args.path || args.savePath,
+                skeletonPath: args.skeletonPath,
+                horizontalAxis: args.horizontalAxis,
+                verticalAxis: args.verticalAxis
+            }));
+        case 'create_state_machine':
+            return cleanObject(await tools.animationTools.createStateMachine({
+                machineName: args.machineName || args.name,
+                states: args.states,
+                transitions: args.transitions,
+                blueprintPath: args.blueprintPath || args.path || args.savePath
+            }));
+        case 'setup_ik':
+            return cleanObject(await tools.animationTools.setupIK({
+                actorName: args.actorName,
+                ikBones: args.ikBones,
+                enableFootPlacement: args.enableFootPlacement
+            }));
+        case 'create_procedural_anim':
+            return cleanObject(await tools.animationTools.createProceduralAnim({
+                systemName: args.systemName || args.name,
+                baseAnimation: args.baseAnimation,
+                modifiers: args.modifiers,
+                savePath: args.savePath || args.path
+            }));
+        case 'create_blend_tree':
+            return cleanObject(await tools.animationTools.createBlendTree({
+                treeName: args.treeName || args.name,
+                blendType: args.blendType,
+                basePose: args.basePose,
+                additiveAnimations: args.additiveAnimations,
+                savePath: args.savePath || args.path
+            }));
+        case 'cleanup':
+            return cleanObject(await tools.animationTools.cleanup(args.artifacts));
+        case 'create_animation_asset': {
+            let assetType = args.assetType;
+            if (!assetType && args.name) {
+                if (args.name.toLowerCase().endsWith('montage') || args.name.toLowerCase().includes('montage')) {
+                    assetType = 'montage';
+                }
+            }
+            return cleanObject(await tools.animationTools.createAnimationAsset({
+                name: args.name,
+                path: args.path || args.savePath,
+                skeletonPath: args.skeletonPath,
+                assetType
+            }));
+        }
+        case 'add_notify':
+            return cleanObject(await tools.animationTools.addNotify({
+                animationPath: args.animationPath,
+                assetPath: args.assetPath,
+                notifyName: args.notifyName || args.name,
+                time: args.time ?? args.startTime
+            }));
+        case 'configure_vehicle':
+            return cleanObject(await tools.physicsTools.configureVehicle({
+                vehicleName: args.vehicleName,
+                vehicleType: args.vehicleType,
+                wheels: args.wheels,
+                engine: args.engine,
+                transmission: args.transmission,
+                pluginDependencies: args.pluginDependencies ?? args.plugins
+            }));
+        case 'setup_physics_simulation': {
+            const payload = {
+                meshPath: args.meshPath,
+                skeletonPath: args.skeletonPath,
+                physicsAssetName: args.physicsAssetName,
+                savePath: args.savePath
+            };
+            if (args.actorName && !args.meshPath && !args.skeletonPath) {
+                payload.actorName = args.actorName;
+            }
+            if (!payload.meshPath && !payload.skeletonPath && !payload.actorName) {
+                return cleanObject({
+                    success: false,
+                    error: 'INVALID_ARGUMENT',
+                    message: 'setup_physics_simulation requires meshPath, skeletonPath, or actorName parameter'
+                });
+            }
+            return cleanObject(await tools.physicsTools.setupPhysicsSimulation(payload));
+        }
+        default:
+            const res = await executeAutomationRequest(tools, 'animation_physics', args, 'Automation bridge not available for animation/physics operations');
+            return cleanObject(res);
+    }
+}
+//# sourceMappingURL=animation-handlers.js.map

package/dist/tools/handlers/argument-helper.d.ts

@@ -0,0 +1,16 @@
+import { ITools } from '../../types/tool-interfaces.js';
+export interface ArgConfig {
+    key: string;
+    aliases?: string[];
+    required?: boolean;
+    default?: any;
+    map?: Record<string, string>;
+    validator?: (val: any) => void | string;
+}
+export declare function normalizeArgs(args: any, configs: ArgConfig[]): any;
+export declare function resolveObjectPath(args: any, tools: ITools, config?: {
+    pathKeys?: string[];
+    actorKeys?: string[];
+    fallbackToName?: boolean;
+}): Promise<string | undefined>;
+//# sourceMappingURL=argument-helper.d.ts.map

package/dist/tools/handlers/argument-helper.js

@@ -0,0 +1,80 @@
+export function normalizeArgs(args, configs) {
+    const normalized = { ...args };
+    for (const config of configs) {
+        let val = undefined;
+        if (args[config.key] !== undefined && args[config.key] !== null && args[config.key] !== '') {
+            val = args[config.key];
+        }
+        if (val === undefined && config.aliases) {
+            for (const alias of config.aliases) {
+                if (args[alias] !== undefined && args[alias] !== null && args[alias] !== '') {
+                    val = args[alias];
+                    break;
+                }
+            }
+        }
+        if (val === undefined && config.default !== undefined) {
+            val = config.default;
+        }
+        if (config.required) {
+            if (val === undefined || val === null || (typeof val === 'string' && val.trim() === '')) {
+                const aliasStr = config.aliases ? ` (or ${config.aliases.join(', ')})` : '';
+                throw new Error(`Missing required argument: ${config.key}${aliasStr}`);
+            }
+        }
+        if (config.map && typeof val === 'string') {
+            if (config.map[val]) {
+                val = config.map[val];
+            }
+        }
+        if (config.validator && val !== undefined) {
+            const err = config.validator(val);
+            if (typeof err === 'string') {
+                throw new Error(`Invalid argument '${config.key}': ${err}`);
+            }
+        }
+        if (val !== undefined) {
+            normalized[config.key] = val;
+        }
+    }
+    return normalized;
+}
+export async function resolveObjectPath(args, tools, config) {
+    const pathKeys = config?.pathKeys || ['objectPath', 'path'];
+    const actorKeys = config?.actorKeys || ['actorName', 'name'];
+    const fallback = config?.fallbackToName !== false;
+    for (const key of pathKeys) {
+        if (typeof args[key] === 'string' && args[key].trim().length > 0) {
+            return args[key].trim().replace(/\/+$/, '');
+        }
+    }
+    let potentialName;
+    for (const key of actorKeys) {
+        if (typeof args[key] === 'string' && args[key].trim().length > 0) {
+            potentialName = args[key].trim();
+            break;
+        }
+    }
+    if (potentialName) {
+        if (tools.actorTools && typeof tools.actorTools.findByName === 'function') {
+            try {
+                const res = await tools.actorTools.findByName(potentialName);
+                const container = res && (res.result || res);
+                const actors = container && Array.isArray(container.actors) ? container.actors : [];
+                if (actors.length > 0) {
+                    const first = actors[0];
+                    const resolvedPath = first.path || first.objectPath || first.levelPath;
+                    if (typeof resolvedPath === 'string' && resolvedPath.trim().length > 0) {
+                        return resolvedPath.trim();
+                    }
+                }
+            }
+            catch {
+            }
+        }
+        if (fallback)
+            return potentialName;
+    }
+    return undefined;
+}
+//# sourceMappingURL=argument-helper.js.map

package/dist/tools/handlers/asset-handlers.d.ts

@@ -0,0 +1,3 @@
+import { ITools } from '../../types/tool-interfaces.js';
+export declare function handleAssetTools(action: string, args: any, tools: ITools): Promise<any>;
+//# sourceMappingURL=asset-handlers.d.ts.map