用途:在编辑 Unity 项目的 C# 脚本、场景或资源后,从 shell 驱动已运行的 Unity Editor 做编译验证、播放模式检查、场景状态与截图,避免手动点窗口或启动第二个编辑器进程。
主要能力:通过文件轮询命令桥工作——代理写入 <project>/UnityRemote.txt(每行一条命令,允许 # 注释),编辑器每 0.5 秒轮询并执行,结果写到 <project>/UnityRemote.result.txt,然后删除命令文件。编译/更新期间命令会被跳过,应等待而不是重发。提供 ping、refresh、play、state、stop、errors、screenshot、record、layout 等命令,完整命令与参数格式见 references/commands.md。
使用方式:先检测桥接脚本(检查 <project>/Assets/UnityRemote.cs,或 grep Assets/**/Editor/*.cs 看是否已有命令文件轮询器)。缺失时复制 assets/UnityRemote.cs(record 还需 assets/UnityRemoteRecorder.cs)到 Assets/,再执行 refresh 导入并编译;编辑器未聚焦会延迟资源导入,refresh 超时则先聚焦窗口再重试,并用 ping 确认。发送命令使用 scripts/unity_cmd.sh:单条 scripts/unity_cmd.sh <project-root> "ping",批量带超时 scripts/unity_cmd.sh <project-root> -t 600 "refresh" "ping"。
验证循环:代码改动后,运行 --compile(refresh → 忙等待空闲 → 控制台尾部,出现 'error CS' 为失败、'console empty' 为干净),再 play 进入播放模式、等待数秒、state 查看是否在播放及 MonoBehaviour 情况、errors 50 抓运行时异常,最后 stop。注意不能把 refresh+ping 当作编译门槛,refresh 会在重新编译开始前返回,同一批次的 ping/errors 来自旧程序集,应使用 --compile。
视觉验证:screenshot [relpath] 同步渲染主相机,输出 PNG 到 <project>/<relpath>,捕获 Game 相机而非编辑器界面;record [sec] [fps] 进入播放模式采帧,生成 Recordings/shot/frame_####.png 和 done.txt,需部署 UnityRemoteRecorder.cs。需要裁剪时可用 layout 获取窗口矩形与 pixelsPerPoint;操作系统级截屏不可靠,仅用于编辑器界面本身。errors 是播放模式向外输出的唯一数据通道,可让运行时代码输出结构化单行日志(如 Debug.Log($"GAME round={r} score={s}"))再检索,使用较大的 n(50+)以免早期条目滚出。
关键规则与限制:每个项目只能有一个编辑器,运行中的编辑器持有 Library 锁,切勿在同一项目上启动 -batchmode;播放模式会触发域重载、程序集重载、桥接重新初始化,须先确保 --compile 通过;桥接仅用于编辑器,不会随构建发布,按偏好提交或加入 .gitignore。遮挡注意事项、超时行为、域重载边界情况和故障排查见 references/caveats.md。