unity-physics

**调用本模块中的任何技能前：**如果你打算根据技能名称或描述猜测参数后调用技能，请立即停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 中获得参数定义，则可以直接进行 dryRun。

触发条件

• 发射射线
• 检测重叠
• 查询碰撞体
• 调整重力/物理设置
• 发射射线、检测重叠、查询碰撞体、调整重力/物理设置

物理技能

编辑器时的物理查询（射线检测 / 重叠检测）、重力、PhysicMaterial 资源和图层碰撞矩阵。

运行模式

• Approval：查询类技能（physics_raycast / physics_check_overlap / physics_get_gravity / physics_get_layer_collision 等，源码标记为 SkillMode.SemiAuto）直接执行；变更类（physics_set_gravity / physics_create_material / physics_set_material / physics_set_layer_collision，标记为 SkillMode.FullAuto）需要用户授权，授权后由服务端一步执行并返回结果。
• Auto / Bypass：所有技能均直接执行；Auto 模式会进行 AI 自我评估，Bypass 模式则全部放行。
• 本模块不包含 Delete / PlayMode / Reload / 高危技能，也没有仅在 Bypass 模式下拦截的项目。
• 注意：所有技能都在编辑器线程中同步运行。真实物理模拟（积分、碰撞响应）仅在 Play mode 下推进；本模块只执行单帧查询和资源/全局设置写入，不会启动模拟。

不要（常见臆测）：

• physics_add_rigidbody / physics_add_collider 不存在 → 使用 component_add，并将 componentType 设为 "Rigidbody"/"BoxCollider"/等。
• physics_simulate 不存在 → 物理模拟在 Play mode 期间运行；本模块不会推进模拟
• Raycast 结果使用世界空间坐标

路由：

• 添加物理组件 → 使用 component 模块
• 物理材质 → 使用 physics_create_material（本模块）
• 图层碰撞矩阵 → 使用 physics_set_layer_collision（本模块）

技能

physics_raycast

发射射线并获取命中信息。 参数：

• originX、originY、originZ（float）：原点。
• dirX、dirY、dirZ（float）：方向向量。
• maxDistance（float，可选）：最大距离（默认值为 1000）。
• layerMask（int，可选）：图层遮罩（默认值为 -1）。

返回： { hit: true, collider: "Cube", distance: 5.2, ... }

physics_check_overlap

检查球体内的碰撞体。 参数：

• x、y、z（float）：中心点。
• radius（float）：球体半径。
• layerMask（int，可选）：图层遮罩。

physics_get_gravity

获取全局重力设置。 参数： 无。

physics_set_gravity

设置全局重力。 参数：

• x、y、z（float）：重力向量（例如 0, -9.81, 0）。

physics_raycast_all

发射射线并返回所有命中项（穿透式）。

参数	类型	必填	默认值	描述
originX	float	是	-	射线原点 X
originY	float	是	-	射线原点 Y
originZ	float	是	-	射线原点 Z
dirX	float	是	-	方向 X
dirY	float	是	-	方向 Y
dirZ	float	是	-	方向 Z
maxDistance	float	否	1000	射线最大距离
layerMask	int	否	-1	图层遮罩筛选条件

返回： { count, hits: [{ objectName, instanceId, path, point, normal, distance }] }

physics_spherecast

沿某个方向发射球体并获取命中信息。

参数	类型	必填	默认值	描述
originX	float	是	-	原点 X
originY	float	是	-	原点 Y
originZ	float	是	-	原点 Z
dirX	float	是	-	方向 X
dirY	float	是	-	方向 Y
dirZ	float	是	-	方向 Z
radius	float	是	-	球体半径
maxDistance	float	否	1000	最大投射距离
layerMask	int	否	-1	图层遮罩筛选条件

返回： { hit, objectName, instanceId, point, distance }

physics_boxcast

沿某个方向投射一个盒体并获取命中信息。

参数	类型	必填	默认值	描述
originX	float	是	-	原点 X
originY	float	是	-	原点 Y
originZ	float	是	-	原点 Z
dirX	float	是	-	方向 X
dirY	float	是	-	方向 Y
dirZ	float	是	-	方向 Z
halfExtentX	float	否	0.5	盒体半尺寸 X
halfExtentY	float	否	0.5	盒体半尺寸 Y
halfExtentZ	float	否	0.5	盒体半尺寸 Z
maxDistance	float	否	1000	最大投射距离
layerMask	int	否	-1	层掩码筛选器

返回： { hit, objectName, instanceId, point, distance }

physics_overlap_box

检查与盒体体积重叠的碰撞体。

参数	类型	必填	默认值	描述
x	float	是	-	盒体中心 X
y	float	是	-	盒体中心 Y
z	float	是	-	盒体中心 Z
halfExtentX	float	否	0.5	盒体半尺寸 X
halfExtentY	float	否	0.5	盒体半尺寸 Y
halfExtentZ	float	否	0.5	盒体半尺寸 Z
layerMask	int	否	-1	层掩码筛选器

返回： { count, colliders: [{ objectName, path, isTrigger }] }

physics_create_material

创建一个 PhysicMaterial 资源。

参数	类型	必填	默认值	描述
name	string	否	"New PhysicMaterial"	材质名称
savePath	string	否	"Assets"	保存目录路径
dynamicFriction	float	否	0.6	动摩擦值
staticFriction	float	否	0.6	静摩擦值
bounciness	float	否	0	弹性值

返回： { success, path }

physics_set_material

为碰撞体设置 PhysicMaterial（支持 name/instanceId/path）。

参数	类型	必填	默认值	描述
materialPath	string	是	-	PhysicMaterial 的资源路径
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径

返回： { success, gameObject, material, collider } — material 是从碰撞体读取并解析出的资源路径，collider 是碰撞体组件的类型名称（例如 BoxCollider）。

physics_get_layer_collision

获取两个层是否会发生碰撞。

参数	类型	必填	默认值	描述
layer1	int	是	-	第一个层索引
layer2	int	是	-	第二个层索引

返回： { layer1, layer2, collisionEnabled }

physics_set_layer_collision

设置两个层是否会发生碰撞。

参数	类型	必填	默认值	描述
layer1	int	是	-	第一个层索引
layer2	int	是	-	第二个层索引
enableCollision	bool	否	true	是否启用碰撞

返回： { success, layer1, layer2, collisionEnabled }

---

最小示例

import unity_skills

# Raycast from position downward, check for hits
result = unity_skills.call_skill("physics_raycast",
    originX=0, originY=5, originZ=0,
    dirX=0, dirY=-1, dirZ=0,
    maxDistance=10
)
if result.get("hit"):
    print(f"Hit: {result['hitObjectName']} at distance {result['distance']}")

精确签名

精确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。

常见错误

完整的传输层错误代码（COMPILING/RATE_LIMIT 等）→ ../../references/protocol-error-codes.md

错误	触发条件	修复方法
SEMANTIC_INVALID	提供了无效值，例如零方向向量、包含路径分隔符的名称或超出范围的参数。	提供非零方向，从材质名称中移除路径分隔符，并将值限制在有效范围内。
TARGET_NOT_FOUND	目标 GameObject 没有 Collider，或无法加载请求的 PhysicMaterial 资源。	通过 component_add 添加碰撞体，或使用 asset_find 确认材质路径，然后重试。
MISSING_PARAM	缺少必需参数，例如 physics_create_material 中的 name。	提供错误中指出的参数；使用 mode=dryRun 查看架构。