wehub-resource-sync
111 lines
5.7 KiB
Markdown
111 lines
5.7 KiB
Markdown
# manage_physics — Complete Feature Patch
|
||
|
||
A new `manage_physics` MCP tool that gives AI assistants full control over Unity's 3D and 2D physics systems. **21 actions** across 9 categories, with C# Editor implementation, Python MCP service, CLI commands, and tests.
|
||
|
||
## Actions by Category
|
||
|
||
### Settings
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `ping` | Health check — returns gravity, solver settings, simulation mode |
|
||
| `get_settings` | Read physics project settings (3D or 2D) |
|
||
| `set_settings` | Write physics project settings (gravity, solver iterations, thresholds, etc.) |
|
||
|
||
### Collision Matrix
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `get_collision_matrix` | Read per-layer collision matrix |
|
||
| `set_collision_matrix` | Enable/disable collision between layer pairs |
|
||
|
||
### Materials
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `create_physics_material` | Create PhysicMaterial (3D) or PhysicsMaterial2D assets with friction/bounciness/combine modes |
|
||
| `configure_physics_material` | Update properties on an existing physics material asset |
|
||
| `assign_physics_material` | Assign a physics material to a GameObject's collider |
|
||
|
||
### Joints
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `add_joint` | Add a joint (hinge, spring, fixed, configurable, etc.) with optional connected body |
|
||
| `configure_joint` | Configure motor, limits, spring, drive, and direct properties on an existing joint |
|
||
| `remove_joint` | Remove joint(s) from a GameObject by type or all |
|
||
|
||
### Queries
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `raycast` | Single-hit raycast from origin along direction |
|
||
| `raycast_all` | Multi-hit raycast returning all intersections |
|
||
| `linecast` | Check if anything intersects the line between two points |
|
||
| `shapecast` | Cast a shape (sphere, box, capsule) along a direction |
|
||
| `overlap` | Find all colliders within a shape (sphere, box, capsule) at a position |
|
||
|
||
### Forces
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `apply_force` | Apply force, torque (or both), force-at-position, or explosion force to Rigidbodies. Supports all ForceModes for 3D and 2D |
|
||
|
||
### Rigidbody
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `get_rigidbody` | Read full Rigidbody state: mass, velocity, position, rotation, damping, constraints, sleep state, centerOfMass |
|
||
| `configure_rigidbody` | Set Rigidbody properties (mass, damping, gravity, kinematic, interpolation, collision detection, constraints) |
|
||
|
||
### Validation
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `validate` | Scan scene (or a single target) for physics issues. Paginated results (`page_size`/`cursor`/`next_cursor`) with per-category summary. 7 check categories: non-convex mesh, missing rigidbody, non-uniform scale, fast object with discrete detection, missing physics material, collision matrix, mixed 2D/3D. Smart warning levels — static colliders without Rigidbodies are downgraded to `[Info]` unless the object has an Animator |
|
||
|
||
### Simulation
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `simulate_step` | Step physics simulation in Edit mode (1–100 steps). Returns positions, velocities, and angular velocities of active Rigidbodies after stepping. Optional `target` to filter to a specific object |
|
||
|
||
## Architecture
|
||
|
||
### C# — 10 files in `MCPForUnity/Editor/Tools/Physics/`
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `ManagePhysics.cs` | Action dispatcher with `[McpForUnityTool]` registration |
|
||
| `PhysicsSettingsOps.cs` | ping, get_settings, set_settings |
|
||
| `CollisionMatrixOps.cs` | get_collision_matrix, set_collision_matrix |
|
||
| `PhysicsMaterialOps.cs` | create, configure, assign physics materials |
|
||
| `JointOps.cs` | add_joint, configure_joint, remove_joint |
|
||
| `PhysicsQueryOps.cs` | raycast, raycast_all, linecast, shapecast, overlap |
|
||
| `PhysicsForceOps.cs` | apply_force (normal, explosion, torque) |
|
||
| `PhysicsRigidbodyOps.cs` | get_rigidbody, configure_rigidbody |
|
||
| `PhysicsValidationOps.cs` | validate with pagination and smart warnings |
|
||
| `PhysicsSimulationOps.cs` | simulate_step with state reporting |
|
||
|
||
### Python — 3 files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `Server/src/services/tools/manage_physics.py` | MCP tool definition with 21-action Literal type, forwards all params to Unity |
|
||
| `Server/src/cli/commands/physics.py` | Full CLI with commands for every action category |
|
||
| `Server/tests/test_manage_physics.py` | 19 unit tests covering action forwarding and validation |
|
||
|
||
### Unity Tests
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManagePhysicsTests.cs` | 973-line EditMode test suite |
|
||
|
||
## Key Design Decisions
|
||
|
||
- **Modular ops classes**: Each physics domain (settings, materials, joints, queries, forces, etc.) gets its own C# class rather than one monolithic handler
|
||
- **Auto-dimension detection**: All actions auto-detect 2D vs 3D based on Rigidbody/Rigidbody2D component presence, with optional `dimension` override
|
||
- **Unity version compatibility**: Uses `#if UNITY_6000_0_OR_NEWER` for renamed APIs (drag → linearDamping, angularDrag → angularDamping)
|
||
- **Pagination on validate**: Large scenes can produce hundreds of warnings — paginated by default (50 per page) with a summary that always shows category counts regardless of page
|
||
- **Smart warning levels**: "Collider without Rigidbody" only escalates to a warning if the object has an Animator (suggesting runtime movement); otherwise downgraded to `[Info]`
|
||
- **Enriched responses**: Force/explosion actions echo back all applied values. Simulation returns Rigidbody states. Validation returns category breakdowns
|
||
|
||
## Stats
|
||
|
||
- **Net change**: +5,985 / −2,965 lines
|
||
- **New C# files**: 10 (+ 10 .meta)
|
||
- **New Python files**: 3
|
||
- **Actions**: 21
|
||
- **Tests**: 19 Python + EditMode C# suite
|