unreal-engine-mcp-server 0.3.1 → 0.4.3

package/dist/tools/ui.js

@@ -1,20 +1,9 @@
+import { bestEffortInterpretedText, interpretStandardResult } from '../utils/result-helpers.js';
 export class UITools {
     bridge;
     constructor(bridge) {
         this.bridge = bridge;
     }
-    // Execute console command
-    async _executeCommand(command) {
-        return this.bridge.httpCall('/remote/object/call', 'PUT', {
-            objectPath: '/Script/Engine.Default__KismetSystemLibrary',
-            functionName: 'ExecuteConsoleCommand',
-            parameters: {
-                Command: command,
-                SpecificPlayer: null
-            },
-            generateTransaction: false
-        });
-    }
     // Create widget blueprint
     async createWidget(params) {
         const path = params.savePath || '/Game/UI/Widgets';
@@ -51,16 +40,18 @@ except Exception as e:
 `.trim();
         try {
             const resp = await this.bridge.executePython(py);
-            const out = typeof resp === 'string' ? resp : JSON.stringify(resp);
-            const m = out.match(/RESULT:({.*})/);
-            if (m) {
-                try {
-                    const parsed = JSON.parse(m[1]);
-                    return parsed.success ? { success: true, message: 'Widget blueprint created' } : { success: false, error: parsed.error };
-                }
-                catch { }
+            const interpreted = interpretStandardResult(resp, {
+                successMessage: 'Widget blueprint created',
+                failureMessage: 'Failed to create WidgetBlueprint'
+            });
+            if (interpreted.success) {
+                return { success: true, message: interpreted.message };
             }
-            return { success: true, message: 'Widget blueprint creation attempted' };
+            return {
+                success: false,
+                error: interpreted.error ?? 'Failed to create widget blueprint',
+                details: bestEffortInterpretedText(interpreted)
+            };
         }
         catch (e) {
             return { success: false, error: `Failed to create widget blueprint: ${e}` };
@@ -84,9 +75,7 @@ except Exception as e:
                 commands.push(`SetWidgetAlignment ${params.widgetName}.${params.componentName} ${params.slot.alignment.join(' ')}`);
             }
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: `Component ${params.componentName} added to widget` };
     }
     // Set text
@@ -102,9 +91,7 @@ except Exception as e:
         if (params.fontFamily) {
             commands.push(`SetWidgetFont ${params.widgetName}.${params.componentName} ${params.fontFamily}`);
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: 'Widget text updated' };
     }
     // Set image
@@ -117,9 +104,7 @@ except Exception as e:
         if (params.sizeToContent !== undefined) {
             commands.push(`SetWidgetSizeToContent ${params.widgetName}.${params.componentName} ${params.sizeToContent}`);
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: 'Widget image updated' };
     }
     // Create HUD
@@ -132,18 +117,50 @@ except Exception as e:
                 commands.push(`AddHUDElement ${params.name} ${element.type} ${element.position.join(' ')} ${size.join(' ')}`);
             }
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: `HUD ${params.name} created` };
     }
     // Show/Hide widget
     async setWidgetVisibility(params) {
         const playerIndex = params.playerIndex ?? 0;
+        const widgetName = params.widgetName?.trim();
+        if (!widgetName) {
+            return { success: false, error: 'widgetName is required' };
+        }
+        const verifyScript = `
+import unreal, json
+name = r"${widgetName}"
+candidates = []
+if name.startswith('/Game/'):
+    candidates.append(name)
+else:
+    candidates.append(f"/Game/UI/Widgets/{name}")
+    candidates.append(f"/Game/{name}")
+
+found_path = ''
+for path in candidates:
+    if unreal.EditorAssetLibrary.does_asset_exist(path):
+        found_path = path
+        break
+
+print('RESULT:' + json.dumps({'success': bool(found_path), 'path': found_path, 'candidates': candidates}))
+`.trim();
+        const verify = await this.bridge.executePythonWithResult(verifyScript);
+        if (!verify?.success) {
+            return { success: false, error: `Widget asset not found for ${widgetName}` };
+        }
         const command = params.visible
-            ? `ShowWidget ${params.widgetName} ${playerIndex}`
-            : `HideWidget ${params.widgetName} ${playerIndex}`;
-        return this.bridge.executeConsoleCommand(command);
+            ? `ShowWidget ${widgetName} ${playerIndex}`
+            : `HideWidget ${widgetName} ${playerIndex}`;
+        const raw = await this.bridge.executeConsoleCommand(command);
+        const summary = this.bridge.summarizeConsoleCommand(command, raw);
+        return {
+            success: true,
+            message: params.visible ? `Widget ${widgetName} show command issued` : `Widget ${widgetName} hide command issued`,
+            command: summary.command,
+            output: summary.output || undefined,
+            logLines: summary.logLines?.length ? summary.logLines : undefined
+        };
     }
     // Add widget to viewport
     async addWidgetToViewport(params) {
@@ -168,10 +185,20 @@ try:
             # Get the generated class from the widget blueprint
             widget_class = widget_bp.generated_class() if hasattr(widget_bp, 'generated_class') else widget_bp
             
-            # Get the world and player controller
-            world = unreal.EditorLevelLibrary.get_editor_world()
-            if not world:
-                print('RESULT:' + json.dumps({'success': False, 'error': 'No editor world available'}))
+      # Get the world and player controller via modern subsystems
+      world = None
+      try:
+        world = unreal.EditorUtilityLibrary.get_editor_world()
+      except Exception:
+        pass
+
+      if not world:
+        editor_subsystem = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
+        if editor_subsystem and hasattr(editor_subsystem, 'get_editor_world'):
+          world = editor_subsystem.get_editor_world()
+
+      if not world:
+        print('RESULT:' + json.dumps({'success': False, 'error': 'No editor world available. Start a PIE session or enable Editor Scripting Utilities.'}))
             else:
                 # Try to get player controller
                 try:
@@ -196,18 +223,18 @@ except Exception as e:
 `.trim();
         try {
             const resp = await this.bridge.executePython(py);
-            const out = typeof resp === 'string' ? resp : JSON.stringify(resp);
-            const m = out.match(/RESULT:({.*})/);
-            if (m) {
-                try {
-                    const parsed = JSON.parse(m[1]);
-                    return parsed.success
-                        ? { success: true, message: `Widget added to viewport with z-order ${zOrder}` }
-                        : { success: false, error: parsed.error };
-                }
-                catch { }
+            const interpreted = interpretStandardResult(resp, {
+                successMessage: `Widget added to viewport with z-order ${zOrder}`,
+                failureMessage: 'Failed to add widget to viewport'
+            });
+            if (interpreted.success) {
+                return { success: true, message: interpreted.message };
             }
-            return { success: true, message: 'Widget add to viewport attempted' };
+            return {
+                success: false,
+                error: interpreted.error ?? 'Failed to add widget to viewport',
+                details: bestEffortInterpretedText(interpreted)
+            };
         }
         catch (e) {
             return { success: false, error: `Failed to add widget to viewport: ${e}` };
@@ -229,9 +256,7 @@ except Exception as e:
                 commands.push(`AddMenuButton ${params.name} "${button.text}" ${button.action} ${pos.join(' ')}`);
             }
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: `Menu ${params.name} created` };
     }
     // Set widget animation
@@ -247,9 +272,7 @@ except Exception as e:
                 }
             }
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: `Animation ${params.animationName} created` };
     }
     // Play widget animation
