unity-physics

このモジュールのスキルを呼び出す前に： 名前や説明から推測したパラメーターを使ってスキルを呼び出そうとしている場合は、いったん停止し、まずこのファイルを読むか、GET /skills/recommend?includeSchema=true を使ってスキーマを取得してください。recommend/schema からすでにパラメーターの定義を取得している場合は、そのまま dryRun に進めます。

トリガー

• レイを飛ばす
• 重なりを検査する
• コライダーを検索する
• 重力／物理設定を調整する
• レイを飛ばす、重なりを検査する、コライダーを検索する、重力／物理設定を調整する

物理スキル

エディター上での物理クエリ（レイキャスト／オーバーラップ）、重力、PhysicMaterial アセット、レイヤー衝突マトリックスを扱います。

動作モード

• 承認：クエリ系スキル（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 後はサーバーが一度の処理で実行し、結果を返します。
• 自動／バイパス：すべてのスキルを直接実行します。自動では AI が自己評価を行い、バイパスではすべて許可されます。
• このモジュールには Delete／PlayMode／Reload／高リスクのスキルは含まれません。バイパス専用のブロック項目もありません。
• 注意：すべてのスキルはエディタースレッドで同期実行されます。実際の物理シミュレーション（積分、衝突応答）が進行するのは Play mode のみです。このモジュールでは単一フレームのクエリとアセット／グローバル設定の書き込みだけを行い、シミュレーションは開始しません。

禁止事項（よくある誤った想定）：

• physics_add_rigidbody / physics_add_collider は存在しません → componentType に "Rigidbody"/"BoxCollider" などを指定して component_add を使用してください。
• 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, optional)：最大距離（デフォルトは 1000）。
• layerMask (int, optional)：レイヤーマスク（デフォルトは -1）。

戻り値： { hit: true, collider: "Cube", distance: 5.2, ... }

physics_check_overlap

球の範囲内にコライダーがあるか確認します。 パラメーター：

• x、y、z (float)：中心点。
• radius (float)：球の半径。
• layerMask (int, optional)：レイヤーマスク。

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 を設定します（名前／instanceId／パスに対応）。

パラメーター	型	必須	デフォルト	説明
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

2 つのレイヤーが衝突するかどうかを取得します。

パラメーター	型	必須	デフォルト	説明
layer1	int	はい	-	1 つ目のレイヤーインデックス
layer2	int	はい	-	2 つ目のレイヤーインデックス

戻り値: { layer1, layer2, collisionEnabled }

physics_set_layer_collision

2 つのレイヤーが衝突するかどうかを設定します。

パラメーター	型	必須	デフォルト	説明
layer1	int	はい	-	1 つ目のレイヤーインデックス
layer2	int	はい	-	2 つ目のレイヤーインデックス
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 を使用してください。