Unity Physics

besty0728/unity-physics

Run Unity physics queries and configure physics at editor time — raycasts, overlap checks, gravity, and physics settings. Use when casting rays, testing overlaps, querying colliders, or adjusting gravity/physics settings, even if the user just says "射线检测" or "物理设置". 执行 Unity 物理查询并在编辑器期配置物理(raycast、overlap 检测、重力、物理设置);当用户要发射射线、检测重叠、查询碰撞体、或调整重力/物理设置时使用。

2k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

1536

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/Besty0728/Unity-Skills --skill unity-physics

The instruction itself

17 sections, as written by the author

Physics Skills

Editor-time physics queries (raycast / overlap), gravity, PhysicMaterial assets, and layer collision matrix.

Operating Mode

Approval：查询类 skill（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）需用户 grant，grant 后服务端一步执行返结果。
Auto / Bypass：所有 skill 直接执行；Auto 走 AI 自我评估，Bypass 全放行。
本模块不含 Delete / PlayMode / Reload / 高危 skill，无 Bypass-only 拦截项。
注意：所有 skill 都在编辑器线程同步运行。真实物理模拟（积分、碰撞响应）仅在 Play mode 下推进；本模块只做单帧 query + 资产/全局设置写入，不会启动模拟。

DO NOT (common hallucinations):

physics_add_rigidbody / physics_add_collider do not exist → use component_add with componentType "Rigidbody"/"BoxCollider"/etc.
physics_simulate does not exist → physics simulation runs during Play mode; this module does not step the simulation
Raycast results use world-space coordinates

Routing:

For adding physics components → use component module
For physics material → use physics_create_material (this module)
For layer collision matrix → physics_set_layer_collision (this module)

Skills

`physics_raycast`

Cast a ray and get hit info.

Parameters:

originX, originY, originZ (float): Origin point.
dirX, dirY, dirZ (float): Direction vector.
maxDistance (float, optional): Max distance (default 1000).
layerMask (int, optional): Layer mask (default -1).

Returns: { hit: true, collider: "Cube", distance: 5.2, ... }

`physics_check_overlap`

Check for colliders in a sphere.

Parameters:

x, y, z (float): Center point.
radius (float): Sphere radius.
layerMask (int, optional): Layer mask.

`physics_get_gravity`

Get global gravity setting.

Parameters: None.

`physics_set_gravity`

Set global gravity setting.

Parameters:

x, y, z (float): Gravity vector (e.g. 0, -9.81, 0).

`physics_raycast_all`

Cast a ray and return ALL hits (penetrating).

|-----------|------|----------|---------|-------------|

| layerMask | int | No | -1 | Layer mask filter |

Returns: { count, hits: [{ objectName, instanceId, path, point, normal, distance }] }

`physics_spherecast`

Cast a sphere along a direction and get hit info.

|-----------|------|----------|---------|-------------|

| layerMask | int | No | -1 | Layer mask filter |

Returns: { hit, objectName, instanceId, point, distance }

`physics_boxcast`

Cast a box along a direction and get hit info.

|-----------|------|----------|---------|-------------|

| layerMask | int | No | -1 | Layer mask filter |

Returns: { hit, objectName, instanceId, point, distance }

`physics_overlap_box`

Check for colliders overlapping a box volume.

|-----------|------|----------|---------|-------------|

| x | float | Yes | - | Box center X |

| y | float | Yes | - | Box center Y |

| z | float | Yes | - | Box center Z |

| layerMask | int | No | -1 | Layer mask filter |

Returns: { count, colliders: [{ objectName, path, isTrigger }] }

`physics_create_material`

Create a PhysicMaterial asset.

|-----------|------|----------|---------|-------------|

Returns: { success, path }

`physics_set_material`

Set PhysicMaterial on a collider (supports name/instanceId/path).

|-----------|------|----------|---------|-------------|

| instanceId | int | No | 0 | GameObject instance ID |

Returns: { success, gameObject, material }

`physics_get_layer_collision`

Get whether two layers collide.

|-----------|------|----------|---------|-------------|

| layer1 | int | Yes | - | First layer index |

| layer2 | int | Yes | - | Second layer index |

Returns: { layer1, layer2, collisionEnabled }

`physics_set_layer_collision`

Set whether two layers collide.

|-----------|------|----------|---------|-------------|

| layer1 | int | Yes | - | First layer index |

| layer2 | int | Yes | - | Second layer index |

Returns: { success, layer1, layer2, collisionEnabled }

Minimal Example

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']}")

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.

How to use it

Copy the folder

Take besty0728/unity-physics from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.