Tool: control-play-mode

Relevant source files

The following files were used as context for generating this wiki page:

• Packages/src/Editor/Api/McpTools/ControlPlayMode/ControlPlayModeTool.cs
• Packages/src/Editor/Api/McpTools/ControlPlayMode/SKILL.md
• Packages/src/README.md
• Packages/src/ARCHITECTURE.md
• Packages/src/TypeScriptServer~/src/unity-tool-manager.ts
• Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts
• Packages/src/Cli~/scripts/generate-bundled-skills.ts

The control-play-mode tool provides an interface for AI agents and external scripts to control the Unity Editor's Play Mode. It allows for starting, pausing, and stopping Play Mode, which is a fundamental part of the autonomous development loop envisioned by uLoopMCP. By using this tool, an AI can verify game behavior, inspect the game state at a specific moment, or reset the state by exiting Play Mode.

This tool is one of the 14 bundled tools designed to let an AI run a full development cycle within a Unity project. It is exposed to LLM tools through both the MCP server and the uloop CLI.

Sources: Packages/src/README.md:143-148, Packages/src/Editor/Api/McpTools/ControlPlayMode/ControlPlayModeTool.cs:7-11

Architecture and Data Flow

The control-play-mode tool follows the standard uLoopMCP architecture, where a request from an MCP client (like an LLM tool or the uloop CLI) is relayed through a TypeScript server to the Unity Editor.

The diagram below illustrates the sequence of events when the control-play-mode tool is invoked.

1. Client Request: An LLM tool or the uloop CLI sends a request to execute control-play-mode.
2. TypeScript Server: The Node.js server receives the request. The UnityToolManager is responsible for discovering the control-play-mode tool from the connected Unity Editor. An instance of DynamicUnityCommandTool is created to represent this specific tool.
3. JSON-RPC Call: The DynamicUnityCommandTool instance forwards the execution request to the C# TCP server running inside the Unity Editor via a JSON-RPC call.
4. Unity Editor Execution: The C# server receives the call and invokes the ExecuteAsync method of the ControlPlayModeTool class. This class contains the core logic to interact with UnityEditor.EditorApplication to change the play state.
5. Response: The ControlPlayModeTool returns a response object, which is serialized and sent back to the TypeScript server, and finally relayed to the original client.

Sources: Packages/src/ARCHITECTURE.md, Packages/src/TypeScriptServer~/src/unity-tool-manager.ts:100-112, Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts:92-105

Core Implementation

The tool's logic is implemented in C# within the Unity project. It consists of a tool class, a parameter schema class, and a response class.

Sources: Packages/src/Editor/Api/McpTools/ControlPlayMode/ControlPlayModeTool.cs

Class Structure

The following diagram shows the relationship between the main classes involved in the control-play-mode tool.

This diagram illustrates that ControlPlayModeTool inherits from a generic base class and is specialized with ControlPlayModeSchema for its parameters and ControlPlayModeResponse for its return value.

Sources: Packages/src/Editor/Api/McpTools/ControlPlayMode/ControlPlayModeTool.cs:10-76

Execution Logic

The ExecuteAsync method in ControlPlayModeTool contains the primary logic. It checks the current state of the editor, performs the requested action, and reports back the initial and final states.

The flowchart below details the logic within the ExecuteAsync method.

Parameters and Response

The tool's interface is defined by its parameter schema and response structure.

Parameters (ControlPlayModeSchema)

The tool accepts a single parameter to determine the action to perform.

Parameter	Type (PlayModeAction)	Description	Default
Action	enum	The action to perform on the Play Mode.	Play

The PlayModeAction enum has the following possible values:

• Play: Starts Play Mode or resumes if paused.
• Pause: Pauses Play Mode.
• Stop: Stops Play Mode.

Sources: Packages/src/Editor/Api/McpTools/ControlPlayMode/ControlPlayModeTool.cs:13-18

Response (ControlPlayModeResponse)

The tool returns an object indicating the result of the operation.

Property	Type	Description
Success	bool	true if the state was changed or already in target state.
Message	string	A message describing the result of the operation.
InitialState	string	The editor's play state before the action was performed.
FinalState	string	The editor's play state after the action was performed.

Sources: Packages/src/Editor/Api/McpTools/ControlPlayMode/ControlPlayModeTool.cs:19-21

Skill Definition

To make the control-play-mode tool easily discoverable and usable by LLM tools via the uloop CLI, it includes a SKILL.md file. This file provides metadata and documentation that the uloop skills install command uses to integrate the tool into the LLM environment.

The generate-bundled-skills.ts script scans for SKILL.md files in Editor/Api/McpTools and bundles them for the CLI.

Sources: Packages/src/Cli~/scripts/generate-bundled-skills.ts:100-112

---
name: uloop-control-play-mode
description: Controls Unity Editor's Play Mode (Play, Pause, Stop). Use this to start the game, pause it for inspection, or stop it to return to Edit Mode.
---

# uloop control-play-mode

Controls the Unity Editor's Play Mode.

## Usage

```bash
uloop control-play-mode --action <action>

Arguments

• --action <action>: The action to perform.
  • Play: Enters Play Mode. If already in Play Mode but paused, it resumes.
  • Pause: Pauses Play Mode. Does nothing if not in Play Mode.
  • Stop: Exits Play Mode.

Examples

• Start Play Mode:

  uloop control-play-mode --action Play
  

• Pause the game:

  uloop control-play-mode --action Pause
  

• Stop Play Mode:

  uloop control-play-mode --action Stop
  

*Sources: [Packages/src/Editor/Api/McpTools/ControlPlayMode/SKILL.md](https://github.com/hatayama/unity-cli-loop/blob/HEAD/Packages/src/Editor/Api/McpTools/ControlPlayMode/SKILL.md)*

## Usage Example

An AI agent can use this tool to start the game, check its behavior, and then pause it to inspect the state of GameObjects.

Example interaction:
1.  Start the game to verify behavior: `control-play-mode (Action: Play)`
2.  Pause the game to inspect the current state: `control-play-mode (Action: Pause)`
3.  Use other tools like `get-hierarchy` or `find-game-objects` to analyze the scene.
4.  Stop the game to return to edit mode: `control-play-mode (Action: Stop)`

*Sources: [Packages/src/README.md:146-148](https://github.com/hatayama/unity-cli-loop/blob/HEAD/Packages/src/README.md#L146-L148)*