ET UnityBridge 实战指南用命令行让 AI 操作 Unity Editor 的全链路解析【免费下载链接】ETUnity3D Client And C# Server Framework项目地址: https://gitcode.com/GitHub_Trending/et/ET导读UnityBridge 是 ET 框架中连接「AI / 命令行工具」与「Unity Editor」的本地文件桥接模块它由一个纯 .NET 命令行程序ET.UnityBridge.dll和驻留在 Unity Editor 中的文件宿主组成让 Agent 无需点击 GUI 即可查询 Unity 编译/PlayMode 状态、操作资源与场景、执行编译热重载、运行 Editor 测试。本文以 SKILL.md 为骨架结合 CLI 参考、AI 操作参考 及源码实现完整讲解桥接原理、命令发现、任务路由、deferred 命令等待与错误排查读完即可在 ET 工程中驱动 AI 安全、省 Token 地操作 Unity。UnityBridge 是什么一个纯命令行的 Unity 操作入口UnityBridge 是 ET 的「Unity 本地文件桥接包」位于 Packages/cn.etetet.unitybridge由三部分构成见 AGENTS.md目录作用DotNet~纯命令行程序ET.UnityBridgeCLI 入口Scripts/EditorUnity Editor 侧的文件宿主、命令处理器与分发逻辑Scripts/Model/Share桥接命令、错误码、路径与文件存储协议它的核心价值在于AI 通过一行dotnet命令即可操作 Unity Editor覆盖资源、场景、选择集、GameObject、Transform、Inspector、Prefab、菜单、截图、GameView、Editor 测试等场景以及Compile/Refresh/RegenProject/EnterPlay/ExitPlay/Reload等会跨越 Unity 状态变化的命令并可直接排查桥接返回的Error/Message。桥接工作原理文件即协议UnityBridge 不依赖网络端口而是以本地目录作为请求/响应的「信箱」其路径解析与文件协议实现在 UnityBridgeStorage.cs桥接根目录解析优先级显式--root参数 环境变量ET_UNITY_BRIDGE_ROOT 默认Temp/UnityBridge见UnityBridgePathHelper.ResolveRoot。目录结构requests/待处理请求、processing/正在处理、responses/已写回的响应、deadletter/解析失败的死信、state/idempotency/幂等响应缓存、state/pending-command.jsondeferred 命令持久化状态。写入方式UnityBridgeFileStore.WriteTextAtomic采用「先写.tmp再改名」的原子替换避免半写文件被对端读到。Editor 侧宿主UnityBridgeEditorHostUnityBridgeEditorHost.cs以[InitializeOnLoad]挂载到EditorApplication.update每 0.2 秒轮询一次requests/目录取出请求 → 反序列化为命令 → 交给UnityBridgeEditorDispatcher分发 → 写回响应。因此整个链路是CLI 写请求文件 → Editor 轮询处理 → CLI 读到响应文件。何时使用与何时不要加载SKILL 文档明确划定了适用范围Agent 需要据此决定是否加载本技能应该使用查询宿主是否在线、Unity 是否在编译、PlayMode 状态、CodeMode、Unity 版本让 AI 操作 Unity Editor 的各类资源/场景/对象执行Compile/Refresh/RegenProject/EnterPlay/ExitPlay/Reload等跨状态命令排查桥接返回的Error/Message。不要加载只是普通 C# 编译应走et-build、只是读写 Excel 或导出 Luban、只是纯代码结构分析不需要 Unity 参与、只是要解释命令协议而不实际操作 Unity此时应只读 proto 或 handler不要启动 UnityBridge。快速上手最小流程1. 确认 CLI 可执行CLI 入口为dotnet ./Bin/ET.UnityBridge.dll默认桥接根目录优先读取环境变量ET_UNITY_BRIDGE_ROOT未设置时默认Temp/UnityBridge也可用--root 路径显式指定。若Bin/ET.UnityBridge.dll尚不存在先用et-build编译确认工具是否生成。构建产物路径由 ET.UnityBridge.csproj 的OutputPath决定Debug/Release 均输出到仓库根的Bin目录目标框架为net10.0。2. 发送第一个 Pingdotnet ./Bin/ET.UnityBridge.dll {_t:Ping}dotnet ./Bin/ET.UnityBridge.dll {_t:Ping} --root Temp/UnityBridgePing用来判断 UnityBridge 宿主是否在线、获取响应时间以及读取IsCompiling/IsPlaying/IsPlayingOrWillChangePlaymode/CodeMode/UnityVersion。对应的处理器实现在 UnityBridgePingHandler.cs其中IsCompiling/IsPlaying/IsPlayingOrWillChangePlaymode直接取自EditorApplicationUnityVersion取自Application.unityVersion。3. 需要命令列表时查询 HostStatedotnet ./Bin/ET.UnityBridge.dll {_t:HostState}HostState在Ping信息的基础上额外返回AvailableCommands由 UnityBridgeQueryHostStateHandler.cs 通过UnityBridgeEditorDispatcher.GetAvailableCommandTypes()汇总因此按任务选择最小命令执行失败时先看Error/Message再读对应 handler。命令发现不要整包读先 HostState 再 rg省 Token 的关键是「按需发现命令」先用HostState看当前可用命令需要字段格式时用rg只查对应 proto 小片段rg -n ^message .*Request|^message (Ping|HostState|Compile|Refresh|RegenProject|EnterPlay|ExitPlay|Reload)\b ./Packages/cn.etetet.unitybridge/Proto需要行为细节时再查 handlerrg -n class UnityBridge.*Handler|AUnityBridgeDeferredHandler ./Packages/cn.etetet.unitybridge/Scripts/Editor/Share协议定义集中在 UnityBridge_C_11100.proto基础命令与对象/资产/场景消息与同目录的UnityBridge_C_11400.proto其余命令族。例如Ping/PingResponse的结构Error、Message、Time、IsCompiling、IsPlaying、CodeMode、UnityVersion等字段与HostStateResponse.AvailableCommands、UnityTestRunResponse.Matched/Passed/Failed、AssetFindResponse.TotalFound/Returned等均可从 proto 中直接确认。任务路由先读状态再执行动作来自 et-unitybridge-ai-ops.md 的完整任务路由表是 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先单步验证以资源查询为例先小范围查、不要全项目大结果dotnet ./Bin/ET.UnityBridge.dll {_t:AssetFindRequest,Filter:t:Prefab,MaxResults:10}AssetFindRequest的Filter如t:Prefab、SearchInFolders、MaxResults、Format字段定义见 proto其路径归一化与返回逻辑可查UnityBridgeAssetFindHandler.cs。场景对象操作则先读层级dotnet ./Bin/ET.UnityBridge.dll {_t:SceneGetHierarchyRequest,Depth:2,IncludeInactive:false}写操作后用GameObjectGetInfoRequest或TransformGetRequest验证不要只相信命令成功。改 Inspector 时先读组件与属性名再使用 set 命令不要猜测SerializedProperty路径dotnet ./Bin/ET.UnityBridge.dll {_t:InspectorGetComponentsRequest,Path:HierarchyPath}常用命令与传输参数来自 et-unitybridge-cli.md 的常用命令一览dotnet ./Bin/ET.UnityBridge.dll {_t:Ping} dotnet ./Bin/ET.UnityBridge.dll {_t:HostState} dotnet ./Bin/ET.UnityBridge.dll {_t:Compile} dotnet ./Bin/ET.UnityBridge.dll {_t:Refresh} dotnet ./Bin/ET.UnityBridge.dll {_t:RegenProject} dotnet ./Bin/ET.UnityBridge.dll {_t:EnterPlay} dotnet ./Bin/ET.UnityBridge.dll {_t:ExitPlay} dotnet ./Bin/ET.UnityBridge.dll {_t:Reload}支持的传输参数由 Program.cs 中的TransportOptions解析参数说明默认值--root 路径显式指定桥接根目录环境变量ET_UNITY_BRIDGE_ROOT否则Temp/UnityBridge--waitMs 毫秒CLI 等待最终响应的最大时长15000DefaultWaitMs--timeoutMs 毫秒请求在 Editor 侧的超时0时按命令类型取默认0由宿主按命令回退--idempotencyKey 字符串幂等键重复请求命中缓存直接返回上次响应未提供时自动生成 GUID其中--timeoutMs的「按命令回退」逻辑在 UnityBridgeEditorHost.cs 的ResolveTimeoutMs中Compile为 180000msRefresh/RegenProject/EnterPlay/ExitPlay为 60000ms其余命令为 10000ms。CLI 侧还内置了 deferred 自动延长机制未显式指定--waitMs时若检测到pending-command.json中存在本请求的 RpcId等待期限会自动延长至DefaultDeferredWaitMs 185000确保Compile等长耗时命令能拿到最终响应。带完整参数的示例dotnet ./Bin/ET.UnityBridge.dll {_t:HostState} --root Temp/UnityBridge --waitMs 15000 --timeoutMs 10000 --idempotencyKey host-state-checkdeferred 命令必须等到最终响应Compile、Refresh、RegenProject、EnterPlay、ExitPlay、AssetImportRequest、AssetRefreshRequest等是deferred延迟命令——它们会先返回「请求已接收」真正的工作在 Unity 主循环中分帧完成。因此必须等待最终响应不要看到请求已接收就结束。其底层机制在 AUnityBridgeDeferredHandler.csdeferred handler 在首次执行时抛出UnityBridgeDeferredStartedException并返回 deferred 响应Editor 侧通过UnityBridgeDeferredRuntime.TryPump在EditorApplication.update中持续恢复执行Run(command, UnityBridgeDeferredContext.CreateResume(startedAt))直到产出最终响应或抛出UnityBridgeCommandStateException此时返回对应错误码。以Refresh为例UnityBridgeRefreshHandler.cs 会等条件满足后执行AssetDatabase.Refresh(ImportAssetOptions.ForceUpdate)再deferred.StartedRefreshResponse()。推荐的执行顺序编译前HostState - Compile刷新前HostState - Refresh重建工程文件HostState - RegenProject进播放前确认IsCompiling false且IsPlayingOrWillChangePlaymode false再EnterPlay热重载前确认IsPlaying true再Reload退播放前HostState - ExitPlay。实时等待的正确姿势先执行Ping或HostState若IsCompiling true持续轮询直到编译结束再发Compile/EnterPlay/Reload/ExitPlay等正式命令deferred 命令必须读取最终响应。响应解读Error 为 0 才是成功Error 0表示成功非 0 表示失败结合Message判断原因。CompileResponse额外包含DurationMs编译耗时。EnterPlayResponse/ExitPlayResponse额外包含IsPlaying。PingResponse额外包含Time、IsCompiling、IsPlaying、IsPlayingOrWillChangePlaymode、CodeMode、UnityVersion。HostStateResponse额外包含AvailableCommands。向用户汇报时只总结Error、Message和关键字段不要把完整 JSON 响应贴给用户。写操作后说明如何验证必要时直接执行验证命令。跑 Editor 测试使用精确正则避免全量跑dotnet ./Bin/ET.UnityBridge.dll {_t:UnityTestRunRequest,Name:^Unitybridge_DeferredHandlerRunContext_Test$}判定Error 0、Matched 0、Failed 0。其实现见 UnityBridgeUnityTestRunHandler.cs通过TestDispatcher按正则匹配ET.Core/ET.Loader/ET.Model/ET.ModelView/ET.Editor/ET.Hotfix/ET.HotfixView程序集中的测试用例并逐条执行最终汇总Matched/Passed/Failed与总耗时。仓库中同名测试如Unitybridge_DeferredHandlerRunContext_Test.cs即用于验证 deferred 运行上下文。常见错误与排查CLI 与参考文档列出的高频错误及其含义wait unity bridge response timeoutUnity 未打开、项目未加载完、桥接根目录不一致或 Editor 未处理请求。排查顺序先检查 Unity 是否已打开项目、心跳文件是否存在、桥接根目录是否一致。unity is compilingUnity 正在编译暂时不能开始新的延迟命令。先轮询Ping等IsCompiling false后重试。unity already in playmode or changing playmode不能再次执行EnterPlay。unity not in playmode执行ExitPlay或Reload的前置条件不满足。handler is missing先HostState确认可用命令再查 proto 名是否写错。execute menu item failed菜单路径不存在或 Unity 当前状态不允许执行。对应的错误码定义集中在 ErrorCode.csSuccess 0并区分Timeout、NotInPlayMode、AlreadyInPlayMode、Compiling、HandlerFail、InvalidCommandLine等便于程序化处理。省 Token 操作守则SKILL 与两份参考文档反复强调的 AI 操作纪律值得作为长期协作约定不要完整读取所有 UnityBridge proto、handler 或AvailableCommands先用HostState或rg发现命令名再只打开相关 proto 小片段和对应 handler先执行最小读命令确认目标再做写操作批量操作前先验证 1 个样本BatchExecuteRequest先单步验证不要把完整 JSON 响应贴给用户只总结Error、Message和关键字段优先 UnityBridge 命令不要用 GUI 点击 Unity Editor除非命令缺失或用户明确要求如果 UnityBridge 不可用说明原因和下一步不回退到 GUI 点击。小结UnityBridge 以「文件即协议」的本地桥接设计为 ET 工程提供了稳定、可脚本化、对 AI 友好的 Unity 操作入口。掌握「HostState 发现命令 → 最小读命令确认 → deferred 命令等待最终响应 → 按 Error/Message 排查」这条主线即可让 AI 在零 GUI 依赖的前提下完成从编译热重载到场景搭建、从 Inspector 调参到 Editor 测试的全流程自动化操作。进一步深入可阅读 SKILL.md、CLI 参考、AI 操作参考以及 Proto 协议 和 Editor 宿主实现。【免费下载链接】ETUnity3D Client And C# Server Framework项目地址: https://gitcode.com/GitHub_Trending/et/ET创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考