uloop-control-play-mode

uloop control-play-mode

控制 Unity Editor 的播放模式（播放／停止／暂停／逐帧），或在不产生副作用的情况下查询状态（status）。

用法

uloop control-play-mode [options]

参数

参数	类型	默认值	描述
--action	string	Play	Play - 启动播放模式，Stop - 停止播放模式，Pause - 暂停播放模式，Step - 在暂停时前进一帧，Status - 报告当前状态，不做任何更改，Resume - 在任何状态下都等同于 Play，包括在停止时启动播放模式
--timeout-seconds	integer	180	等待所请求播放模式状态的最长秒数

输出

返回包含当前播放模式状态的 JSON：

• IsPlaying：Unity 当前是否处于播放模式
• IsPaused：播放模式是否已暂停
• Changed：所请求的操作是否更改了当前播放模式状态
• WasAlreadyStopped：请求 Stop 时播放模式是否已经停止
• ResumedFromPause：Play 是否恢复了已暂停的播放模式会话，而非启动新会话
• Message：所执行操作的描述
• Warning（string，可选）：当操作带有限制说明时设置。全新的 Play 启动始终会注明会话从编辑时场景状态启动；此外，当存在活动的热重载补丁或启用的暂停点，且启用了 Domain Reload 时，会报告进入 Play 模式的域重载将丢弃其中多少项。启用 --persist 的暂停点会单独计数：它们会在重载后重新启用，警告会指向 pause-point-status，以查看重新启用结果。当 Unity Editor 未处于焦点状态而播放模式仍在运行时，Status 也会报告这一情况，因为运行进度可能会受到限制；请运行 uloop focus-window，或者使用 pause-point --await／--trigger 流程，而不是轮询进度。
• StoppedBy（string，可选）：播放模式上次停止的原因：cli-control-play-mode、cli-compile-stop-setting、cli-run-tests-cancel、script-compilation 或 unknown。当播放模式已停止时的 Stop 操作，以及播放模式未运行时的 Status 操作会包含此字段。此 Editor 会话中没有已确认的停止记录时省略。
• StoppedAt（string，可选）：该次停止的 UTC ISO 8601 时间戳。没有停止记录时，与 StoppedBy 一同省略。

注意事项

• 对已停止的 Editor 执行 Stop 会设置 Changed: false、WasAlreadyStopped: true
• 对已在播放的 Editor 执行 Play 不会产生任何操作：它会设置 Changed: false，并保留当前会话（包括累积状态、生成的对象和进度），而不是重新启动会话。如果需要干净的状态进行验证，请明确先执行 Stop 再执行 Play，不要指望仅执行 Play 就能重置任何内容。
• 在 Play Mode 暂停时执行 Play 会恢复同一会话：它会设置 Changed: true、ResumedFromPause: true 和 Message: "Play mode resumed"——会话不会重新启动。
• Resume 是 Play 的别名，在所有状态下行为都相同，包括在停止时启动 Play Mode。
• Step 恰好前进一帧，并使 PlayMode 保持暂停（即 Editor 的 Next Frame 按钮）；它独立于 Time.timeScale，并且要求 PlayMode 正在运行
• 命令会等待到达所请求的状态后再返回。对于进入 PlayMode 较慢的项目，请增大 --timeout-seconds。
• 在将 PlayMode 行为作为验证依据前，请检查 uloop get-logs --log-type Error 中是否存在之前的错误。否则，PlayMode 启动时已存在的错误可能会被误认为是由正在测试的操作导致的。
• Status 会读取当前状态，不产生副作用：Changed 始终为 false，不会等待或保存场景，也不会因编译错误而被拒绝。它会报告编译错误当前是否会阻止 Play（通过 BlockedByCompileErrors 和 CompileErrors 列表），数据读取自上一次编译结果，不会触发新的编译。它不会预测未保存更改导致的阻塞：BlockedByUnsavedChanges 描述的是 Play 请求期间保存失败的情况，而 Status 从不尝试保存。
• 如果无法静默保存未保存的更改，Play 会立即失败并返回 CONTROL_PLAY_MODE_UNSAVED_CHANGES 错误——最常见的情况是 Untitled 场景，因为它没有可保存到的路径。错误消息会准确列出阻止操作的场景或预制件阶段；请将 Untitled 场景保存到明确指定的路径（或放弃更改），然后重试。
• 从 Edit mode 执行 Play 会触发域重载（除非 Enter Play Mode Options 禁用了域重载），这会丢弃所有活动的热重载补丁和已启用的暂停点；使用 --persist 启用的暂停点除外，它们会在之后重新启用。响应中的 Warning 会报告被丢弃的数量，以及另外重新启用的数量。仅通过热重载应用的编辑不属于已编译程序集，因此新会话会运行上一次编译的代码——请在执行 Play 前运行 uloop compile 以保留这些编辑，或者在 Play Mode 启动后重新应用 uloop hot-reload。