coplaydev--unity-mcp/website/docs/architecture/manage-physics.md

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