
ET UnityBridge AI 操作指南通过 CLI 让 AI 自动化操作 Unity Editor【免费下载链接】ETUnity3D Client And C# Server Framework项目地址: https://gitcode.com/GitHub_Trending/et/ET本篇指南以 ET 框架的cn.etetet.unitybridge包内 AI 操作参考文档为核心系统讲解如何通过ET.UnityBridge.dll命令行桥接层让 AI或任何自动化脚本在 Unity Editor 中完成状态查询、编译刷新、PlayMode 切换、资源/场景/对象操作、Inspector 修改与 Editor 测试执行。读完本文你将掌握 UnityBridge 的命令入口、命令发现方法、任务路由表、deferred 命令等待语义与常见错误处理能够以先读状态、再执行动作的安全姿势驱动 Unity Editor 完成自动化操作。UnityBridge 是什么AI 操作 Unity Editor 的桥接层在 ET 框架中cn.etetet.unitybridge包为 AI 提供了一条不依赖 GUI 点击、完全通过命令行协议操作 Unity Editor 的通道。核心思路是宿主进程Unity Editor 内运行的桥接代码持续监听请求文件外部进程通过dotnet ./Bin/ET.UnityBridge.dll以 JSON 命令形式写入请求、读取响应命令以 proto 消息定义见 Proto/UnityBridge_C_11100.proto响应统一携带Error/Message字段用于判定成败。该文档的定位非常明确只在需要实际操作 Unity 时读取不要把它当完整命令手册。因此本文同样聚焦任务路由 操作模式 错误处理这条实操主线命令字段细节则指向 proto 与 handler 源码。核心原则先读后写最小化操作AI 通过 UnityBridge 操作 Unity Editor 时必须遵守以下纪律文档原文要求也是源码设计的直接映射所有命令通过pwsh执行CLI 入口统一为dotnet ./Bin/ET.UnityBridge.dll先读状态再执行动作任何写操作之前先用Ping/HostState确认编译与 PlayMode 状态先用最小读命令确认目标再执行写命令例如改 Transform 前先Find/GetInfo/Get改 Inspector 前先读组件与属性名只读取相关 proto / handler 小片段不要全量加载命令定义按需用rg精准命中deferred 命令要等最终响应看到pending/deferred中间状态不代表命令成功必须等待最终响应。这些原则的底层依据可以在 Program.cs 中看到CLI 默认等待DefaultWaitMs 15000一旦检测到请求进入 deferred 状态会自动把截止时间延长到DefaultDeferredWaitMs 185000约 3 分钟并持续轮询直到读到最终响应或超时——这正是必须等最终响应的机制保障。入口与连通性检查Ping 与 HostState所有操作的第一步是确认 UnityBridge 宿主在线。文档给出的两个最小入口命令dotnet ./Bin/ET.UnityBridge.dll {_t:Ping}dotnet ./Bin/ET.UnityBridge.dll {_t:HostState}两者的职责分工命令用途关键返回字段Ping判断 UnityBridge 是否在线读取编译 / PlayMode / CodeMode / Unity 版本Time、IsCompiling、IsPlaying、IsPlayingOrWillChangePlaymode、CodeMode、UnityVersionHostState在Ping基础上额外获取AvailableCommands当前可用的全部命令列表上述字段 AvailableCommands从源码看Ping的实现UnityBridgePingHandler.cs直接映射 UnityEditor APIIsCompiling EditorApplication.isCompiling、IsPlaying EditorApplication.isPlaying、IsPlayingOrWillChangePlaymode EditorApplication.isPlayingOrWillChangePlaymode、UnityVersion Application.unityVersion。HostState在 UnityBridgeQueryHostStateHandler.cs 中实现其中AvailableCommands由UnityBridgeEditorDispatcher.GetAvailableCommandTypes()汇总生成。注意如果Bin/ET.UnityBridge.dll尚不存在需要先用et-build编译生成工具再进行连通性检查。命令发现按需定位不做全量枚举UnityBridge 的命令很多资源、场景、选择集、GameObject、Transform、Inspector、Prefab、GameView、截图、测试、批量等文档明确要求按需发现、按需读取需要命令列表时优先看HostState的AvailableCommands字段需要字段格式时用正则精准搜索 protorg -n ^message .*Request|^message (Ping|HostState|Compile|Refresh|RegenProject|EnterPlay|ExitPlay|Reload)\b ./Packages/cn.etetet.unitybridge/Proto需要行为细节时搜索 handler 定义rg -n class UnityBridge.*Handler|AUnityBridgeDeferredHandler ./Packages/cn.etetet.unitybridge/Scripts/Editor/Share命中之后只打开命中的单个 proto 或 handler不要整包读取。这种先定位、后精读的模式在省 token 的同时也避免了被无关命令干扰。任务路由总览按目标选命令族文档给出了一张核心任务路由表是 AI 操作 Unity 的导航地图。下面完整继承并补充说明目标优先命令族常见前置状态/连通性Ping,HostState,EditorGetStateRequest无编译/刷新Compile,Refresh,RegenProject,AssetRefreshRequest,AssetImportRequestIsCompiling falsePlayMode/热重载EnterPlay,ExitPlay,Reload,EditorPauseRequest检查IsPlaying/IsPlayingOrWillChangePlaymode资源AssetSearchRequest,AssetFindRequest,AssetLoadRequest,AssetReadTextRequest,AssetGetPathRequest先限定 filter/path/count场景SceneGetHierarchyRequest,SceneGetActiveRequest,SceneLoadRequest,SceneSaveRequest,SceneNewRequest写操作前确认当前场景选择集SelectionGetRequest,SelectionSetRequest,SelectionAddRequest,SelectionRemoveRequest,SelectionClearRequest先读当前 selection对象/TransformGameObject*Request,Transform*Request先Find/GetInfo/GetInspectorInspectorGet*Request,InspectorSet*Request,InspectorAddComponentRequest,InspectorRemoveComponentRequest先读组件和属性名PrefabPrefabInstantiateRequest,PrefabSaveRequest,PrefabApplyRequest,PrefabGet*Request,PrefabUnpackRequest先确认 asset path / instance截图/GameViewScreenshotCaptureRequest,GameView*Request先读分辨率测试UnityTestRunRequest用精确正则批量BatchExecuteRequest先单步验证这些命令族均能在 Scripts/Editor/Share 目录下找到一一对应的 handler 实现如UnityBridgeAssetFindHandler.cs、UnityBridgeSceneGetHierarchyHandler.cs、UnityBridgeInspectorGetComponentsHandler.cs、UnityBridgePrefabInstantiateHandler.cs、UnityBridgeScreenshotCaptureHandler.cs、UnityBridgeUnityTestRunHandler.cs、UnityBridgeBatchExecuteHandler.cs等且每个 handler 都配套了完整的协议测试见 Scripts/Editor/Test 目录例如Unitybridge_DeferredHandlerRunContext_Test.cs、Unitybridge_AssetFindHandler_Test.cs可作为行为细节的权威参考。操作模式详解读状态只看关键字段dotnet ./Bin/ET.UnityBridge.dll {_t:HostState}只总结关键字段Error、Message、IsCompiling、IsPlaying、IsPlayingOrWillChangePlaymode以及需要的命令是否存在。不要把完整 JSON 响应贴给用户。执行 deferred 命令等待最终响应dotnet ./Bin/ET.UnityBridge.dll {_t:Refresh}Compile、Refresh、RegenProject、EnterPlay、ExitPlay、Reload、AssetImportRequest、AssetRefreshRequest等都属于 deferred 命令CLI 会等待最终响应。若返回unity is compiling先轮询Ping等IsCompiling false后重试。deferred 的语义在 AUnityBridgeDeferredHandler.cs 中有清晰实现处理器先通过UnityBridgeDeferredRuntime.TryCreatePendingCurrent创建 pending 状态随后Run抛出UnityBridgeDeferredStartedException返回CreateDeferredResponse()等 Unity 状态就绪后由运行时以UnityBridgeDeferredContext.CreateResume(startedAt)续跑若条件未满足如仍在编译则抛UnityBridgeDeferredNotReadyException返回 nullCLI 侧继续轮询。这就是看到 pending/deferred 不能结束的原因——pending 只是操作挂起不是最终结果。查资源小范围优先dotnet ./Bin/ET.UnityBridge.dll {_t:AssetFindRequest,Filter:t:Prefab,MaxResults:10}先用小范围查询限定Filter/SearchInFolders/MaxResults避免全项目大结果。需要字段格式时查对应 proto需要路径归一化或返回逻辑时查UnityBridgeAsset*Handler.cs。从 proto 可以看到AssetFindRequest支持Filter、SearchInFolders、MaxResults、Format响应中TotalFound/Returned分别表示命中总数与实际返回数。操作场景对象先读层级再改改后验证dotnet ./Bin/ET.UnityBridge.dll {_t:SceneGetHierarchyRequest,Depth:2,IncludeInactive:false}先读层级或查对象再执行修改。SceneGetHierarchyRequest的Depth控制递归深度、IncludeInactive控制是否包含未激活对象。写操作后用GameObjectGetInfoRequest或TransformGetRequest验证不要只相信命令成功——这是文档反复强调的验证闭环。改 Inspector不要猜 SerializedProperty 路径dotnet ./Bin/ET.UnityBridge.dll {_t:InspectorGetComponentsRequest,Path:HierarchyPath}先读组件列表再读属性名和类型InspectorGetPropertiesRequest/InspectorGetPropertyRequest最后使用 set 命令InspectorSetPropertyRequest/InspectorSetPropertiesRequest。proto 中的BridgePropertyInfo携带Name、Type、PropertyPath、IsEditable、IsArray等字段InspectorFindPropertyRequest则用于按名字定位属性路径避免凭空猜测序列化路径。跑 Editor 测试用精确正则dotnet ./Bin/ET.UnityBridge.dll {_t:UnityTestRunRequest,Name:^Unitybridge_DeferredHandlerRunContext_Test$}判定标准Error 0、Matched 0、Failed 0。用精确正则锚定测试名^...$避免全量跑测试。UnityTestRunRequest响应中的Matched/Passed/Failed/DurationMs以及Results逐条BridgeTestResult可用于细粒度判定。常见错误处理速查文档给出了完整的错误对照表这里逐条继承并补充原因说明错误信息含义与处理wait unity bridge response timeoutUnity 未打开、项目未加载、桥接根目录不一致或 Editor 未处理请求。先检查 Unity 是否已打开项目、心跳文件是否存在、--root是否与宿主一致unity is compilingUnity 正在编译暂时不能开始新的 deferred 命令。等待编译结束IsCompiling false再发写命令unity already in playmode or changing playmode不要重复EnterPlay当前已在播放或正在切换播放模式unity not in playmodeReload/ExitPlay的前置条件不满足Reload要求IsPlaying trueExitPlay同样要求处于播放状态handler is missing先HostState确认可用命令列表再核对 proto 中的命令名是否写错注意大小写与_t字段execute menu item failed菜单路径不存在或当前 Unity 状态不允许执行该菜单项输出要求与行为规范文档对 AI 的汇报方式也做了明确约束向用户汇报目标、命令、关键结果不贴完整大 JSON省 token 且聚焦写操作后说明如何验证必要时直接执行验证命令如GameObjectGetInfoRequest/TransformGetRequest如果 UnityBridge 不可用说明原因和下一步不回退到 GUI 点击除非用户明确确认。从包级技能定义SKILL.md还可以看到配套的边界约束普通 C# 编译应走et-build、Excel/Luban 导出不应走 UnityBridge、纯代码结构分析也不需要启动桥接——UnityBridge 只服务于需要 Unity 编辑器参与的操作。从参考到实战完整操作流程示例综合上述内容一次典型的 AI 操作 Unity 的完整流程是连通性Ping确认宿主在线读取IsCompiling/IsPlaying/CodeMode/UnityVersion命令确认需要命令列表时发HostState从AvailableCommands中确认目标命令存在前置状态写操作前确认IsCompiling falsePlayMode 类操作再确认IsPlaying/IsPlayingOrWillChangePlaymode最小读用最小读命令确认目标查资源限定 filter/count、改场景先读层级、改 Inspector 先读组件与属性执行写命令发出 deferred 写命令并等待最终响应CLI 会自动延长等待到约 3 分钟验证用读命令验证写操作结果而不是只相信命令成功返回汇报向用户总结目标、命令与关键结果附上验证说明。这套流程既能保证操作的安全性先读后写、状态前置校验又能借助 Program.cs 中的轮询与自动等待机制可靠地拿到 deferred 命令的最终结果。配合 Proto/UnityBridge_C_11100.proto 中的字段定义与 Scripts/Editor/Share 下的 handler 实现任何自动化脚本或 AI Agent 都能按图索骥以确定性的方式完成 Unity Editor 的批量操作、自动化验证与回归测试。【免费下载链接】ETUnity3D Client And C# Server Framework项目地址: https://gitcode.com/GitHub_Trending/et/ET创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考