@@ -277,9 +300,7 @@ except Exception as e:
         if (params.style.margin) {
             commands.push(`SetWidgetMargin ${params.widgetName}.${params.componentName} ${params.style.margin.join(' ')}`);
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: 'Widget style updated' };
     }
     // Bind widget event
@@ -297,9 +318,7 @@ except Exception as e:
         if (params.lockCursor !== undefined) {
             commands.push(`SetMouseLockMode ${params.lockCursor}`);
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: `Input mode set to ${params.mode}` };
     }
     // Create tooltip
@@ -320,9 +339,7 @@ except Exception as e:
                 commands.push(`AddDropTarget ${params.widgetName}.${params.componentName} ${target}`);
             }
         }
-        for (const cmd of commands) {
-            await this.bridge.executeConsoleCommand(cmd);
-        }
+        await this.bridge.executeConsoleCommands(commands);
         return { success: true, message: 'Drag and drop configured' };
     }
     // Create notification

package/dist/tools/visual.d.ts

@@ -2,6 +2,7 @@ import { UnrealBridge } from '../unreal-bridge.js';
 export declare class VisualTools {
     private bridge;
     private env;
+    private log;
     constructor(bridge: UnrealBridge);
     takeScreenshot(params: {
         resolution?: string;
@@ -9,12 +10,18 @@ export declare class VisualTools {
         success: boolean;
         message: string;
         imagePath?: undefined;
+        imageMimeType?: undefined;
+        imageSizeBytes?: undefined;
         imageBase64?: undefined;
+        imageBase64Truncated?: undefined;
         error?: undefined;
     } | {
         success: boolean;
         imagePath: string;
+        imageMimeType: string | undefined;
+        imageSizeBytes: number | undefined;
         imageBase64: string | undefined;
+        imageBase64Truncated: boolean;
         message?: undefined;
         error?: undefined;
     } | {
@@ -22,8 +29,12 @@ export declare class VisualTools {
         error: string;
         message?: undefined;
         imagePath?: undefined;
+        imageMimeType?: undefined;
+        imageSizeBytes?: undefined;
         imageBase64?: undefined;
+        imageBase64Truncated?: undefined;
     }>;
+    private getEngineScreenshotDirectories;
     private findLatestScreenshot;
 }
 //# sourceMappingURL=visual.d.ts.map

package/dist/tools/visual.js

@@ -1,67 +1,282 @@
 import { loadEnv } from '../types/env.js';
-import fs from 'fs';
+import { Logger } from '../utils/logger.js';
+import { coerceStringArray, interpretStandardResult } from '../utils/result-helpers.js';
+import { promises as fs } from 'fs';
 import path from 'path';
 export class VisualTools {
     bridge;
     env = loadEnv();
+    log = new Logger('VisualTools');
     constructor(bridge) {
         this.bridge = bridge;
     }
     // Take a screenshot of viewport (high res or standard). Returns path and base64 (truncated)
     async takeScreenshot(params) {
         const res = params.resolution && /^\d+x\d+$/i.test(params.resolution) ? params.resolution : '';
-        const cmd = res ? `HighResShot ${res}` : 'HighResShot';
+        const primaryCommand = res ? `HighResShot ${res}` : 'Shot';
+        const captureStartedAt = Date.now();
         try {
-            await this.bridge.executeConsoleCommand(cmd);
-            // Give the engine a moment to write the file
+            const firstAttempt = await this.bridge.executeConsoleCommand(primaryCommand);
+            const firstSummary = this.bridge.summarizeConsoleCommand(primaryCommand, firstAttempt);
+            if (!res) {
+                const output = (firstSummary.output || '').toLowerCase();
+                const badInput = output.includes('bad input') || output.includes('unrecognized command');
+                const hasErrorLine = firstSummary.logLines?.some(line => /error:/i.test(line));
+                if (badInput || hasErrorLine) {
+                    this.log.debug(`Screenshot primary command reported an error (${firstSummary.output || 'no output'})`);
+                }
+            }
+            // Give the engine a moment to write the file (UE can flush asynchronously)
             await new Promise(r => setTimeout(r, 1200));
-            const p = await this.findLatestScreenshot();
-            if (!p)
+            const p = await this.findLatestScreenshot(captureStartedAt);
+            if (!p) {
+                this.log.warn('Screenshot captured but output file was not found');
                 return { success: true, message: 'Screenshot triggered, but could not locate output file' };
+            }
             let b64;
+            let truncated = false;
+            let sizeBytes;
+            let mime;
             try {
-                const buf = fs.readFileSync(p);
-                // Limit to ~1MB to avoid huge responses
-                const max = 1024 * 1024;
-                b64 = buf.length > max ? buf.subarray(0, max).toString('base64') : buf.toString('base64');
+                const stat = await fs.stat(p);
+                sizeBytes = stat.size;
+                const max = 1024 * 1024; // 1 MiB cap for inline payloads
+                if (stat.size <= max) {
+                    const buf = await fs.readFile(p);
+                    b64 = buf.toString('base64');
+                }
+                else {
+                    truncated = true;
+                }
+                const ext = path.extname(p).toLowerCase();
+                if (ext === '.png')
+                    mime = 'image/png';
+                else if (ext === '.jpg' || ext === '.jpeg')
+                    mime = 'image/jpeg';
+                else if (ext === '.bmp')
+                    mime = 'image/bmp';
             }
             catch { }
-            return { success: true, imagePath: p, imageBase64: b64 };
+            return {
+                success: true,
+                imagePath: p.replace(/\\/g, '/'),
+                imageMimeType: mime,
+                imageSizeBytes: sizeBytes,
+                imageBase64: b64,
+                imageBase64Truncated: truncated
+            };
         }
         catch (err) {
             return { success: false, error: String(err?.message || err) };
         }
     }
-    async findLatestScreenshot() {
+    async getEngineScreenshotDirectories() {
+        const python = `
+import unreal
+import json
+import os
+
+result = {
+  "success": True,
+  "message": "",
+  "error": "",
+  "directories": [],
+  "warnings": [],
+  "details": []
+}
+
+def finalize():
+  data = dict(result)
+  if data.get("success"):
+    if not data.get("message"):
+      data["message"] = "Collected screenshot directories"
+    data.pop("error", None)
+  else:
+    if not data.get("error"):
+      data["error"] = data.get("message") or "Failed to collect screenshot directories"
+    if not data.get("message"):
+      data["message"] = data["error"]
+  if not data.get("warnings"):
+    data.pop("warnings", None)
+  if not data.get("details"):
+    data.pop("details", None)
+  if not data.get("directories"):
+    data.pop("directories", None)
+  return data
+
+def add_path(candidate, note=None):
+  if not candidate:
+    return
+  try:
+    abs_path = os.path.abspath(os.path.normpath(candidate))
+  except Exception as normalize_error:
+    result["warnings"].append(f"Failed to normalize path {candidate}: {normalize_error}")
+    return
+  if abs_path not in result["directories"]:
+    result["directories"].append(abs_path)
+    if note:
+      result["details"].append(f"{note}: {abs_path}")
+    else:
+      result["details"].append(f"Discovered screenshot directory: {abs_path}")
+
+try:
+  automation_dir = unreal.AutomationLibrary.get_screenshot_directory()
+  add_path(automation_dir, "Automation screenshot directory")
+except Exception as automation_error:
+  result["warnings"].append(f"Automation screenshot directory unavailable: {automation_error}")
+
+try:
+  project_saved = unreal.Paths.project_saved_dir()
+  add_path(project_saved, "Project Saved directory")
+  if project_saved:
+    add_path(os.path.join(project_saved, 'Screenshots'), "Project Saved screenshots")
+    add_path(os.path.join(project_saved, 'Screenshots', 'Windows'), "Project Saved Windows screenshots")
+    add_path(os.path.join(project_saved, 'Screenshots', 'WindowsEditor'), "Project Saved WindowsEditor screenshots")
+    try:
+      platform_name = unreal.SystemLibrary.get_platform_user_name()
+      if platform_name:
+        add_path(os.path.join(project_saved, 'Screenshots', platform_name), f"Project Saved screenshots for {platform_name}")
+        add_path(os.path.join(project_saved, 'Screenshots', f"{platform_name}Editor"), f"Project Saved editor screenshots for {platform_name}")
+    except Exception as platform_error:
+      result["warnings"].append(f"Failed to resolve platform-specific screenshot directories: {platform_error}")
+except Exception as saved_error:
+  result["warnings"].append(f"Project Saved directory unavailable: {saved_error}")
+
+try:
+  project_file = unreal.Paths.get_project_file_path()
+  if project_file:
+    project_dir = os.path.dirname(project_file)
+    add_path(os.path.join(project_dir, 'Saved', 'Screenshots'), "Project directory screenshots")
+    add_path(os.path.join(project_dir, 'Saved', 'Screenshots', 'Windows'), "Project directory Windows screenshots")
+    add_path(os.path.join(project_dir, 'Saved', 'Screenshots', 'WindowsEditor'), "Project directory WindowsEditor screenshots")
+except Exception as project_error:
+  result["warnings"].append(f"Project directory screenshots unavailable: {project_error}")
+
+if not result["directories"]:
+  result["warnings"].append("No screenshot directories discovered")
+
+print('RESULT:' + json.dumps(finalize()))
+`.trim()
+            .replace(/\r?\n/g, '\n');
+        try {
+            const response = await this.bridge.executePython(python);
+            const interpreted = interpretStandardResult(response, {
+                successMessage: 'Collected screenshot directories',
+                failureMessage: 'Failed to collect screenshot directories'
+            });
+            if (interpreted.details) {
+                for (const entry of interpreted.details) {
+                    this.log.debug(entry);
+                }
+            }
+            if (interpreted.warnings) {
+                for (const warning of interpreted.warnings) {
+                    this.log.debug(`Screenshot directory warning: ${warning}`);
+                }
+            }
+            const directories = coerceStringArray(interpreted.payload.directories);
+            if (directories?.length) {
+                return directories;
+            }
+            if (!interpreted.success && interpreted.error) {
+                this.log.warn(`Screenshot path probe failed: ${interpreted.error}`);
+            }
+            if (interpreted.rawText) {
+                try {
+                    const fallback = JSON.parse(interpreted.rawText);
+                    const fallbackDirs = coerceStringArray(fallback);
+                    if (fallbackDirs?.length) {
+                        return fallbackDirs;
+                    }
+                }
+                catch { }
+            }
+        }
+        catch (err) {
+            this.log.debug('Screenshot path probe failed', err);
+        }
+        return [];
+    }
+    async findLatestScreenshot(since) {
         // Try env override, otherwise look in common UE Saved/Screenshots folder under project
         const candidates = [];
+        const seen = new Set();
+        const addCandidate = (candidate) => {
+            if (!candidate)
+                return;
+            const normalized = path.isAbsolute(candidate)
+                ? path.normalize(candidate)
+                : path.resolve(candidate);
+            if (!seen.has(normalized)) {
+                seen.add(normalized);
+                candidates.push(normalized);
+            }
+        };
         if (this.env.UE_SCREENSHOT_DIR)
-            candidates.push(this.env.UE_SCREENSHOT_DIR);
+            addCandidate(this.env.UE_SCREENSHOT_DIR);
         if (this.env.UE_PROJECT_PATH) {
             const projectDir = path.dirname(this.env.UE_PROJECT_PATH);
-            candidates.push(path.join(projectDir, 'Saved', 'Screenshots'));
-            candidates.push(path.join(projectDir, 'Saved', 'Screenshots', 'Windows'));
-            candidates.push(path.join(projectDir, 'Saved', 'Screenshots', 'WindowsEditor'));
+            addCandidate(path.join(projectDir, 'Saved', 'Screenshots'));
+            addCandidate(path.join(projectDir, 'Saved', 'Screenshots', 'Windows'));
+            addCandidate(path.join(projectDir, 'Saved', 'Screenshots', 'WindowsEditor'));
         }
-        // Fallback: common locations
-        candidates.push(path.join(process.cwd(), 'Saved', 'Screenshots'));
-        candidates.push(path.join(process.cwd(), 'Saved', 'Screenshots', 'Windows'));
-        candidates.push(path.join(process.cwd(), 'Saved', 'Screenshots', 'WindowsEditor'));
-        let latest = null;
-        for (const c of candidates) {
+        const engineDirs = await this.getEngineScreenshotDirectories();
+        for (const dir of engineDirs) {
+            addCandidate(dir);
+        }
+        // Fallback: common locations relative to current working directory
+        addCandidate(path.join(process.cwd(), 'Saved', 'Screenshots'));
+        addCandidate(path.join(process.cwd(), 'Saved', 'Screenshots', 'Windows'));
+        addCandidate(path.join(process.cwd(), 'Saved', 'Screenshots', 'WindowsEditor'));
+        const searchDirs = new Set();
+        const queue = [...candidates];
+        while (queue.length) {
+            const candidate = queue.pop();
+            if (!candidate || searchDirs.has(candidate))
+                continue;
+            searchDirs.add(candidate);
             try {
-                const entries = fs.readdirSync(c).map(f => path.join(c, f));
-                for (const fp of entries) {
-                    if (!/\.png$/i.test(fp))
-                        continue;
-                    const st = fs.statSync(fp);
-                    if (!latest || st.mtimeMs > latest.mtime)
-                        latest = { path: fp, mtime: st.mtimeMs };
+                const entries = await fs.readdir(candidate, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        queue.push(path.join(candidate, entry.name));
+                    }
                 }
             }
             catch { }
         }
-        return latest?.path || null;
+        let latest = null;
+        let latestSince = null;
+        const cutoff = since ? since - 2000 : undefined; // allow slight clock drift
+        for (const dirPath of searchDirs) {
+            let entries;
+            try {
+                entries = await fs.readdir(dirPath);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const fp = path.join(dirPath, entry);
+                if (!/\.(png|jpg|jpeg|bmp)$/i.test(fp))
+                    continue;
+                try {
+                    const st = await fs.stat(fp);
+                    const info = { path: fp, mtime: st.mtimeMs };
+                    if (!latest || info.mtime > latest.mtime) {
+                        latest = info;
+                    }
+                    if (cutoff !== undefined && st.mtimeMs >= cutoff) {
+                        if (!latestSince || info.mtime > latestSince.mtime) {
+                            latestSince = info;
+                        }
+                    }
+                }
+                catch { }
+            }
+        }
+        const chosen = latestSince || latest;
+        return chosen?.path || null;
     }
 }
 //# sourceMappingURL=visual.js.map

package/dist/types/tool-types.d.ts

@@ -265,10 +265,4 @@ export interface ToolResponseMap {
 export type ToolName = keyof ToolResponseMap;
 export type GetToolResponse<T extends ToolName> = ToolResponseMap[T];
 export type GetToolParams<T extends keyof ConsolidatedToolParams> = ConsolidatedToolParams[T];
-export declare function isSuccessResponse(response: BaseToolResponse): response is BaseToolResponse & {
-    success: true;
-};
-export declare function isErrorResponse(response: BaseToolResponse): response is BaseToolResponse & {
-    error: string;
-};
 //# sourceMappingURL=tool-types.d.ts.map

package/dist/types/tool-types.js

@@ -2,12 +2,5 @@
  * Auto-generated TypeScript types from tool schemas
  * This provides type safety and IntelliSense support
  */
-// Export a type guard to check if a response is successful
-export function isSuccessResponse(response) {
-    return response.success === true;
-}
-// Export a type guard to check if a response has an error
-export function isErrorResponse(response) {
-    return response.success === false && typeof response.error === 'string';
-}
+export {};
 //# sourceMappingURL=tool-types.js.map