Tool: find-game-objects

Relevant source files

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

• Packages/src/Editor/Api/McpTools/FindGameObjects/FindGameObjectsTool.cs
• Packages/src/Editor/Core/CoreTools/GameObjectFinder/GameObjectFinderService.cs
• Packages/src/Editor/Api/McpTools/FindGameObjects/SKILL.md
• Packages/src/TOOL_REFERENCE.md
• README.md
• Packages/src/Cli~/src/tests/cli-e2e.test.ts
• Packages/src/Cli~/src/skills/bundled-skills.ts

The find-game-objects tool is a core Unity Editor automation and discovery tool within the uLoopMCP framework. Its primary function is to search for GameObject instances within the currently active scene based on a rich set of criteria, including name, components, tags, and layers. This enables AI agents to inspect the scene hierarchy, examine component parameters, and understand the structure of the game world programmatically.

This tool is essential for use cases such as having an AI inspect large numbers of GameObjects for bulk parameter adjustments or scene structure organization. It is exposed to LLM tools through both the MCP server and the uloop CLI, making it a fundamental component for scene-aware AI-driven development.

Sources: README.md, TOOL_REFERENCE.md

Architecture and Execution Flow

The find-game-objects tool follows the standard uLoopMCP architecture, where a request from an MCP client is routed through the TypeScript server to the corresponding C# tool running in the Unity Editor. The C# implementation decouples the tool's public-facing API from its core logic using a dedicated service.

Sources: ARCHITECTURE.md, Packages/src/Editor/Api/McpTools/FindGameObjects/FindGameObjectsTool.cs, Packages/src/Editor/Core/CoreTools/GameObjectFinder/GameObjectFinderService.cs

Execution Sequence

The following diagram illustrates the sequence of events when the find-game-objects tool is executed.

This diagram shows the flow from a client request to the final response, highlighting the delegation from FindGameObjectsTool to GameObjectFinderService.
Sources: Packages/src/Editor/Api/McpTools/FindGameObjects/FindGameObjectsTool.cs, Packages/src/Editor/Core/CoreTools/GameObjectFinder/GameObjectFinderService.cs

Class Relationships

The tool's implementation in Unity is split between a tool class and a service class, promoting separation of concerns.

This diagram shows that FindGameObjectsTool implements the standard tool interface, uses FindGameObjectsSchema for its parameters, and delegates the core work to an implementation of IGameObjectFinderService.
Sources: Packages/src/Editor/Api/McpTools/FindGameObjects/FindGameObjectsTool.cs, Packages/src/Editor/Core/CoreTools/GameObjectFinder/GameObjectFinderService.cs

Tool Parameters

The tool accepts several parameters to refine the search. These are defined in the FindGameObjectsSchema class.

Parameter	Type	Description	Default
NamePattern	string	GameObject name pattern to search for.	""
SearchMode	enum	Search mode: "Exact", "Path", "Regex", "Contains".	"Exact"
RequiredComponents	string[]	Array of component type names that GameObjects must have.	[]
Tag	string	Tag filter.	""
Layer	number	Layer filter.	null
IncludeInactive	boolean	Whether to include inactive GameObjects.	false
MaxResults	number	Maximum number of results to return.	20
IncludeInheritedProperties	boolean	Whether to include inherited properties in component details.	false

Sources: Packages/src/TOOL_REFERENCE.md, Packages/src/Editor/Api/McpTools/FindGameObjects/FindGameObjectsTool.cs

Response Structure

The tool returns a JSON object containing the search results and metadata.

Field	Type	Description
results	GameObjectSearchResult[]	An array of found GameObjects.
totalFound	number	The total number of GameObjects that matched the criteria before being limited by MaxResults.
errorMessage	string	An error message if the search failed.

GameObjectSearchResult Object

Each item in the results array has the following structure:

Field	Type	Description
name	string	The name of the GameObject.
path	string	The full hierarchy path of the GameObject.
isActive	boolean	Whether the GameObject is active in the hierarchy.
tag	string	The tag assigned to the GameObject.
layer	number	The layer number of the GameObject.
components	ComponentInfo[]	An array of components attached to the GameObject.

Sources: Packages/src/TOOL_REFERENCE.md, Packages/src/Editor/Core/CoreTools/GameObjectFinder/GameObjectFinderService.cs

Search Logic

The core search functionality resides within the GameObjectFinderService.FindGameObjectsAsync method. The process is as follows:

1. Initial Fetch: It begins by fetching all GameObject instances in the scene using Object.FindObjectsByType<GameObject>. The IncludeInactive parameter determines whether to include inactive objects in this initial set.
2. Filtering: The initial list is then filtered sequentially based on the provided parameters:
   • Name: Filters by name using the specified SearchMode (Exact, Path, Regex, or Contains).
   • Tag: If a Tag is provided, it filters for objects with that exact tag.
   • Layer: If a Layer is provided, it filters for objects on that layer.
   • Required Components: It checks if each GameObject has all the component types listed in the RequiredComponents array.
3. Result Capping: The filtered list is truncated to the MaxResults limit.
4. Response Construction: Finally, it constructs the GameObjectSearchResult objects for the final list, populating details like name, path, and component information.

This multi-stage filtering approach allows for precise and efficient querying of the scene hierarchy.

Sources: Packages/src/Editor/Core/CoreTools/GameObjectFinder/GameObjectFinderService.cs

CLI and Skill Integration

The find-game-objects tool is accessible via the uloop command-line interface and is integrated into the Skills system, making it discoverable by LLM tools like Claude Code.

Skill Definition

The tool's capabilities are described in a SKILL.md file, which is bundled into the CLI. This file informs the AI how and when to use the tool.

---
name: uloop-find-game-objects
description: Find GameObjects in the current scene by name, component, tag, or layer. Useful for inspecting scene hierarchy and object properties.
---

# uloop find-game-objects

Finds GameObjects in the currently open Unity scene.

## When to use it

Use this command to:
- Locate specific GameObjects to inspect their properties.
- Verify if objects with certain components exist.
- Get a list of objects matching a pattern for batch operations.
- Understand the structure of a scene.

Sources: Packages/src/Editor/Api/McpTools/FindGameObjects/SKILL.md, Packages/src/Cli~/src/skills/bundled-skills.ts

CLI Usage Example

The tool can be invoked directly from the command line. The end-to-end tests provide a practical example.

# Example from e2e tests
uloop find-game-objects --name-pattern "*" --include-inactive

This command searches for all GameObjects in the scene, including inactive ones, and returns the results as a JSON object.

Sources: Packages/src/Cli~/src/tests/cli-e2e.test.ts:200-206