Skip to content

UEMCP v0.1.5

Choose a tag to compare

@KyuuKyuuStone KyuuKyuuStone released this 03 Nov 08:58

中文

本版集中修复业务团队《UEMCP v0.1.4 复测缺陷单》确认的四条缺陷(D1–D4),不需要使用者改任何自己的代码:换上新插件包 + 新 server 包、重启编辑器即可。D5(screen-space UWidget 截图)经复核为引擎合成层边界,窗口截屏模式排入 0.1.6。

下载(Downloads)

  • UEMCPBridge-5.4.zip — Unreal Engine 5.4 插件包(实测 5.4.4)
  • UEMCPBridge-5.7.zip — Unreal Engine 5.7 插件包(实测 5.7.4)
  • uemcp-server-0.1.5.tgz — MCP Server 离线包(Node ≥ 20,未发布到 npm registry)
  • SHA256SUMS.txt — 三个产物的 SHA-256 校验和(大小以 SHA256SUMS.txt 旁文件为准)

修复(Fixed,逐条对应缺陷单编号)

  • D1:ue_viewport_capture 的 activateWindow 参数现在由 MCP 层原样透传到 Bridge(v0.1.4 的 Server schema 不认这个参数,会报 INVALID_ARGUMENT: Unrecognized key,只有直连 Bridge 18778/rpc 才能用)。开启后置前并校验前台,成功返回带 activation{requested, ok, editorPid, foregroundPid, hwnd, isIconic, alreadyForeground};失败仍立即 EDITOR_UNSAFE_STATE(reason=window_not_foreground,details 带 editorPid/foregroundPid/hwnd/isIconic/hint),不干等超时。注意 activateWindow 默认 false(不传则不置前、不校验)。
  • D2:ue_log_query 的级别判定兼容 UE 的隐式 LogXxx: 行:显式 : Error: / : Warning: / : Display: / : Verbose: 段优先;否则 Log+首字母大写类别名(如 LogMarker:)视为 Log;都不匹配则 level=null 且不计入 levels 过滤,返回带 unclassified 计数。v0.1.4 中 levels:["Log"] 会静默漏掉全部隐式 LogXxx: 行("matched 0" 误判为没发生)。
  • D3:ue_reflect 的 target 支持裸类名短名解析(如 CustomDomainCmdHandler,含工程模块类):走派生类搜索 / 世界内实例搜索,不再必须写全路径(v0.1.4 只吃 /Script/… 全路径,裸类名直接 NOT_FOUND);解析失败时错误 details 返回 candidates 候选全路径,照抄即可。
  • D4:ue_call_function 新增 captureLog:true(调用窗口日志旁路):调用期间在窗口内捕获日志,返回 logLines[{lineNo, level, text}]——void 函数不再只能拿到 {"returned":null,"returnedVoid":true},业务结果(如 handler 打的 JSON 日志行)可直接随调用读回。

已知限制(Known limitations)

  • 窗口截屏模式(method:"window")尚未提供,已排入 0.1.6:ue_viewport_capture 目前只能截引擎渲染的视口画面。
  • UE 侧 screen-space UWidgetComponent 不进 hires 截图(缺陷单 D5 复核结论):这类 widget 属 Slate 合成层,由 UI pass 叠加在 scene renderer 输出之后,take_high_res_screenshot 拿不到——这是引擎渲染管线行为,不是插件缺陷。需要带标记的画面时,请先用外部窗口截屏(Win32 PrintWindow/桌面截图)对照验收,窗口截屏模式 0.1.6 提供。
  • object.call 的函数名黑名单按子串拦截 python / exec / eval / subprocess:名字里含这些子串的正常业务函数会被误拦(安全优先于便利)。函数命名请避开这些词;被拦时的错误信息会写明命中了黑名单。

升级提示(Upgrade notes)

  • 从 v0.1.4 升级:整目录覆盖插件 + npm install -g uemcp-server-0.1.5.tgz,重启编辑器;用 /health 的 pluginVersion=0.1.5、buildHash 变化、sourcePath 指向当前工程 Plugins/UEMCPBridge 三项确认升级生效。
  • 备份旧版时把 .uplugin 一并改名(如 UEMCPBridge.uplugin.bak)或移出 Plugins/,否则备份会顶掉新版(second location will be ignored)。
  • 验收 activateWindow 前先确认 server 包确为 0.1.5:调用带 "activateWindow": true 若报 Unrecognized key,说明包未含 D1 修复,请回传完整错误 JSON。

