unreal-engine-mcp-server 0.2.1

package/dist/unreal-bridge.js

@@ -0,0 +1,992 @@
+import WebSocket from 'ws';
+import { createHttpClient } from './utils/http.js';
+import { Logger } from './utils/logger.js';
+import { loadEnv } from './types/env.js';
+export class UnrealBridge {
+    ws;
+    http = createHttpClient('');
+    env = loadEnv();
+    log = new Logger('UnrealBridge');
+    connected = false;
+    reconnectTimer;
+    reconnectAttempts = 0;
+    MAX_RECONNECT_ATTEMPTS = 5;
+    BASE_RECONNECT_DELAY = 1000;
+    // Command queue for throttling
+    commandQueue = [];
+    isProcessing = false;
+    MIN_COMMAND_DELAY = 100; // Increased to prevent console spam
+    MAX_COMMAND_DELAY = 500; // Maximum delay for heavy operations
+    STAT_COMMAND_DELAY = 300; // Special delay for stat commands to avoid warnings
+    lastCommandTime = 0;
+    lastStatCommandTime = 0; // Track stat commands separately
+    // Safe viewmodes that won't cause crashes (per docs and testing)
+    _SAFE_VIEWMODES = [
+        'Lit', 'Unlit', 'Wireframe', 'DetailLighting',
+        'LightingOnly', 'ReflectionOverride', 'ShaderComplexity'
+    ];
+    // Unsafe viewmodes that can cause crashes or instability via visualizeBuffer
+    UNSAFE_VIEWMODES = [
+        'BaseColor', 'WorldNormal', 'Metallic', 'Specular',
+        'Roughness', 'SubsurfaceColor', 'Opacity',
+        'LightComplexity', 'LightmapDensity',
+        'StationaryLightOverlap', 'CollisionPawn', 'CollisionVisibility'
+    ];
+    // Python script templates for EditorLevelLibrary access
+    PYTHON_TEMPLATES = {
+        GET_ALL_ACTORS: {
+            name: 'get_all_actors',
+            script: `
+import unreal
+# Use EditorActorSubsystem instead of deprecated EditorLevelLibrary
+subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+actors = subsys.get_all_level_actors()
+result = [{'name': a.get_name(), 'class': a.get_class().get_name(), 'path': a.get_path_name()} for a in actors]
+print(f"RESULT:{result}")
+      `.trim()
+        },
+        SPAWN_ACTOR_AT_LOCATION: {
+            name: 'spawn_actor',
+            script: `
+import unreal
+location = unreal.Vector({x}, {y}, {z})
+rotation = unreal.Rotator({pitch}, {yaw}, {roll})
+actor_class = unreal.EditorAssetLibrary.load_asset("{class_path}")
+if actor_class:
+    # Use EditorActorSubsystem instead of deprecated EditorLevelLibrary
+    subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+    spawned = subsys.spawn_actor_from_object(actor_class, location, rotation)
+    print(f"RESULT:{{'success': True, 'actor': spawned.get_name()}}")
+else:
+    print(f"RESULT:{{'success': False, 'error': 'Failed to load actor class'}}")
+      `.trim()
+        },
+        DELETE_ACTOR: {
+            name: 'delete_actor',
+            script: `
+import unreal
+import json
+subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+actors = subsys.get_all_level_actors()
+found = False
+for actor in actors:
+    if not actor:
+        continue
+    label = actor.get_actor_label()
+    name = actor.get_name()
+    if label == "{actor_name}" or name == "{actor_name}" or label.lower().startswith("{actor_name}".lower()+"_"):
+        subsys.destroy_actor(actor)
+        print("RESULT:" + json.dumps({'success': True, 'deleted': label}))
+        found = True
+        break
+if not found:
+    print("RESULT:" + json.dumps({'success': False, 'error': 'Actor not found'}))
+      `.trim()
+        },
+        CREATE_ASSET: {
+            name: 'create_asset',
+            script: `
+import unreal
+asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
+factory = unreal.{factory_class}()
+asset = asset_tools.create_asset("{asset_name}", "{package_path}", {asset_class}, factory)
+if asset:
+    unreal.EditorAssetLibrary.save_asset(asset.get_path_name())
+    print(f"RESULT:{{'success': True, 'path': asset.get_path_name()}}")
+else:
+    print(f"RESULT:{{'success': False, 'error': 'Failed to create asset'}}")
+      `.trim()
+        },
+        SET_VIEWPORT_CAMERA: {
+            name: 'set_viewport_camera',
+            script: `
+import unreal
+location = unreal.Vector({x}, {y}, {z})
+rotation = unreal.Rotator({pitch}, {yaw}, {roll})
+# Use UnrealEditorSubsystem for viewport operations (UE5.1+)
+ues = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
+les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
+if ues:
+    ues.set_level_viewport_camera_info(location, rotation)
+    try:
+        if les:
+            les.editor_invalidate_viewports()
+    except Exception:
+        pass
+    print(f"RESULT:{{'success': True, 'location': [{x}, {y}, {z}], 'rotation': [{pitch}, {yaw}, {roll}]}}")
+else:
+    print(f"RESULT:{{'success': False, 'error': 'UnrealEditorSubsystem not available'}}")
+      `.trim()
+        },
+        BUILD_LIGHTING: {
+            name: 'build_lighting',
+            script: `
+import unreal
+try:
+    les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
+    if les:
+        q = unreal.LightingBuildQuality.{quality}
+        les.build_light_maps(q, True)
+        print(f"RESULT:{{'success': True, 'quality': '{quality}', 'method': 'LevelEditorSubsystem'}}")
+    else:
+        print(f"RESULT:{{'success': False, 'error': 'LevelEditorSubsystem not available'}}")
+except Exception as e:
+    print(f"RESULT:{{'success': False, 'error': str(e)}}")
+      `.trim()
+        },
+        SAVE_ALL_DIRTY_PACKAGES: {
+            name: 'save_dirty_packages',
+            script: `
+import unreal
+saved = unreal.EditorLoadingAndSavingUtils.save_dirty_packages(True, True)
+print(f"RESULT:{{'success': {saved}, 'message': 'All dirty packages saved'}}")
+      `.trim()
+        }
+    };
+    get isConnected() { return this.connected; }
+    /**
+     * Attempt to connect with retries
+     * @param maxAttempts Maximum number of connection attempts
+     * @param timeoutMs Timeout for each connection attempt in milliseconds
+     * @param retryDelayMs Delay between retry attempts in milliseconds
+     * @returns Promise that resolves when connected or rejects after all attempts fail
+     */
+    async tryConnect(maxAttempts = 3, timeoutMs = 5000, retryDelayMs = 2000) {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                this.log.info(`Connection attempt ${attempt}/${maxAttempts}`);
+                await this.connect(timeoutMs);
+                return true; // Successfully connected
+            }
+            catch (err) {
+                this.log.warn(`Connection attempt ${attempt} failed:`, err);
+                if (attempt < maxAttempts) {
+                    this.log.info(`Retrying in ${retryDelayMs}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+                }
+                else {
+                    this.log.error(`All ${maxAttempts} connection attempts failed`);
+                    return false; // All attempts failed
+                }
+            }
+        }
+        return false;
+    }
+    async connect(timeoutMs = 5000) {
+        const wsUrl = `ws://${this.env.UE_HOST}:${this.env.UE_RC_WS_PORT}`;
+        const httpBase = `http://${this.env.UE_HOST}:${this.env.UE_RC_HTTP_PORT}`;
+        this.http = createHttpClient(httpBase);
+        this.log.info(`Connecting to UE Remote Control: ${wsUrl}`);
+        this.ws = new WebSocket(wsUrl);
+        await new Promise((resolve, reject) => {
+            if (!this.ws)
+                return reject(new Error('WS not created'));
+            // Setup timeout
+            const timeout = setTimeout(() => {
+                this.log.warn(`Connection timeout after ${timeoutMs}ms`);
+                if (this.ws) {
+                    this.ws.removeAllListeners();
+                    // Only close if the websocket is in CONNECTING state
+                    if (this.ws.readyState === WebSocket.CONNECTING) {
+                        try {
+                            this.ws.terminate(); // Use terminate instead of close for immediate cleanup
+                        }
+                        catch (e) {
+                            // Ignore close errors
+                        }
+                    }
+                    this.ws = undefined;
+                }
+                reject(new Error('Connection timeout: Unreal Engine may not be running or Remote Control is not enabled'));
+            }, timeoutMs);
+            // Success handler
+            const onOpen = () => {
+                clearTimeout(timeout);
+                this.connected = true;
+                this.log.info('Connected to Unreal Remote Control');
+                this.startCommandProcessor(); // Start command processor on connect
+                resolve();
+            };
+            // Error handler
+            const onError = (err) => {
+                clearTimeout(timeout);
+                this.log.error('WebSocket error', err);
+                if (this.ws) {
+                    this.ws.removeAllListeners();
+                    try {
+                        if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+                            this.ws.terminate();
+                        }
+                    }
+                    catch (e) {
+                        // Ignore close errors
+                    }
+                    this.ws = undefined;
+                }
+                reject(new Error(`Failed to connect: ${err.message}`));
+            };
+            // Close handler (if closed before open)
+            const onClose = () => {
+                if (!this.connected) {
+                    clearTimeout(timeout);
+                    reject(new Error('Connection closed before establishing'));
+                }
+                else {
+                    // Normal close after connection was established
+                    this.connected = false;
+                    this.log.warn('WebSocket closed');
+                    this.scheduleReconnect();
+                }
+            };
+            // Message handler (currently best-effort logging)
+            const onMessage = (raw) => {
+                try {
+                    const msg = JSON.parse(String(raw));
+                    this.log.debug('WS message', msg);
+                }
+                catch (e) {
+                    this.log.error('Failed parsing WS message', e);
+                }
+            };
+            // Attach listeners
+            this.ws.once('open', onOpen);
+            this.ws.once('error', onError);
+            this.ws.on('close', onClose);
+            this.ws.on('message', onMessage);
+        });
+    }
+    async httpCall(path, method = 'POST', body) {
+        const url = path.startsWith('/') ? path : `/${path}`;
+        const started = Date.now();
+        // Fix Content-Length header issue - ensure body is properly handled
+        if (body === undefined || body === null) {
+            body = method === 'GET' ? undefined : {};
+        }
+        // Add timeout wrapper to prevent hanging
+        const CALL_TIMEOUT = 10000; // 10 seconds timeout
+        // CRITICAL: Intercept and block dangerous console commands at HTTP level
+        if (url === '/remote/object/call' && body?.functionName === 'ExecuteConsoleCommand') {
+            const command = body?.parameters?.Command;
+            if (command && typeof command === 'string') {
+                const cmdLower = command.trim().toLowerCase();
+                // List of commands that cause crashes
+                const crashCommands = [
+                    'buildpaths', // Causes access violation 0x0000000000000060
+                    'rebuildnavigation', // Can crash without nav system
+                    'buildhierarchicallod', // Can crash without proper setup
+                    'buildlandscapeinfo', // Can crash without landscape
+                    'rebuildselectednavigation' // Nav-related crash
+                ];
+                // Check if this is a crash-inducing command
+                if (crashCommands.some(dangerous => cmdLower === dangerous || cmdLower.startsWith(dangerous + ' '))) {
+                    this.log.warn(`BLOCKED dangerous command that causes crashes: ${command}`);
+                    // Return a safe error response instead of executing
+                    return {
+                        success: false,
+                        error: `Command '${command}' blocked: This command can cause Unreal Engine to crash. Use the Python API alternatives instead.`
+                    };
+                }
+                // Also block other dangerous commands
+                const dangerousPatterns = [
+                    'quit', 'exit', 'r.gpucrash', 'debug crash',
+                    'viewmode visualizebuffer' // These can crash in certain states
+                ];
+                if (dangerousPatterns.some(pattern => cmdLower.includes(pattern))) {
+                    this.log.warn(`BLOCKED potentially dangerous command: ${command}`);
+                    return {
+                        success: false,
+                        error: `Command '${command}' blocked for safety.`
+                    };
+                }
+            }
+        }
+        // Retry logic with exponential backoff and timeout
+        let lastError;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                // For GET requests, send payload as query parameters (not in body)
+                const config = { url, method, timeout: CALL_TIMEOUT };
+                if (method === 'GET' && body && typeof body === 'object') {
+                    config.params = body;
+                }
+                else if (body !== undefined) {
+                    config.data = body;
+                }
+                // Wrap with timeout promise to ensure we don't hang
+                const requestPromise = this.http.request(config);
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new Error(`Request timeout after ${CALL_TIMEOUT}ms`));
+                    }, CALL_TIMEOUT);
+                });
+                const resp = await Promise.race([requestPromise, timeoutPromise]);
+                const ms = Date.now() - started;
+                this.log.debug(`[HTTP ${method}] ${url} -> ${ms}ms`);
+                return resp.data;
+            }
+            catch (error) {
+                lastError = error;
+                const delay = Math.min(1000 * Math.pow(2, attempt), 5000); // Exponential backoff with 5s max
+                // Log timeout errors specifically
+                if (error.message?.includes('timeout')) {
+                    this.log.warn(`HTTP request timed out (attempt ${attempt + 1}/3): ${url}`);
+                }
+                if (attempt < 2) {
+                    this.log.warn(`HTTP request failed (attempt ${attempt + 1}/3), retrying in ${delay}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    // If connection error, try to reconnect
+                    if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT' || error.message?.includes('timeout')) {
+                        this.scheduleReconnect();
+                    }
+                }
+            }
+        }
+        throw lastError;
+    }
+    // Generic function call via Remote Control HTTP API
+    async call(body) {
+        // Using HTTP endpoint /remote/object/call
+        const result = await this.httpCall('/remote/object/call', 'PUT', {
+            generateTransaction: false,
+            ...body
+        });
+        return result;
+    }
+    async getExposed() {
+        return this.httpCall('/remote/preset', 'GET');
+    }
+    // Execute a console command safely with validation and throttling
+    async executeConsoleCommand(command) {
+        // Validate command is not empty
+        if (!command || typeof command !== 'string') {
+            throw new Error('Invalid command: must be a non-empty string');
+        }
+        const cmdTrimmed = command.trim();
+        if (cmdTrimmed.length === 0) {
+            // Return success for empty commands to match UE behavior
+            return { success: true, message: 'Empty command ignored' };
+        }
+        // Check for dangerous commands
+        const dangerousCommands = [
+            'quit', 'exit', 'delete', 'destroy', 'kill', 'crash',
+            'viewmode visualizebuffer basecolor',
+            'viewmode visualizebuffer worldnormal',
+            'r.gpucrash',
+            'buildpaths', // Can cause access violation if nav system not initialized
+            'rebuildnavigation' // Can also crash without proper nav setup
+        ];
+        const cmdLower = cmdTrimmed.toLowerCase();
+        if (dangerousCommands.some(dangerous => cmdLower.includes(dangerous))) {
+            throw new Error(`Dangerous command blocked: ${command}`);
+        }
+        // Determine priority based on command type
+        let priority = 7; // Default priority
+        if (command.includes('BuildLighting') || command.includes('BuildPaths')) {
+            priority = 1; // Heavy operation
+        }
+        else if (command.includes('summon') || command.includes('spawn')) {
+            priority = 5; // Medium operation
+        }
+        else if (command.startsWith('stat') || command.startsWith('show')) {
+            priority = 9; // Light operation
+        }
+        // Known invalid command patterns
+        const invalidPatterns = [
+            /^\d+$/, // Just numbers
+            /^invalid_command/i,
+            /^this_is_not_a_valid/i,
+        ];
+        const isLikelyInvalid = invalidPatterns.some(pattern => pattern.test(cmdTrimmed));
+        if (isLikelyInvalid) {
+            this.log.warn(`Command appears invalid: ${cmdTrimmed}`);
+        }
+        try {
+            const result = await this.executeThrottledCommand(() => this.httpCall('/remote/object/call', 'PUT', {
+                objectPath: '/Script/Engine.Default__KismetSystemLibrary',
+                functionName: 'ExecuteConsoleCommand',
+                parameters: {
+                    WorldContextObject: null,
+                    Command: cmdTrimmed,
+                    SpecificPlayer: null
+                },
+                generateTransaction: false
+            }), priority);
+            return result;
+        }
+        catch (error) {
+            this.log.error(`Console command failed: ${cmdTrimmed}`, error);
+            throw error;
+        }
+    }
+    // Try to execute a Python command via the PythonScriptPlugin, fallback to `py` console command.
+    async executePython(command) {
+        const isMultiLine = /[\r\n]/.test(command) || command.includes(';');
+        try {
+            // Use ExecutePythonCommandEx with appropriate mode based on content
+            return await this.httpCall('/remote/object/call', 'PUT', {
+                objectPath: '/Script/PythonScriptPlugin.Default__PythonScriptLibrary',
+                functionName: 'ExecutePythonCommandEx',
+                parameters: {
+                    PythonCommand: command,
+                    ExecutionMode: isMultiLine ? 'ExecuteFile' : 'ExecuteStatement',
+                    FileExecutionScope: 'Private'
+                },
+                generateTransaction: false
+            });
+        }
+        catch {
+            try {
+                // Fallback to ExecutePythonCommand (more tolerant for multi-line)
+                return await this.httpCall('/remote/object/call', 'PUT', {
+                    objectPath: '/Script/PythonScriptPlugin.Default__PythonScriptLibrary',
+                    functionName: 'ExecutePythonCommand',
+                    parameters: {
+                        Command: command
+                    },
+                    generateTransaction: false
+                });
+            }
+            catch {
+                // Final fallback: execute via console py command
+                this.log.warn('PythonScriptLibrary not available or failed, falling back to console `py` command');
+                // For simple single-line commands
+                if (!isMultiLine) {
+                    return await this.executeConsoleCommand(`py ${command}`);
+                }
+                // For multi-line scripts, try to execute as a block
+                try {
+                    // Try executing as a single exec block
+                    // Properly escape the script for Python exec
+                    const escapedScript = command
+                        .replace(/\\/g, '\\\\')
+                        .replace(/"/g, '\\"')
+                        .replace(/\n/g, '\\n')
+                        .replace(/\r/g, '');
+                    return await this.executeConsoleCommand(`py exec("${escapedScript}")`);
+                }
+                catch {
+                    // If that fails, break into smaller chunks
+                    try {
+                        // First ensure unreal is imported
+                        await this.executeConsoleCommand('py import unreal');
+                        // For complex multi-line scripts, execute in logical chunks
+                        const commandWithoutImport = command.replace(/^\s*import\s+unreal\s*;?\s*/m, '');
+                        // Split by semicolons first, then by newlines
+                        const statements = commandWithoutImport
+                            .split(/[;\n]/)
+                            .map(s => s.trim())
+                            .filter(s => s.length > 0 && !s.startsWith('#'));
+                        let result = null;
+                        for (const stmt of statements) {
+                            // Skip if statement is too long for console
+                            if (stmt.length > 200) {
+                                // Try to execute as a single exec block
+                                const miniScript = `exec("""${stmt.replace(/"/g, '\\"')}""")`;
+                                result = await this.executeConsoleCommand(`py ${miniScript}`);
+                            }
+                            else {
+                                result = await this.executeConsoleCommand(`py ${stmt}`);
+                            }
+                            // Small delay between commands
+                            await new Promise(resolve => setTimeout(resolve, 30));
+                        }
+                        return result;
+                    }
+                    catch {
+                        // Final fallback: execute line by line
+                        const lines = command.split('\n').filter(line => line.trim().length > 0);
+                        let result = null;
+                        for (const line of lines) {
+                            // Skip comments
+                            if (line.trim().startsWith('#')) {
+                                continue;
+                            }
+                            result = await this.executeConsoleCommand(`py ${line.trim()}`);
+                            // Small delay between commands to ensure execution order
+                            await new Promise(resolve => setTimeout(resolve, 50));
+                        }
+                        return result;
+                    }
+                }
+            }
+        }
+    }
+    // Connection recovery
+    scheduleReconnect() {
+        if (this.reconnectTimer || this.connected) {
+            return;
+        }
+        if (this.reconnectAttempts >= this.MAX_RECONNECT_ATTEMPTS) {
+            this.log.error('Max reconnection attempts reached. Please check Unreal Engine.');
+            return;
+        }
+        // Exponential backoff with jitter
+        const delay = Math.min(this.BASE_RECONNECT_DELAY * Math.pow(2, this.reconnectAttempts) + Math.random() * 1000, 30000 // Max 30 seconds
+        );
+        this.log.info(`Scheduling reconnection attempt ${this.reconnectAttempts + 1}/${this.MAX_RECONNECT_ATTEMPTS} in ${Math.round(delay)}ms`);
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = undefined;
+            this.reconnectAttempts++;
+            try {
+                await this.connect();
+                this.reconnectAttempts = 0;
+                this.log.info('Successfully reconnected to Unreal Engine');
+            }
+            catch (err) {
+                this.log.error('Reconnection attempt failed:', err);
+                this.scheduleReconnect();
+            }
+        }, delay);
+    }
+    // Graceful shutdown
+    async disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = undefined;
+        }
+        this.connected = false;
+    }
+    /**
+     * Enhanced Editor Function Access
+     * Use Python scripting as a bridge to access modern Editor Subsystem functions
+     */
+    async executeEditorFunction(functionName, params) {
+        const template = this.PYTHON_TEMPLATES[functionName];
+        if (!template) {
+            throw new Error(`Unknown editor function: ${functionName}`);
+        }
+        let script = template.script;
+        // Replace parameters in the script
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                const placeholder = `{${key}}`;
+                script = script.replace(new RegExp(placeholder, 'g'), String(value));
+            }
+        }
+        try {
+            // Execute Python script with result parsing
+            const result = await this.executePythonWithResult(script);
+            return result;
+        }
+        catch (error) {
+            this.log.error(`Failed to execute editor function ${functionName}:`, error);
+            // Fallback to console command if Python fails
+            return this.executeFallbackCommand(functionName, params);
+        }
+    }
+    /**
+     * Execute Python script and parse the result
+     */
+    async executePythonWithResult(script) {
+        try {
+            // Wrap script to capture output so we can parse RESULT: lines reliably
+            const wrappedScript = `
+import sys
+import io
+old_stdout = sys.stdout
+sys.stdout = buffer = io.StringIO()
+try:
+    ${script.split('\n').join('\n    ')}
+finally:
+    output = buffer.getvalue()
+    sys.stdout = old_stdout
+    if output:
+        print(output)
+      `.trim()
+                .replace(/\r?\n/g, '\n');
+            const response = await this.executePython(wrappedScript);
+            // Extract textual output from various response shapes
+            let out = '';
+            try {
+                if (response && typeof response === 'string') {
+                    out = response;
+                }
+                else if (response && typeof response === 'object') {
+                    // Common RC Python response contains LogOutput array entries with .Output strings
+                    if (Array.isArray(response.LogOutput)) {
+                        out = response.LogOutput.map((l) => l.Output || '').join('');
+                    }
+                    else if (typeof response.Output === 'string') {
+                        out = response.Output;
+                    }
+                    else if (typeof response.result === 'string') {
+                        out = response.result;
+                    }
+                    else {
+                        // Fallback to stringifying object (may still include RESULT in nested fields)
+                        out = JSON.stringify(response);
+                    }
+                }
+            }
+            catch {
+                out = String(response || '');
+            }
+            // Find the last RESULT: JSON block in the output for robustness
+            const matches = Array.from(out.matchAll(/RESULT:({[\s\S]*?})/g));
+            if (matches.length > 0) {
+                const last = matches[matches.length - 1][1];
+                try {
+                    // Accept single quotes and True/False from Python repr if present
+                    const normalized = last
+                        .replace(/'/g, '"')
+                        .replace(/\bTrue\b/g, 'true')
+                        .replace(/\bFalse\b/g, 'false');
+                    return JSON.parse(normalized);
+                }
+                catch {
+                    return { raw: last };
+                }
+            }
+            // If no RESULT: marker, return the best-effort textual output or original response
+            return typeof response !== 'undefined' ? response : out;
+        }
+        catch {
+            this.log.warn('Python execution failed, trying direct execution');
+            return this.executePython(script);
+        }
+    }
+    /**
+     * Get the Unreal Engine version via Python and parse major/minor/patch.
+     */
+    async getEngineVersion() {
+        try {
+            const script = `
+import unreal, json, re
+ver = str(unreal.SystemLibrary.get_engine_version())
+m = re.match(r'^(\\d+)\\.(\\d+)\\.(\\d+)', ver)
+major = int(m.group(1)) if m else 0
+minor = int(m.group(2)) if m else 0
+patch = int(m.group(3)) if m else 0
+print('RESULT:' + json.dumps({'version': ver, 'major': major, 'minor': minor, 'patch': patch}))
+      `.trim();
+            const result = await this.executePythonWithResult(script);
+            const version = String(result?.version ?? 'unknown');
+            const major = Number(result?.major ?? 0) || 0;
+            const minor = Number(result?.minor ?? 0) || 0;
+            const patch = Number(result?.patch ?? 0) || 0;
+            const isUE56OrAbove = major > 5 || (major === 5 && minor >= 6);
+            return { version, major, minor, patch, isUE56OrAbove };
+        }
+        catch (error) {
+            this.log.warn('Failed to get engine version via Python', error);
+            return { version: 'unknown', major: 0, minor: 0, patch: 0, isUE56OrAbove: false };
+        }
+    }
+    /**
+     * Query feature flags (Python availability, editor subsystems) via Python.
+     */
+    async getFeatureFlags() {
+        try {
+            const script = `
+import unreal, json
+flags = {}
+# Python plugin availability (class exists)
+try:
+    _ = unreal.PythonScriptLibrary
+    flags['pythonEnabled'] = True
+except Exception:
+    flags['pythonEnabled'] = False
+# Editor subsystems
+try:
+    flags['unrealEditor'] = bool(unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem))
+except Exception:
+    flags['unrealEditor'] = False
+try:
+    flags['levelEditor'] = bool(unreal.get_editor_subsystem(unreal.LevelEditorSubsystem))
+except Exception:
+    flags['levelEditor'] = False
+try:
+    flags['editorActor'] = bool(unreal.get_editor_subsystem(unreal.EditorActorSubsystem))
+except Exception:
+    flags['editorActor'] = False
+print('RESULT:' + json.dumps(flags))
+      `.trim();
+            const res = await this.executePythonWithResult(script);
+            return {
+                pythonEnabled: Boolean(res?.pythonEnabled),
+                subsystems: {
+                    unrealEditor: Boolean(res?.unrealEditor),
+                    levelEditor: Boolean(res?.levelEditor),
+                    editorActor: Boolean(res?.editorActor)
+                }
+            };
+        }
+        catch (e) {
+            this.log.warn('Failed to get feature flags via Python', e);
+            return { pythonEnabled: false, subsystems: { unrealEditor: false, levelEditor: false, editorActor: false } };
+        }
+    }
+    /**
+     * Fallback commands when Python is not available
+     */
+    async executeFallbackCommand(functionName, params) {
+        switch (functionName) {
+            case 'SPAWN_ACTOR_AT_LOCATION':
+                return this.executeConsoleCommand(`summon ${params?.class_path || 'StaticMeshActor'} ${params?.x || 0} ${params?.y || 0} ${params?.z || 0}`);
+            case 'DELETE_ACTOR':
+                // Use Python-based deletion to avoid unsafe console command and improve reliability
+                return this.executePythonWithResult(this.PYTHON_TEMPLATES.DELETE_ACTOR.script.replace('{actor_name}', String(params?.actor_name || '')));
+            case 'BUILD_LIGHTING':
+                return this.executeConsoleCommand('BuildLighting');
+            default:
+                throw new Error(`No fallback available for ${functionName}`);
+        }
+    }
+    /**
+     * SOLUTION 2: Safe ViewMode Switching
+     * Prevent crashes by validating and safely switching viewmodes
+     */
+    async setSafeViewMode(mode) {
+        const normalizedMode = mode.charAt(0).toUpperCase() + mode.slice(1).toLowerCase();
+        // Check if the viewmode is known to be unsafe
+        if (this.UNSAFE_VIEWMODES.includes(normalizedMode)) {
+            this.log.warn(`Viewmode '${normalizedMode}' is known to cause crashes. Using safe alternative.`);
+            // For visualizeBuffer modes, we need special handling
+            if (normalizedMode === 'BaseColor' || normalizedMode === 'WorldNormal') {
+                // First ensure we're in a safe state
+                await this.executeConsoleCommand('viewmode Lit');
+                await this.delay(100);
+                // Try to use a safer alternative or skip
+                this.log.info(`Skipping unsafe visualizeBuffer mode: ${normalizedMode}`);
+                return {
+                    success: false,
+                    message: `Viewmode ${normalizedMode} skipped for safety`,
+                    alternative: 'Lit'
+                };
+            }
+            // For other unsafe modes, switch to safe alternatives
+            const safeAlternative = this.getSafeAlternative(normalizedMode);
+            return this.executeConsoleCommand(`viewmode ${safeAlternative}`);
+        }
+        // Safe mode - execute with delay
+        return this.executeThrottledCommand(() => this.httpCall('/remote/object/call', 'PUT', {
+            objectPath: '/Script/Engine.Default__KismetSystemLibrary',
+            functionName: 'ExecuteConsoleCommand',
+            parameters: {
+                WorldContextObject: null,
+                Command: `viewmode ${normalizedMode}`,
+                SpecificPlayer: null
+            },
+            generateTransaction: false
+        }));
+    }
+    /**
+     * Get safe alternative for unsafe viewmodes
+     */
+    getSafeAlternative(unsafeMode) {
+        const alternatives = {
+            'BaseColor': 'Unlit',
+            'WorldNormal': 'Lit',
+            'Metallic': 'Lit',
+            'Specular': 'Lit',
+            'Roughness': 'Lit',
+            'LightComplexity': 'LightingOnly',
+            'ShaderComplexity': 'Wireframe',
+            'CollisionPawn': 'Wireframe',
+            'CollisionVisibility': 'Wireframe'
+        };
+        return alternatives[unsafeMode] || 'Lit';
+    }
+    /**
+     * SOLUTION 3: Command Throttling and Queueing
+     * Prevent rapid command execution that can overwhelm the engine
+     */
+    async executeThrottledCommand(command, priority = 5) {
+        return new Promise((resolve, reject) => {
+            this.commandQueue.push({
+                command,
+                resolve,
+                reject,
+                priority
+            });
+            // Sort by priority (lower number = higher priority)
+            this.commandQueue.sort((a, b) => a.priority - b.priority);
+            // Process queue if not already processing
+            if (!this.isProcessing) {
+                this.processCommandQueue();
+            }
+        });
+    }
+    /**
+     * Process command queue with appropriate delays
+     */
+    async processCommandQueue() {
+        if (this.isProcessing || this.commandQueue.length === 0) {
+            return;
+        }
+        this.isProcessing = true;
+        while (this.commandQueue.length > 0) {
+            const item = this.commandQueue.shift();
+            if (!item)
+                continue; // Skip if undefined
+            // Calculate delay based on time since last command
+            const timeSinceLastCommand = Date.now() - this.lastCommandTime;
+            const requiredDelay = this.calculateDelay(item.priority);
+            if (timeSinceLastCommand < requiredDelay) {
+                await this.delay(requiredDelay - timeSinceLastCommand);
+            }
+            try {
+                const result = await item.command();
+                item.resolve(result);
+            }
+            catch (error) {
+                // Retry logic for transient failures
+                if (item.retryCount === undefined) {
+                    item.retryCount = 0;
+                }
+                if (item.retryCount < 3) {
+                    item.retryCount++;
+                    this.log.warn(`Command failed, retrying (${item.retryCount}/3)`);
+                    // Re-add to queue with increased priority
+                    this.commandQueue.unshift({
+                        command: item.command,
+                        resolve: item.resolve,
+                        reject: item.reject,
+                        priority: Math.max(1, item.priority - 1),
+                        retryCount: item.retryCount
+                    });
+                    // Add extra delay before retry
+                    await this.delay(500);
+                }
+                else {
+                    item.reject(error);
+                }
+            }
+            this.lastCommandTime = Date.now();
+        }
+        this.isProcessing = false;
+    }
+    /**
+     * Calculate appropriate delay based on command priority and type
+     */
+    calculateDelay(priority) {
+        // Priority 1-3: Heavy operations (asset creation, lighting build)
+        if (priority <= 3) {
+            return this.MAX_COMMAND_DELAY;
+        }
+        // Priority 4-6: Medium operations (actor spawning, material changes)
+        else if (priority <= 6) {
+            return 200;
+        }
+        // Priority 8: Stat commands - need special handling
+        else if (priority === 8) {
+            // Check time since last stat command to avoid FindConsoleObject warnings
+            const timeSinceLastStat = Date.now() - this.lastStatCommandTime;
+            if (timeSinceLastStat < this.STAT_COMMAND_DELAY) {
+                return this.STAT_COMMAND_DELAY;
+            }
+            this.lastStatCommandTime = Date.now();
+            return 150;
+        }
+        // Priority 7,9-10: Light operations (console commands, queries)
+        else {
+            return this.MIN_COMMAND_DELAY;
+        }
+    }
+    /**
+     * SOLUTION 4: Enhanced Asset Creation
+     * Use Python scripting for complex asset creation that requires editor scripting
+     */
+    async createComplexAsset(assetType, params) {
+        const assetCreators = {
+            'Material': 'MaterialFactoryNew',
+            'MaterialInstance': 'MaterialInstanceConstantFactoryNew',
+            'Blueprint': 'BlueprintFactory',
+            'AnimationBlueprint': 'AnimBlueprintFactory',
+            'ControlRig': 'ControlRigBlueprintFactory',
+            'NiagaraSystem': 'NiagaraSystemFactoryNew',
+            'NiagaraEmitter': 'NiagaraEmitterFactoryNew',
+            'LandscapeGrassType': 'LandscapeGrassTypeFactory',
+            'PhysicsAsset': 'PhysicsAssetFactory'
+        };
+        const factoryClass = assetCreators[assetType];
+        if (!factoryClass) {
+            throw new Error(`Unknown asset type: ${assetType}`);
+        }
+        const createParams = {
+            factory_class: factoryClass,
+            asset_class: `unreal.${assetType}`,
+            asset_name: params.name || `New${assetType}`,
+            package_path: params.path || '/Game/CreatedAssets',
+            ...params
+        };
+        return this.executeEditorFunction('CREATE_ASSET', createParams);
+    }
+    /**
+     * Start the command processor
+     */
+    startCommandProcessor() {
+        // Periodic queue processing to handle any stuck commands
+        setInterval(() => {
+            if (!this.isProcessing && this.commandQueue.length > 0) {
+                this.processCommandQueue();
+            }
+        }, 1000);
+    }
+    /**
+     * Helper delay function
+     */
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Batch command execution with proper delays
+     */
+    async executeBatch(commands) {
+        const results = [];
+        for (const cmd of commands) {
+            const result = await this.executeConsoleCommand(cmd.command);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Get safe console commands for common operations
+     */
+    getSafeCommands() {
+        return {
+            // Health check (safe, no side effects)
+            'HealthCheck': 'echo MCP Server Health Check',
+            // Performance monitoring (safe)
+            'ShowFPS': 'stat unit', // Use 'stat unit' instead of 'stat fps'
+            'ShowMemory': 'stat memory',
+            'ShowGame': 'stat game',
+            'ShowRendering': 'stat scenerendering',
+            'ClearStats': 'stat none',
+            // Safe viewmodes
+            'ViewLit': 'viewmode lit',
+            'ViewUnlit': 'viewmode unlit',
+            'ViewWireframe': 'viewmode wireframe',
+            'ViewDetailLighting': 'viewmode detaillighting',
+            'ViewLightingOnly': 'viewmode lightingonly',
+            // Safe show flags
+            'ShowBounds': 'show bounds',
+            'ShowCollision': 'show collision',
+            'ShowNavigation': 'show navigation',
+            'ShowFog': 'show fog',
+            'ShowGrid': 'show grid',
+            // PIE controls
+            'PlayInEditor': 'play',
+            'StopPlay': 'stop',
+            'PausePlay': 'pause',
+            // Time control
+            'SlowMotion': 'slomo 0.5',
+            'NormalSpeed': 'slomo 1',
+            'FastForward': 'slomo 2',
+            // Camera controls
+            'CameraSpeed1': 'camspeed 1',
+            'CameraSpeed4': 'camspeed 4',
+            'CameraSpeed8': 'camspeed 8',
+            // Rendering quality (safe)
+            'LowQuality': 'sg.ViewDistanceQuality 0',
+            'MediumQuality': 'sg.ViewDistanceQuality 1',
+            'HighQuality': 'sg.ViewDistanceQuality 2',
+            'EpicQuality': 'sg.ViewDistanceQuality 3'
+        };
+    }
+}
+//# sourceMappingURL=unreal-bridge.js.map