Tools
Tools are a high-level primitive you can use to build complex, interactive user workflows. They serve as the bridge between user actions (like mouse clicks in the 3D viewport or slider adjustments in a side panel) and the authoritative project state.
Building Interactive Tools
A Tool is an asynchronous process that guides the user through a specific task. Unlike standard Bevy systems that run every frame, a Tool has a defined lifecycle and is managed exclusively by the Runtime.
The Tool Lifecycle
Only one Tool can be active in the client at any given time. This exclusivity prevents conflicting interactions and ensures a clear, linear workflow for the user. When a tool is activated:
- Setup: The SDK initializes the tool’s environment, displaying its dedicated UI panel and any associated Viewport Overlays.
- The Event Loop: The tool’s asynchronous
runmethod enters a loop, waiting for and reacting to inputs. These inputs can come from property changes in the UI panel, direct interactions in the 3D viewport, or specialized ECS systems that track spatial state. - Committing Changes: When the user performs an action (like clicking to place a point), the tool processes that data and commits a Statement or a Transaction to modify the project.
- Teardown: Once the task is completed or the user cancels, the tool is stopped, and the SDK automatically cleans up the UI and overlays.