尧图网页设计 
Unity MCPmanage_physics工具完全指南让 AI 助手掌控 3D/2D 物理系统【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp本篇技术指南围绕 Unity MCP 项目一个在 AI 助手与 Unity Editor 之间架设桥梁的开源工具中的manage_physicsMCP 工具展开。该工具将 Unity 的物理系统——项目设置、碰撞矩阵、物理材质、关节、查询、力、刚体、校验与仿真——全部封装为 21 个可调用的 action让 LLM 或命令行能够直接读写 Unity 的物理世界。阅读本文后你将掌握manage_physics的全部 21 个 action 的用法与参数语义、底层调用链Python 服务 → C# 分发器 → 各 Ops 实现类、以及配套 CLI 命令与测试验证方法可以直接在自己的 Unity 项目中通过 AI 助手完成从改重力到施加爆炸力的完整物理操作。工具总览一个入口九大类 21 个 Actionmanage_physics是 Unity MCP 的核心工具组core成员模块路径为services.tools.manage_physics其官方定义为Manage physics settings, collision matrix, materials, joints, queries, and validation管理物理设置、碰撞矩阵、材质、关节、查询与校验。它同时覆盖 Unity 的3D 物理Physics与2D 物理Physics2D两套系统。在 Server/src/services/tools/manage_physics.py 中21 个 action 被定义为一个Literal类型PhysicsAction并通过ALL_ACTIONS列表供校验使用。从源码结构看这 21 个 action 按功能可归为九大类类别Action设置Settingsping、get_settings、set_settings碰撞矩阵Collision Matrixget_collision_matrix、set_collision_matrix材质Materialscreate_physics_material、configure_physics_material、assign_physics_material关节Jointsadd_joint、configure_joint、remove_joint查询Queriesraycast、raycast_all、linecast、shapecast、overlap力Forcesapply_force刚体Rigidbodyget_rigidbody、configure_rigidbody校验Validationvalidate仿真Simulationsimulate_step从 MCPForUnity/Editor/Tools/Physics/ManagePhysics.cs 可以看出C# 端通过[McpForUnityTool(manage_physics, AutoRegister false, Group core)]特性注册工具HandleCommand接收JObject参数后读取action字段再用一个switch语句将每个 action 分发给对应的 Ops 实现类。所有未知 action 或异常都会被统一包装为ErrorResponse并记录到McpLog。注意该工具在 MCP 注册时带有destructiveHintTrue标注见 manage_physics.py即它包含会修改场景/资产的破坏性操作如set_settings、add_joint、remove_jointAgent 调用时需谨慎。参数说明一个工具承载所有物理操作manage_physics通过一个action参数选择要执行的操作其余参数均为可选按 action 的实际需要传入。完整参数表来自 website/docs/reference/tools/core/manage_physics.md参数类型必填说明actionLiteral[...]是要执行的物理操作21 个枚举值dimensionstr \| None否物理维度3d默认或2dsettingsdict \| None否set_settings的键值对设置layer_a/layer_bstr \| None否碰撞矩阵中的图层名或索引collidebool \| None否是否允许两图层碰撞set_collision_matrixnamestr \| None否新建物理材质的名称pathstr \| None否材质资源路径dynamic_friction/static_friction/bouncinessfloat \| None否3D 材质属性动态摩擦 / 静态摩擦 / 弹性0-1frictionfloat \| None否2D 材质摩擦系数friction_combine/bounce_combinestr \| None否合并模式Average、Minimum、Multiply、Maximummaterial_pathstr \| None否用于 assign 的物理材质资源路径targetstr \| None否目标 GameObject 名称或实例 IDcollider_typestr \| None否指定要操作的碰撞器类型search_methodstr \| None否目标解析的搜索方式joint_typestr \| None否关节类型详见下文connected_bodystr \| None否关节连接的刚体目标motordict \| None否电机配置{targetVelocity, force, freeSpin}limitsdict \| None否限制配置{min, max, bounciness}springdict \| None否弹簧配置{spring, damper, targetPosition}drivedict \| None否ConfigurableJoint的驱动配置propertiesdict \| None否关节或材质的直接属性字典origin/directionlist[float] \| None否射线起点 / 方向[x,y,z]或[x,y]max_distancefloat \| None否最大投射距离layer_maskstr \| None否查询图层掩码图层名或整数query_trigger_interactionstr \| None否触发器交互UseGlobal、Ignore、Collideshapestr \| None否重叠查询形状3D 为 sphere/box/capsule2D 为 circle/box/capsulepositionlist[float] \| None否重叠查询位置[x,y,z]或[x,y]sizeAny \| None否重叠大小float半径或[x,y,z]半尺寸start/endlist[float] \| None否Linecast 的起止点point1/point2list[float] \| None否胶囊体 Shapecast 的两个端点heightfloat \| None否胶囊体高度capsule_directionint \| None否胶囊体方向0X、1Y默认、2Zanglefloat \| None否2D 形状投射的旋转角度forcelist[float] \| None否力的向量[x,y,z]或[x,y]force_modestr \| None否力模式3D 为 Force/Impulse/Acceleration/VelocityChange2D 为 Force/Impulseforce_typestr \| None否力类型normal默认或explosion仅 3Dtorquelist[float] \| None否扭矩向量3D 为[x,y,z]2D 为[z]explosion_position/explosion_radius/explosion_force/upwards_modifier各类型否爆炸力参数中心 / 半径 / 力大小 / 上抛修正stepsint \| None否仿真步数最大 100step_sizefloat \| None否仿真步长秒page_sizeint \| None否validate结果分页大小默认 50cursorint \| None否validate分页游标偏移component_indexint \| None否同类型组件存在多个时如多个 HingeJoint 或 BoxCollider用从零开始的索引选择目标缺省时作用于第一个实例在 Python 服务端manage_physics函数接收这些参数后将非None值组装为params_dict再通过send_with_unity_instance与async_send_command_with_retry发送给 Unity见 manage_physics.py。值得注意的细节component_index在 Python 层会被转写为驼峰式componentIndex后发送与 C# 端的参数约定保持一致而对未知 action服务端会直接返回{success: False, message: ...}而不会发往 Unity。设置类 Actionping / get_settings / set_settingsping健康检查ping返回物理系统的健康状态包括 3D/2D 重力、仿真模式、求解器迭代次数、弹跳阈值、休眠阈值、默认接触偏移等见 PhysicsSettingsOps.cs{ action: ping }响应中的data至少包含gravity3d、gravity2d、simulationMode、defaultSolverIterations、defaultSolverVelocityIterations、bounceThreshold、sleepThreshold、defaultContactOffset、queriesHitTriggers。C# 侧通过UnityPhysicsCompat.GetPhysicsSimulationMode()读取仿真模式该兼容层Runtime/Helpers/UnityPhysicsCompat.cs负责屏蔽不同 Unity 版本间的 API 差异。get_settings读取物理项目设置get_settings按dimension默认3d读取物理设置。3D 维度返回的重心字段包括gravity、defaultContactOffset、sleepThreshold、defaultSolverIterations、defaultSolverVelocityIterations、bounceThreshold、defaultMaxAngularSpeed、queriesHitTriggers、queriesHitBackfaces、simulationMode、autoSyncTransforms2D 维度则返回gravity、velocityIterations、positionIterations、queriesHitTriggers、queriesStartInColliders、callbacksOnDisable、autoSyncTransforms。若传入非法维度会返回错误提示Use 3d or 2dPhysicsSettingsOps.cs。set_settings写入物理项目设置set_settings接受一个settings字典。C# 实现的关键设计是先校验全部键、再统一应用若包含未知键直接返回错误且不做任何修改避免改了一半的脏状态PhysicsSettingsOps.cs。3D 可写键不区分大小写gravity须为[x,y,z]数组、defaultcontactoffset、sleepthreshold、defaultsolveriterations、defaultsolvervelocityiterations、bouncethreshold、defaultmaxangularspeed、querieshittriggers、querieshitbackfaces、simulationmode可选FixedUpdate/Update/Script且受 Unity 版本支持性校验、autosynctransforms。2D 可写键gravity[x,y]、velocityiterations、positioniterations、querieshittriggers、queriesstartincolliders、callbacksondisable、autosynctransforms。例如将 3D 重力调为两倍并开启后向面查询{ action: set_settings, dimension: 3d, settings: { gravity: [0, -19.62, 0], queriesHitBackfaces: true, defaultSolverIterations: 8 } }每次成功修改后C# 端会通过MarkDynamicsManagerDirty()/MarkPhysics2DSettingsDirty()对ProjectSettings/DynamicsManager.asset或ProjectSettings/Physics2DSettings.asset调用EditorUtility.SetDirty确保设置变更被持久化到项目设置文件中。响应会列出实际修改的字段列表changed数组。碰撞矩阵get_collision_matrix / set_collision_matrix碰撞矩阵Collision Matrix控制 32 个 Layer 之间是否发生碰撞。get_collision_matrix读取每个图层对的碰撞开关set_collision_matrix通过layer_a、layer_b图层名或索引与collide布尔值修改某一对图层的碰撞关系{ action: set_collision_matrix, layer_a: Default, layer_b: Player, collide: false }该实现位于 CollisionMatrixOps.cs底层对应 Unity 的Physics.IgnoreLayerCollision/GetIgnoreLayerCollision以及 Physics2D 的对应 API。典型应用场景是实现玩家与敌人不互相碰撞、子弹只打敌人不打玩家等常见游戏规则而无需人工在 Project Settings 里逐项勾选。物理材质create / configure / assign物理材质决定碰撞表面的摩擦与弹性。manage_physics提供三个动作create_physics_material新建PhysicMaterial3D或PhysicsMaterial2D资源。通过name指定材质名path指定存放目录默认在 Assets 根目录dimension决定 3D/2D3D 用dynamic_friction、static_friction、bounciness、friction_combine、bounce_combine2D 用friction、bounciness等属性。configure_physics_material通过path定位已有材质资源用properties字典或独立的摩擦/弹性参数直接更新其属性。assign_physics_material把material_path指向的材质赋给targetGameObject 的碰撞器。当目标有多个同类型碰撞器时可用collider_type指定类型、用component_index指定第几个实例。创建一颗很弹很滑的冰面材质{ action: create_physics_material, dimension: 3d, name: Ice, path: Assets/Materials/Physics, dynamic_friction: 0.05, static_friction: 0.05, bounciness: 0.9, friction_combine: Minimum, bounce_combine: Maximum }实现位于 PhysicsMaterialOps.cs材质创建走 Unity 的AssetDatabase.CreateAsset流程确保生成的是可持久化的 .asset 资源而非运行时对象。关节add_joint / configure_joint / remove_joint关节用于把两个刚体约束在一起。add_joint要求目标已有Rigidbody或Rigidbody2D否则直接报错见 JointOps.cs。支持的类型映射在源码中以字典形式维护3D 关节fixedFixedJoint、hingeHingeJoint、springSpringJoint、characterCharacterJoint、configurableConfigurableJoint2D 关节distance、fixed、friction、hinge、relative、slider、spring、target、wheel分别对应 9 种 Joint2D 组件{ action: add_joint, target: Door, joint_type: hinge, connected_body: DoorFrame, dimension: 3d }configure_joint支持motor{targetVelocity, force, freeSpin}、limits{min, max, bounciness}、spring{spring, damper, targetPosition}、driveConfigurableJoint 专用以及任意properties直写字典remove_joint可移除指定类型的关节省略joint_type则移除全部。component_index在目标有多个同类型关节时用于精确定位。实现上add_joint使用Undo.AddComponent以保证编辑器可撤销且会在添加前先校验 connected body 的刚体类型避免产生悬挂引用JointOps.cs。物理查询raycast / raycast_all / linecast / shapecast / overlap五种查询动作PhysicsQueryOps.cs把 Unity 的物理查询 API 暴露给 AI 助手统一支持dimension3d/2d、layer_mask图层名或整数掩码与query_trigger_interactionUseGlobal/Ignore/Collide参数。raycast 与 raycast_all单次命中射线检测需提供origin、direction数组与可选的max_distance默认Infinity。命中时返回point、normal、distance、gameObject名称、instanceID与collider_type未命中时返回{hit: false}{ action: raycast, dimension: 3d, origin: [0, 1, 0], direction: [0, 0, 1], max_distance: 50, layer_mask: Default }raycast_all返回所有命中并按距离升序排序响应包含hit_count与hits数组PhysicsQueryOps.cs。linecast检测两点之间的线段是否与任何碰撞器相交不关心第一个命中点的具体距离{ action: linecast, start: [0, 0, 0], end: [10, 0, 0], dimension: 3d }shapecast把形状球体/盒体/胶囊体沿方向投射。size语义随形状变化球体/圆为半径 float盒体为半尺寸数组[x,y,z]3D或尺寸[width,height]2D胶囊体为{radius, ...}或{width, height, direction}对象。胶囊体还可用point1/point2直接指定两端点或用heightcapsule_direction0X、1Y、2Z由代码自动推导端点。2D 场景可通过angle指定形状旋转角。overlap在指定位置用形状探测所有重叠碰撞器{ action: overlap, dimension: 3d, shape: sphere, position: [0, 2, 0], size: 1.5 }3D 支持sphere/box/capsule2D 支持circle/box/capsule胶囊体 2D 的size需为{width, height, direction}对象。返回命中碰撞器列表。一个值得注意的实现细节所有查询在执行前都会调用Physics.SyncTransforms()/Physics2D.SyncTransforms()保证 Transform 变换已同步到物理引擎避免刚移动物体查询不到PhysicsQueryOps.cs。layer_mask的解析逻辑PhysicsQueryOps.cs先尝试解析为整数掩码否则按图层名通过LayerMask.NameToLayer解析为单个位掩码缺省时返回~0全部图层。力与刚体apply_force / get_rigidbody / configure_rigidbodyapply_forceapply_force支持普通力、扭矩、指定位置施力与爆炸力四种形态见 PhysicsForceOps.cs普通力force向量3D 为[x,y,z]2D 为[x,y]可选force_mode3DForce、Impulse、Acceleration、VelocityChange2D 仅Force、Impulse可选position指定施力点AddForceAtPosition可选torque同时施加扭矩。爆炸力force_type: explosion仅 3D需explosion_position、explosion_radius、explosion_force可选upwards_modifier对应Rigidbody.AddExplosionForce。{ action: apply_force, target: Player, dimension: 3d, force: [0, 500, 0], force_mode: Impulse }实现上有三重前置校验目标必须存在必须有对应维度的 Rigidbody否则报Add one before applying force必须是非 kinematic 刚体运动学刚体不能施加力。维度未显式指定时自动检测优先看是否同时存在 Rigidbody/Rigidbody2Ddimension缺省时按有 2D 无 3D 则为 2D判断。所有响应都会回显实际施加的值force/torque/explosion 全套参数便于 Agent 核对。get_rigidbody / configure_rigidbodyget_rigidbody读取刚体完整状态质量、速度、位置、旋转、阻尼、约束、休眠状态与质心centerOfMass。configure_rigidbody通过properties字典设置刚体属性质量、阻尼、重力影响、是否 kinematic、插值、碰撞检测模式与约束。两者实现于 PhysicsRigidbodyOps.cs。这两类动作同样支持dimension自动检测与search_method目标解析。场景校验validate 与 7 类检查项validate是 AI 助手排查物理问题的利器对整个场景或单个target扫描常见物理配置错误返回分页结果与分类汇总。校验逻辑位于 PhysicsValidationOps.cs共 7 个检查类别类别键检查内容non_convex_mesh非运动学刚体上的 MeshCollider 未勾选 Convexmissing_rigidbody非静态物体有 Collider 但没有 Rigidbody见下方智能分级non_uniform_scale带碰撞器的物体存在非均匀缩放三轴差值 0.01会劣化物理性能fast_object_discrete名字含 bullet/projectile/fast 等特征、使用 Discrete 碰撞检测的快速物体建议改用 ContinuousDynamicmissing_physics_materialCollider 未指定物理材质使用默认值标记为[Info]collision_matrix场景级检查所有已命名图层彼此全部碰撞且图层数 2建议关闭无用图层对以提升性能mixed_2d_3d同一物体同时存在 3D 与 2D 物理组件智能警告分级是 validate 的一大亮点默认有 Collider 无 Rigidbody只是[Info]物体运行期不移动就完全没问题但若该物体或其父级链上存在 Animator暗示运行期会被移动/动画驱动则升级为真正的 warning提示Moving it via Transform causes broadphase rebuild every frame每帧 Transform 移动会导致宽相重建。validate支持分页page_size默认 50配合cursor与响应中的next_cursor翻页同时无论当前页大小summary都始终返回 7 个类别的完整计数方便快速定位问题分布PhysicsValidationOps.cs{ action: validate, dimension: both, target: Player }编辑模式仿真simulate_stepsimulate_step让 AI 助手在编辑模式下推进物理仿真传入steps1-100 步上限 100与可选的step_size秒即可离线模拟若干物理帧并返回所有激活刚体在步进后的位置、速度与角速度传入target可只关注某个物体。实现位于 PhysicsSimulationOps.cs这对于先预测再执行的工作流很有价值——例如先仿真 60 步验证机关触发结果再决定是否落地为场景修改。命令行入口physics子命令组除了通过 MCP 协议调用manage_physics还提供了完整的 Click CLI 封装Server/src/cli/commands/physics.py。CLI 对每个 action 都有对应命令典型用法# 健康检查与设置 unity-mcp physics ping unity-mcp physics get-settings --dimension 3d unity-mcp physics set-settings --dimension 3d gravity [0,-20,0] # 碰撞矩阵 unity-mcp physics get-collision-matrix --dimension 3d unity-mcp physics set-collision-matrix Default Player --ignore # 材质 unity-mcp physics create-material --name Ice --path Assets/Materials --bounciness 0.9 unity-mcp physics configure-material --path Assets/Materials/Ice.asset dynamicFriction0.1 unity-mcp physics assign-material --target Ball --material-path Assets/Materials/Ice.asset # 关节 unity-mcp physics add-joint --target Door --joint-type hinge --connected-body DoorFrame unity-mcp physics configure-joint --target Door --joint-type hinge motor.targetVelocity90 motor.force100 # 查询 unity-mcp physics raycast --origin 0,1,0 --direction 0,0,1 --max-distance 50 unity-mcp physics raycast-all --origin 0,1,0 --direction 0,0,1 unity-mcp physics linecast --start 0,0,0 --end 10,0,0 unity-mcp physics shapecast --shape sphere --origin 0,1,0 --direction 0,0,1 --size 0.5 unity-mcp physics overlap --shape sphere --position 0,2,0 --size 1.5 # 力与刚体 unity-mcp physics apply-force --target Player --force 0,500,0 --force-mode Impulse unity-mcp physics get-rigidbody Player unity-mcp physics configure-rigidbody --target Player mass3 isKinematictrue # 校验与仿真 unity-mcp physics validate --dimension both unity-mcp physics simulate --steps 60 --step-size 0.02CLI 内置_coerce_cli_value自动把字符串转换为 bool/int/float见 physics.py因此keyvalue形式的属性参数可以直接书写--collide/--ignore是一对布尔开关默认 collidevector 类型参数使用逗号分隔字符串如0,1,0CLI 内部会拆分为浮点数组。架构与调用链三层实现manage_physics的完整实现遵循Python MCP 服务 → C# Editor 工具 → Unity 物理 API的分层结构1. Python 层MCP 协议入口Server/src/services/tools/manage_physics.py定义 21 个 action 的Literal类型与全部参数负责校验 action 合法性、组装参数并通过send_with_unity_instanceasync_send_command_with_retry把命令发给指定 Unity 实例。Server/src/cli/commands/physics.pyClick 命令组每个 action 一个子命令。2. C# 层Editor 内执行— 采用模块化 Ops 类设计每个物理域一个类避免单一大而全的处理器位于 MCPForUnity/Editor/Tools/Physics/文件职责ManagePhysics.csAction 分发器与[McpForUnityTool]注册PhysicsSettingsOps.csping、get_settings、set_settingsCollisionMatrixOps.cs碰撞矩阵读写PhysicsMaterialOps.cs材质创建/配置/赋值JointOps.cs关节增删改PhysicsQueryOps.cs五种物理查询PhysicsForceOps.cs普通力/爆炸力/扭矩PhysicsRigidbodyOps.cs刚体状态读写PhysicsValidationOps.cs7 类校验与分页PhysicsSimulationOps.cs编辑模式步进仿真3. 兼容层C# 实现大量借助 MCPForUnity/Runtime/Helpers/UnityPhysicsCompat.cs 等兼容 shim例如#if UNITY_6000_0_OR_NEWER处理drag→linearDamping等 API 改名并在 MCPForUnity/Runtime/Helpers/ 下提供UnityPhysicsCompat、UnityObjectIdCompat等跨版本兼容工具保证工具在较老的 Unity 版本上也能运行。关键设计决策与 website/docs/architecture/manage-physics.md 记载一致所有 action 默认自动检测 2D/3D依据 Rigidbody/Rigidbody2D 组件是否存在dimension参数可显式覆盖validate默认每页 50 条并始终返回分类汇总力/爆炸/仿真类 action 返回增强型响应回显施加值、刚体状态方便 Agent 验证结果add_joint等场景修改操作走Undo通道保持编辑器可撤销。测试验证与文档生成该工具具备完整的双端测试覆盖Python 单测Server/tests/test_manage_physics.py共 19 个用例通过 mock 的send_with_unity_instance验证每个 action 的参数转发是否正确包括未知 action 报错、dimension透传、settings字典透传、碰撞矩阵参数透传、componentIndex驼峰转换等。Unity EditMode 测试TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManagePhysicsTests.cs974 行直接调用ManagePhysics.HandleCommand覆盖空参数/缺失 action/未知 action 的错误分支、ping返回字段完整性、3D/2D 设置读写、目标解析等真实编辑器行为测试中的临时物体统一以PhysTest_前缀命名并在TearDown中清理避免污染测试场景。此外website/docs/reference/tools/core/manage_physics.md 本身由tools/generate_docs_reference.py从 Python 工具注册表自动生成参数表与 action 列表与源码中的Literal定义保持严格同步因此上文所有参数均以该文档与 manage_physics.py 源码双重核对为准。实战建议AI 驱动关卡迭代让 Agent 先用validate扫描全场景拿到问题清单再按分类逐项修复如给快速物体补 Rigidbody 并切 ContinuousDynamic、给碰撞器赋值材质、关闭无用图层对最后用simulate_step验证修复效果。程序化机关搭建通过add_jointconfigure_jointmotor/limits/spring在编辑模式批量搭建铰链门、弹簧桥、可配置关节等机关connected_body参数让关节关系一目了然。查询驱动决策raycast/shapecast/overlap 可让 AI 在修改场景前先摸清当前世界视线是否被挡、半径内有哪些物体减少盲目操作。注意破坏性操作set_settings、remove_joint、configure_*会直接改动项目设置或场景建议先get_settings/get_rigidbody读取现状、通过Undo通道保留可撤销性并对settings/properties字典的键名严格按上文列出的白名单书写未知键会被整体拒绝。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Unity MCP `manage_physics` 工具完全指南：让 AI 助手掌控 3D/2D 物理系统
Unity MCPmanage_physics工具完全指南让 AI 助手掌控 3D/2D 物理系统【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp本篇技术指南围绕 Unity MCP 项目一个在 AI 助手与 Unity Editor 之间架设桥梁的开源工具中的manage_physicsMCP 工具展开。该工具将 Unity 的物理系统——项目设置、碰撞矩阵、物理材质、关节、查询、力、刚体、校验与仿真——全部封装为 21 个可调用的 action让 LLM 或命令行能够直接读写 Unity 的物理世界。阅读本文后你将掌握manage_physics的全部 21 个 action 的用法与参数语义、底层调用链Python 服务 → C# 分发器 → 各 Ops 实现类、以及配套 CLI 命令与测试验证方法可以直接在自己的 Unity 项目中通过 AI 助手完成从改重力到施加爆炸力的完整物理操作。工具总览一个入口九大类 21 个 Actionmanage_physics是 Unity MCP 的核心工具组core成员模块路径为services.tools.manage_physics其官方定义为Manage physics settings, collision matrix, materials, joints, queries, and validation管理物理设置、碰撞矩阵、材质、关节、查询与校验。它同时覆盖 Unity 的3D 物理Physics与2D 物理Physics2D两套系统。在 Server/src/services/tools/manage_physics.py 中21 个 action 被定义为一个Literal类型PhysicsAction并通过ALL_ACTIONS列表供校验使用。从源码结构看这 21 个 action 按功能可归为九大类类别Action设置Settingsping、get_settings、set_settings碰撞矩阵Collision Matrixget_collision_matrix、set_collision_matrix材质Materialscreate_physics_material、configure_physics_material、assign_physics_material关节Jointsadd_joint、configure_joint、remove_joint查询Queriesraycast、raycast_all、linecast、shapecast、overlap力Forcesapply_force刚体Rigidbodyget_rigidbody、configure_rigidbody校验Validationvalidate仿真Simulationsimulate_step从 MCPForUnity/Editor/Tools/Physics/ManagePhysics.cs 可以看出C# 端通过[McpForUnityTool(manage_physics, AutoRegister false, Group core)]特性注册工具HandleCommand接收JObject参数后读取action字段再用一个switch语句将每个 action 分发给对应的 Ops 实现类。所有未知 action 或异常都会被统一包装为ErrorResponse并记录到McpLog。注意该工具在 MCP 注册时带有destructiveHintTrue标注见 manage_physics.py即它包含会修改场景/资产的破坏性操作如set_settings、add_joint、remove_jointAgent 调用时需谨慎。参数说明一个工具承载所有物理操作manage_physics通过一个action参数选择要执行的操作其余参数均为可选按 action 的实际需要传入。完整参数表来自 website/docs/reference/tools/core/manage_physics.md参数类型必填说明actionLiteral[...]是要执行的物理操作21 个枚举值dimensionstr \| None否物理维度3d默认或2dsettingsdict \| None否set_settings的键值对设置layer_a/layer_bstr \| None否碰撞矩阵中的图层名或索引collidebool \| None否是否允许两图层碰撞set_collision_matrixnamestr \| None否新建物理材质的名称pathstr \| None否材质资源路径dynamic_friction/static_friction/bouncinessfloat \| None否3D 材质属性动态摩擦 / 静态摩擦 / 弹性0-1frictionfloat \| None否2D 材质摩擦系数friction_combine/bounce_combinestr \| None否合并模式Average、Minimum、Multiply、Maximummaterial_pathstr \| None否用于 assign 的物理材质资源路径targetstr \| None否目标 GameObject 名称或实例 IDcollider_typestr \| None否指定要操作的碰撞器类型search_methodstr \| None否目标解析的搜索方式joint_typestr \| None否关节类型详见下文connected_bodystr \| None否关节连接的刚体目标motordict \| None否电机配置{targetVelocity, force, freeSpin}limitsdict \| None否限制配置{min, max, bounciness}springdict \| None否弹簧配置{spring, damper, targetPosition}drivedict \| None否ConfigurableJoint的驱动配置propertiesdict \| None否关节或材质的直接属性字典origin/directionlist[float] \| None否射线起点 / 方向[x,y,z]或[x,y]max_distancefloat \| None否最大投射距离layer_maskstr \| None否查询图层掩码图层名或整数query_trigger_interactionstr \| None否触发器交互UseGlobal、Ignore、Collideshapestr \| None否重叠查询形状3D 为 sphere/box/capsule2D 为 circle/box/capsulepositionlist[float] \| None否重叠查询位置[x,y,z]或[x,y]sizeAny \| None否重叠大小float半径或[x,y,z]半尺寸start/endlist[float] \| None否Linecast 的起止点point1/point2list[float] \| None否胶囊体 Shapecast 的两个端点heightfloat \| None否胶囊体高度capsule_directionint \| None否胶囊体方向0X、1Y默认、2Zanglefloat \| None否2D 形状投射的旋转角度forcelist[float] \| None否力的向量[x,y,z]或[x,y]force_modestr \| None否力模式3D 为 Force/Impulse/Acceleration/VelocityChange2D 为 Force/Impulseforce_typestr \| None否力类型normal默认或explosion仅 3Dtorquelist[float] \| None否扭矩向量3D 为[x,y,z]2D 为[z]explosion_position/explosion_radius/explosion_force/upwards_modifier各类型否爆炸力参数中心 / 半径 / 力大小 / 上抛修正stepsint \| None否仿真步数最大 100step_sizefloat \| None否仿真步长秒page_sizeint \| None否validate结果分页大小默认 50cursorint \| None否validate分页游标偏移component_indexint \| None否同类型组件存在多个时如多个 HingeJoint 或 BoxCollider用从零开始的索引选择目标缺省时作用于第一个实例在 Python 服务端manage_physics函数接收这些参数后将非None值组装为params_dict再通过send_with_unity_instance与async_send_command_with_retry发送给 Unity见 manage_physics.py。值得注意的细节component_index在 Python 层会被转写为驼峰式componentIndex后发送与 C# 端的参数约定保持一致而对未知 action服务端会直接返回{success: False, message: ...}而不会发往 Unity。设置类 Actionping / get_settings / set_settingsping健康检查ping返回物理系统的健康状态包括 3D/2D 重力、仿真模式、求解器迭代次数、弹跳阈值、休眠阈值、默认接触偏移等见 PhysicsSettingsOps.cs{ action: ping }响应中的data至少包含gravity3d、gravity2d、simulationMode、defaultSolverIterations、defaultSolverVelocityIterations、bounceThreshold、sleepThreshold、defaultContactOffset、queriesHitTriggers。C# 侧通过UnityPhysicsCompat.GetPhysicsSimulationMode()读取仿真模式该兼容层Runtime/Helpers/UnityPhysicsCompat.cs负责屏蔽不同 Unity 版本间的 API 差异。get_settings读取物理项目设置get_settings按dimension默认3d读取物理设置。3D 维度返回的重心字段包括gravity、defaultContactOffset、sleepThreshold、defaultSolverIterations、defaultSolverVelocityIterations、bounceThreshold、defaultMaxAngularSpeed、queriesHitTriggers、queriesHitBackfaces、simulationMode、autoSyncTransforms2D 维度则返回gravity、velocityIterations、positionIterations、queriesHitTriggers、queriesStartInColliders、callbacksOnDisable、autoSyncTransforms。若传入非法维度会返回错误提示Use 3d or 2dPhysicsSettingsOps.cs。set_settings写入物理项目设置set_settings接受一个settings字典。C# 实现的关键设计是先校验全部键、再统一应用若包含未知键直接返回错误且不做任何修改避免改了一半的脏状态PhysicsSettingsOps.cs。3D 可写键不区分大小写gravity须为[x,y,z]数组、defaultcontactoffset、sleepthreshold、defaultsolveriterations、defaultsolvervelocityiterations、bouncethreshold、defaultmaxangularspeed、querieshittriggers、querieshitbackfaces、simulationmode可选FixedUpdate/Update/Script且受 Unity 版本支持性校验、autosynctransforms。2D 可写键gravity[x,y]、velocityiterations、positioniterations、querieshittriggers、queriesstartincolliders、callbacksondisable、autosynctransforms。例如将 3D 重力调为两倍并开启后向面查询{ action: set_settings, dimension: 3d, settings: { gravity: [0, -19.62, 0], queriesHitBackfaces: true, defaultSolverIterations: 8 } }每次成功修改后C# 端会通过MarkDynamicsManagerDirty()/MarkPhysics2DSettingsDirty()对ProjectSettings/DynamicsManager.asset或ProjectSettings/Physics2DSettings.asset调用EditorUtility.SetDirty确保设置变更被持久化到项目设置文件中。响应会列出实际修改的字段列表changed数组。碰撞矩阵get_collision_matrix / set_collision_matrix碰撞矩阵Collision Matrix控制 32 个 Layer 之间是否发生碰撞。get_collision_matrix读取每个图层对的碰撞开关set_collision_matrix通过layer_a、layer_b图层名或索引与collide布尔值修改某一对图层的碰撞关系{ action: set_collision_matrix, layer_a: Default, layer_b: Player, collide: false }该实现位于 CollisionMatrixOps.cs底层对应 Unity 的Physics.IgnoreLayerCollision/GetIgnoreLayerCollision以及 Physics2D 的对应 API。典型应用场景是实现玩家与敌人不互相碰撞、子弹只打敌人不打玩家等常见游戏规则而无需人工在 Project Settings 里逐项勾选。物理材质create / configure / assign物理材质决定碰撞表面的摩擦与弹性。manage_physics提供三个动作create_physics_material新建PhysicMaterial3D或PhysicsMaterial2D资源。通过name指定材质名path指定存放目录默认在 Assets 根目录dimension决定 3D/2D3D 用dynamic_friction、static_friction、bounciness、friction_combine、bounce_combine2D 用friction、bounciness等属性。configure_physics_material通过path定位已有材质资源用properties字典或独立的摩擦/弹性参数直接更新其属性。assign_physics_material把material_path指向的材质赋给targetGameObject 的碰撞器。当目标有多个同类型碰撞器时可用collider_type指定类型、用component_index指定第几个实例。创建一颗很弹很滑的冰面材质{ action: create_physics_material, dimension: 3d, name: Ice, path: Assets/Materials/Physics, dynamic_friction: 0.05, static_friction: 0.05, bounciness: 0.9, friction_combine: Minimum, bounce_combine: Maximum }实现位于 PhysicsMaterialOps.cs材质创建走 Unity 的AssetDatabase.CreateAsset流程确保生成的是可持久化的 .asset 资源而非运行时对象。关节add_joint / configure_joint / remove_joint关节用于把两个刚体约束在一起。add_joint要求目标已有Rigidbody或Rigidbody2D否则直接报错见 JointOps.cs。支持的类型映射在源码中以字典形式维护3D 关节fixedFixedJoint、hingeHingeJoint、springSpringJoint、characterCharacterJoint、configurableConfigurableJoint2D 关节distance、fixed、friction、hinge、relative、slider、spring、target、wheel分别对应 9 种 Joint2D 组件{ action: add_joint, target: Door, joint_type: hinge, connected_body: DoorFrame, dimension: 3d }configure_joint支持motor{targetVelocity, force, freeSpin}、limits{min, max, bounciness}、spring{spring, damper, targetPosition}、driveConfigurableJoint 专用以及任意properties直写字典remove_joint可移除指定类型的关节省略joint_type则移除全部。component_index在目标有多个同类型关节时用于精确定位。实现上add_joint使用Undo.AddComponent以保证编辑器可撤销且会在添加前先校验 connected body 的刚体类型避免产生悬挂引用JointOps.cs。物理查询raycast / raycast_all / linecast / shapecast / overlap五种查询动作PhysicsQueryOps.cs把 Unity 的物理查询 API 暴露给 AI 助手统一支持dimension3d/2d、layer_mask图层名或整数掩码与query_trigger_interactionUseGlobal/Ignore/Collide参数。raycast 与 raycast_all单次命中射线检测需提供origin、direction数组与可选的max_distance默认Infinity。命中时返回point、normal、distance、gameObject名称、instanceID与collider_type未命中时返回{hit: false}{ action: raycast, dimension: 3d, origin: [0, 1, 0], direction: [0, 0, 1], max_distance: 50, layer_mask: Default }raycast_all返回所有命中并按距离升序排序响应包含hit_count与hits数组PhysicsQueryOps.cs。linecast检测两点之间的线段是否与任何碰撞器相交不关心第一个命中点的具体距离{ action: linecast, start: [0, 0, 0], end: [10, 0, 0], dimension: 3d }shapecast把形状球体/盒体/胶囊体沿方向投射。size语义随形状变化球体/圆为半径 float盒体为半尺寸数组[x,y,z]3D或尺寸[width,height]2D胶囊体为{radius, ...}或{width, height, direction}对象。胶囊体还可用point1/point2直接指定两端点或用heightcapsule_direction0X、1Y、2Z由代码自动推导端点。2D 场景可通过angle指定形状旋转角。overlap在指定位置用形状探测所有重叠碰撞器{ action: overlap, dimension: 3d, shape: sphere, position: [0, 2, 0], size: 1.5 }3D 支持sphere/box/capsule2D 支持circle/box/capsule胶囊体 2D 的size需为{width, height, direction}对象。返回命中碰撞器列表。一个值得注意的实现细节所有查询在执行前都会调用Physics.SyncTransforms()/Physics2D.SyncTransforms()保证 Transform 变换已同步到物理引擎避免刚移动物体查询不到PhysicsQueryOps.cs。layer_mask的解析逻辑PhysicsQueryOps.cs先尝试解析为整数掩码否则按图层名通过LayerMask.NameToLayer解析为单个位掩码缺省时返回~0全部图层。力与刚体apply_force / get_rigidbody / configure_rigidbodyapply_forceapply_force支持普通力、扭矩、指定位置施力与爆炸力四种形态见 PhysicsForceOps.cs普通力force向量3D 为[x,y,z]2D 为[x,y]可选force_mode3DForce、Impulse、Acceleration、VelocityChange2D 仅Force、Impulse可选position指定施力点AddForceAtPosition可选torque同时施加扭矩。爆炸力force_type: explosion仅 3D需explosion_position、explosion_radius、explosion_force可选upwards_modifier对应Rigidbody.AddExplosionForce。{ action: apply_force, target: Player, dimension: 3d, force: [0, 500, 0], force_mode: Impulse }实现上有三重前置校验目标必须存在必须有对应维度的 Rigidbody否则报Add one before applying force必须是非 kinematic 刚体运动学刚体不能施加力。维度未显式指定时自动检测优先看是否同时存在 Rigidbody/Rigidbody2Ddimension缺省时按有 2D 无 3D 则为 2D判断。所有响应都会回显实际施加的值force/torque/explosion 全套参数便于 Agent 核对。get_rigidbody / configure_rigidbodyget_rigidbody读取刚体完整状态质量、速度、位置、旋转、阻尼、约束、休眠状态与质心centerOfMass。configure_rigidbody通过properties字典设置刚体属性质量、阻尼、重力影响、是否 kinematic、插值、碰撞检测模式与约束。两者实现于 PhysicsRigidbodyOps.cs。这两类动作同样支持dimension自动检测与search_method目标解析。场景校验validate 与 7 类检查项validate是 AI 助手排查物理问题的利器对整个场景或单个target扫描常见物理配置错误返回分页结果与分类汇总。校验逻辑位于 PhysicsValidationOps.cs共 7 个检查类别类别键检查内容non_convex_mesh非运动学刚体上的 MeshCollider 未勾选 Convexmissing_rigidbody非静态物体有 Collider 但没有 Rigidbody见下方智能分级non_uniform_scale带碰撞器的物体存在非均匀缩放三轴差值 0.01会劣化物理性能fast_object_discrete名字含 bullet/projectile/fast 等特征、使用 Discrete 碰撞检测的快速物体建议改用 ContinuousDynamicmissing_physics_materialCollider 未指定物理材质使用默认值标记为[Info]collision_matrix场景级检查所有已命名图层彼此全部碰撞且图层数 2建议关闭无用图层对以提升性能mixed_2d_3d同一物体同时存在 3D 与 2D 物理组件智能警告分级是 validate 的一大亮点默认有 Collider 无 Rigidbody只是[Info]物体运行期不移动就完全没问题但若该物体或其父级链上存在 Animator暗示运行期会被移动/动画驱动则升级为真正的 warning提示Moving it via Transform causes broadphase rebuild every frame每帧 Transform 移动会导致宽相重建。validate支持分页page_size默认 50配合cursor与响应中的next_cursor翻页同时无论当前页大小summary都始终返回 7 个类别的完整计数方便快速定位问题分布PhysicsValidationOps.cs{ action: validate, dimension: both, target: Player }编辑模式仿真simulate_stepsimulate_step让 AI 助手在编辑模式下推进物理仿真传入steps1-100 步上限 100与可选的step_size秒即可离线模拟若干物理帧并返回所有激活刚体在步进后的位置、速度与角速度传入target可只关注某个物体。实现位于 PhysicsSimulationOps.cs这对于先预测再执行的工作流很有价值——例如先仿真 60 步验证机关触发结果再决定是否落地为场景修改。命令行入口physics子命令组除了通过 MCP 协议调用manage_physics还提供了完整的 Click CLI 封装Server/src/cli/commands/physics.py。CLI 对每个 action 都有对应命令典型用法# 健康检查与设置 unity-mcp physics ping unity-mcp physics get-settings --dimension 3d unity-mcp physics set-settings --dimension 3d gravity [0,-20,0] # 碰撞矩阵 unity-mcp physics get-collision-matrix --dimension 3d unity-mcp physics set-collision-matrix Default Player --ignore # 材质 unity-mcp physics create-material --name Ice --path Assets/Materials --bounciness 0.9 unity-mcp physics configure-material --path Assets/Materials/Ice.asset dynamicFriction0.1 unity-mcp physics assign-material --target Ball --material-path Assets/Materials/Ice.asset # 关节 unity-mcp physics add-joint --target Door --joint-type hinge --connected-body DoorFrame unity-mcp physics configure-joint --target Door --joint-type hinge motor.targetVelocity90 motor.force100 # 查询 unity-mcp physics raycast --origin 0,1,0 --direction 0,0,1 --max-distance 50 unity-mcp physics raycast-all --origin 0,1,0 --direction 0,0,1 unity-mcp physics linecast --start 0,0,0 --end 10,0,0 unity-mcp physics shapecast --shape sphere --origin 0,1,0 --direction 0,0,1 --size 0.5 unity-mcp physics overlap --shape sphere --position 0,2,0 --size 1.5 # 力与刚体 unity-mcp physics apply-force --target Player --force 0,500,0 --force-mode Impulse unity-mcp physics get-rigidbody Player unity-mcp physics configure-rigidbody --target Player mass3 isKinematictrue # 校验与仿真 unity-mcp physics validate --dimension both unity-mcp physics simulate --steps 60 --step-size 0.02CLI 内置_coerce_cli_value自动把字符串转换为 bool/int/float见 physics.py因此keyvalue形式的属性参数可以直接书写--collide/--ignore是一对布尔开关默认 collidevector 类型参数使用逗号分隔字符串如0,1,0CLI 内部会拆分为浮点数组。架构与调用链三层实现manage_physics的完整实现遵循Python MCP 服务 → C# Editor 工具 → Unity 物理 API的分层结构1. Python 层MCP 协议入口Server/src/services/tools/manage_physics.py定义 21 个 action 的Literal类型与全部参数负责校验 action 合法性、组装参数并通过send_with_unity_instanceasync_send_command_with_retry把命令发给指定 Unity 实例。Server/src/cli/commands/physics.pyClick 命令组每个 action 一个子命令。2. C# 层Editor 内执行— 采用模块化 Ops 类设计每个物理域一个类避免单一大而全的处理器位于 MCPForUnity/Editor/Tools/Physics/文件职责ManagePhysics.csAction 分发器与[McpForUnityTool]注册PhysicsSettingsOps.csping、get_settings、set_settingsCollisionMatrixOps.cs碰撞矩阵读写PhysicsMaterialOps.cs材质创建/配置/赋值JointOps.cs关节增删改PhysicsQueryOps.cs五种物理查询PhysicsForceOps.cs普通力/爆炸力/扭矩PhysicsRigidbodyOps.cs刚体状态读写PhysicsValidationOps.cs7 类校验与分页PhysicsSimulationOps.cs编辑模式步进仿真3. 兼容层C# 实现大量借助 MCPForUnity/Runtime/Helpers/UnityPhysicsCompat.cs 等兼容 shim例如#if UNITY_6000_0_OR_NEWER处理drag→linearDamping等 API 改名并在 MCPForUnity/Runtime/Helpers/ 下提供UnityPhysicsCompat、UnityObjectIdCompat等跨版本兼容工具保证工具在较老的 Unity 版本上也能运行。关键设计决策与 website/docs/architecture/manage-physics.md 记载一致所有 action 默认自动检测 2D/3D依据 Rigidbody/Rigidbody2D 组件是否存在dimension参数可显式覆盖validate默认每页 50 条并始终返回分类汇总力/爆炸/仿真类 action 返回增强型响应回显施加值、刚体状态方便 Agent 验证结果add_joint等场景修改操作走Undo通道保持编辑器可撤销。测试验证与文档生成该工具具备完整的双端测试覆盖Python 单测Server/tests/test_manage_physics.py共 19 个用例通过 mock 的send_with_unity_instance验证每个 action 的参数转发是否正确包括未知 action 报错、dimension透传、settings字典透传、碰撞矩阵参数透传、componentIndex驼峰转换等。Unity EditMode 测试TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManagePhysicsTests.cs974 行直接调用ManagePhysics.HandleCommand覆盖空参数/缺失 action/未知 action 的错误分支、ping返回字段完整性、3D/2D 设置读写、目标解析等真实编辑器行为测试中的临时物体统一以PhysTest_前缀命名并在TearDown中清理避免污染测试场景。此外website/docs/reference/tools/core/manage_physics.md 本身由tools/generate_docs_reference.py从 Python 工具注册表自动生成参数表与 action 列表与源码中的Literal定义保持严格同步因此上文所有参数均以该文档与 manage_physics.py 源码双重核对为准。实战建议AI 驱动关卡迭代让 Agent 先用validate扫描全场景拿到问题清单再按分类逐项修复如给快速物体补 Rigidbody 并切 ContinuousDynamic、给碰撞器赋值材质、关闭无用图层对最后用simulate_step验证修复效果。程序化机关搭建通过add_jointconfigure_jointmotor/limits/spring在编辑模式批量搭建铰链门、弹簧桥、可配置关节等机关connected_body参数让关节关系一目了然。查询驱动决策raycast/shapecast/overlap 可让 AI 在修改场景前先摸清当前世界视线是否被挡、半径内有哪些物体减少盲目操作。注意破坏性操作set_settings、remove_joint、configure_*会直接改动项目设置或场景建议先get_settings/get_rigidbody读取现状、通过Undo通道保留可撤销性并对settings/properties字典的键名严格按上文列出的白名单书写未知键会被整体拒绝。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考