English

This release fixes the four defects (D1–D4) confirmed in the business team's v0.1.4 defect report. No changes are required on your side: swap in the new plugin and server packages and restart the editor. D5 (screen-space UWidget capture) was re-verified as an engine compositing boundary; a window-capture mode is scheduled for 0.1.6.

Downloads

  • UEMCPBridge-5.4.zip — Unreal Engine 5.4 plugin (tested 5.4.4)
  • UEMCPBridge-5.7.zip — Unreal Engine 5.7 plugin (tested 5.7.4)
  • uemcp-server-0.1.5.tgz — offline MCP server bundle (Node ≥ 20; not published to npm)
  • SHA256SUMS.txt — SHA-256 checksums for all three (file sizes are whatever the sums file accompanies)

Fixed (per defect-report IDs)

  • D1: ue_viewport_capture now passes activateWindow through the MCP layer to the bridge (the 0.1.4 server schema rejected the key with INVALID_ARGUMENT: Unrecognized key, so it only worked when calling the bridge port 18778/rpc directly). When enabled, the window is restored and the foreground state verified; success returns activation{requested, ok, editorPid, foregroundPid, hwnd, isIconic, alreadyForeground}, failure returns immediately with EDITOR_UNSAFE_STATE (reason=window_not_foreground, details carry editorPid/foregroundPid/hwnd/isIconic/hint). Note activateWindow defaults to false (no activation/verification unless requested).
  • D2: ue_log_query level inference now recognises UE's implicit LogXxx: lines: explicit : Error: / : Warning: / : Display: / : Verbose: segments win; otherwise Log + a capitalised category (e.g. LogMarker:) counts as Log; anything else keeps level=null, is excluded from levels filtering, and is reported via an unclassified count. In 0.1.4, levels:["Log"] silently missed every implicit LogXxx: line ("matched 0" was read as "never happened").
  • D3: ue_reflect target accepts bare class names (e.g. CustomDomainCmdHandler, including project-module classes) via derived-class search / in-world instance search — a full /Script/… path is no longer required (0.1.4 returned NOT_FOUND for bare names); on failure the error details carry candidates with the resolved full paths.
  • D4: ue_call_function accepts captureLog:true (in-call log bypass): log lines captured inside the call window are returned as logLines[{lineNo, level, text}] — a void function no longer leaves the caller with only {"returned":null,"returnedVoid":true}; business results logged by your handler come back with the call itself.

Known limitations

  • The window-capture mode (method:"window") is not provided yet — scheduled for 0.1.6; ue_viewport_capture currently captures only the engine-rendered viewport.
  • Screen-space UWidgetComponent on the UE side does not appear in hires screenshots (D5 re-verification): such widgets live in the Slate compositing layer, applied after the scene renderer output, so take_high_res_screenshot cannot include them — an engine rendering-pipeline behaviour, not a plugin defect. For frames that must show the markers, use an external window screenshot (Win32 PrintWindow/desktop capture) until the 0.1.6 window-capture mode ships.
  • object.call name blacklist matches by substring on python / exec / eval / subprocess: legitimate business functions whose names contain these substrings are blocked (safety over convenience). Avoid these substrings when naming functions; the error message names the matched blacklist term.

Upgrade notes

  • From v0.1.4: overwrite the plugin directory and npm install -g uemcp-server-0.1.5.tgz, restart the editor; confirm via /health — pluginVersion=0.1.5, a changed buildHash, and sourcePath pointing at the project's Plugins/UEMCPBridge.
  • When backing up the old version, rename its .uplugin (e.g. UEMCPBridge.uplugin.bak) or move it out of Plugins/, otherwise the backup shadows the new build (second location will be ignored).
  • Before acceptance-testing activateWindow, make sure the server package is really 0.1.5: if a call with "activateWindow": true fails with Unrecognized key, the package predates the D1 fix — please send back the full error JSON.