unity-physics

Unity Physics（Rigidbody / PhysX）

Unity 6.3 LTS に組み込まれた 3D 物理演算（PhysX）を使って、オブジェクトを移動させ、衝突させ、互いを検出します。FixedUpdate の使い方、トリガーと衝突のルール、衝突レイヤーを正しく理解しましょう。対象は Unity 6.3 LTS (6000.3) です。

Unity 6.3 LTS での名称変更： Rigidbody.velocity は Rigidbody.linearVelocity になりました（旧名称は非推奨です）。古いチュートリアルからコピーしたコードでは警告が表示されたり、コンパイルに失敗したりすることがあります。

使用する場面

• オブジェクトに物理的な動き（力、速度、重力）を与える場合、衝突やトリガーに反応させる場合、衝突レイヤーやマスクを設定する場合、地面チェックや視線判定のためにレイキャストする場合、またはジョイントでボディを接続する場合に使用します。
• シーンやプレハブに Rigidbody と Collider コンポーネントが含まれる場合に使用します。

使用しない場面： 2D 物理演算（Rigidbody2D、Collider2D）は別の API です。概念を応用できますが、型は異なります。エンジンをまたいだ操作感の調整（タイムステップ、ジッター、トンネリング）には physics-tuning を使用します。移動を制御する入力の読み取りには unity-input-system を使用します。

基本的なワークフロー

1. シミュレーション対象には Rigidbody を追加し、衝突対象には Collider を追加します。衝突には両方に Collider が必要で、少なくとも一方に Rigidbody が必要です。
2. 物理演算はすべて FixedUpdate で行います。Update で入力を読み取り、意図を保存してから、FixedUpdate で力を加える／linearVelocity を設定する／MovePosition を呼び出します。
3. ボディは Transform ではなく物理演算 API で移動します。AddForce、linearVelocity、または MovePosition を使用します。非キネマティックな Rigidbody の transform.position を設定してはいけません（テレポートが発生し、衝突解決が壊れます）。
4. 衝突とトリガーのどちらを使うか選びます。通常の衝突は動きを妨げ、OnCollisionEnter を呼び出します。Is Trigger にチェックを入れた Collider はすり抜けて、OnTriggerEnter を呼び出します。
5. レイヤーを使って相互作用を整理します。オブジェクトをレイヤーに割り当て、Layer Collision Matrix（Project Settings → Physics）を編集して、無関係なオブジェクト同士が衝突判定されないようにします。
6. Physics Debugger（Window → Analysis → Physics Debugger）で確認し、ジッターが発生していないか観察します。高速なオブジェクトが壁をすり抜ける場合は、Collision Detection モードを上げます。

パターン

1. FixedUpdate での力ベースの移動（速度上限付き）

using UnityEngine;

[RequireComponent(typeof(Rigidbody))]
public class Mover : MonoBehaviour
{
    [SerializeField] private float accel = 30f, maxSpeed = 8f;
    private Rigidbody _rb;
    private Vector3 _input;   // set from Update / input system

    private void Awake() => _rb = GetComponent<Rigidbody>();

    private void FixedUpdate()
    {
        _rb.AddForce(_input * accel, ForceMode.Acceleration);     // mass-independent accel
        // Unity 6.3 LTS: linearVelocity (was 'velocity'). Clamp horizontal speed.
        Vector3 flat = new(_rb.linearVelocity.x, 0, _rb.linearVelocity.z);
        if (flat.magnitude > maxSpeed)
        {
            flat = flat.normalized * maxSpeed;
            _rb.linearVelocity = new Vector3(flat.x, _rb.linearVelocity.y, flat.z);
        }
    }
}

ForceMode：Force（連続、質量の影響を受ける）、Acceleration（連続、質量の影響を受けない）、Impulse（瞬間的、質量の影響を受ける — ジャンプ）、VelocityChange（瞬間的、質量の影響を受けない）。

2. 衝突とトリガーのコールバック

// Solid hit: both have colliders, this one has a (non-kinematic) Rigidbody.
private void OnCollisionEnter(Collision col)
{
    Debug.Log($"Hit {col.gameObject.name} at {col.contacts[0].point}");
}

// Overlap: one collider has 'Is Trigger' = true. Requires a Rigidbody on at least one party.
private void OnTriggerEnter(Collider other)
{
    if (other.CompareTag("Pickup")) Destroy(other.gameObject);
}

3. レイヤーマスク付きレイキャストによる地面チェック

[SerializeField] private LayerMask groundMask;   // set to your "Ground" layer in the Inspector

private bool IsGrounded()
{
    // Cast a short ray down; only test colliders on groundMask.
    return Physics.Raycast(transform.position, Vector3.down, out RaycastHit hit,
                           1.1f, groundMask);
}

4. ボディを押し続けるキネマティックなプラットフォーム

// isKinematic Rigidbody: not driven by forces, but MovePosition interpolates and carries
// resting bodies correctly (unlike moving the Transform directly).
private void FixedUpdate() => _rb.MovePosition(_rb.position + Vector3.right * (2f * Time.fixedDeltaTime));

注意点

• Unity 6.3 LTS には Rigidbody.velocity がありません — linearVelocity を使用してください（angularVelocity は変更ありません）。
• 動的な Rigidbody に transform.position を設定する — テレポートし、衝突判定をスキップします。MovePosition（キネマティック／補間）を使用するか、力を加えてください。Transform を直接変更する場合、物理クエリ（Raycast、OverlapSphere）では次の物理ステップまで古い位置が参照されます。同じフレーム内でクエリを実行する前に Physics.SyncTransforms() を一度呼び出してください。毎フレーム呼び出してはいけません。
• CharacterController では OnCollisionEnter が呼び出されません — CharacterController.Move は Rigidbody システムを経由しないため、代わりに OnControllerColliderHit(ControllerColliderHit) を使ってヒットを通知します。「修正」するために Rigidbody を追加しないでください。この 2 つは相互に排他的な移動モードです。
• Physics.Raycast はデフォルトでトリガーを無視します — QueryTriggerInteraction.Collide を渡す（またはグローバル設定 Physics.queriesHitTriggers／Project Settings → Physics → Queries Hit Triggers を切り替える）必要があります。レイの開始点が対象のコライダーの内側にある場合も、false を返します。
• 静止中の Rigidbody は、接地しているオブジェクトを移動または無効化してもその場に留まります — Sleep Threshold を下回ると、剛体はスリープ状態になります。衝突と AddForce は自動的にスリープを解除しますが、Transform を介して静的コライダー（Rigidbody なし）を移動しても解除されないことがあります。そのため、床が滑り去ると木箱が空中に浮いたままになります。影響を受ける剛体に Rigidbody.WakeUp() を呼び出してください。
• Update で力を加える — フレームレートに依存し、動きが不安定になります。物理処理は FixedUpdate で行ってください。
• トリガーコールバックが呼び出されない — トリガーには、2 つのコライダーの少なくとも一方に Rigidbody が必要で、両方のコライダーが有効でなければなりません。静的なトリガー同士では重なりが通知されません。
• 高速なオブジェクトが壁をすり抜ける（トンネリング） — Rigidbody の Collision Detection を Discrete より高い設定にしてください。Continuous は静的コライダーのみに対してスイープする点に注意してください（ほかの動的剛体に対しては Discrete にフォールバックします）。Continuous Dynamic は、ほかの連続動的剛体に対してもスイープします。Continuous Speculative はすべての対象に対して機能し、より低コストです。弾丸には、コライダーの代わりに軌道に沿った SphereCast／Raycast も検討してください。
• 不均一にスケーリングされた MeshCollider や、スケーリングされたコライダーは正常に動作しないことがあります。プリミティブコライダーを優先し、スケールを均一に保ってください。
• 移動する剛体に凹形状の MeshCollider を付ける — メッシュコライダーはデフォルトで凹形状であり、凹形状のものは静的またはキネマティックにしかできません。また、凹形状のコライダー同士はまったく衝突しません。動的な Rigidbody では、MeshCollider の Convex を有効にするか、プリミティブから複合コライダーを作成してください。
• あらゆるものがあらゆるものと衝突する — コストの無駄です。レイヤーを割り当て、Layer Collision Matrix を整理してください。

参考資料

• レイキャストのバリエーション（SphereCast、RaycastAll、OverlapSphere、LayerMask のビット演算）やジョイント（FixedJoint、HingeJoint、ConfigurableJoint、破壊可能なジョイント）については、references/raycasting-and-joints.md を参照してください。
• 主なドキュメント：Unity Manual の「Physics」セクション、および ScriptReference/Rigidbody、ScriptReference/Physics.Raycast。追加の注意事項については、ScriptReference/CollisionDetectionMode、ScriptReference/Physics-queriesHitTriggers、ScriptReference/MonoBehaviour.OnControllerColliderHit、ScriptReference/Physics.SyncTransforms、ScriptReference/Rigidbody.WakeUp、および Manual の「Introduction to rigid body physics」（スリープ）と「Introduction to Mesh colliders」（凹形状と凸形状）の各ページを参照してください。

関連スキル

• physics-tuning — エンジンに依存しない挙動の調整：固定タイムステップ、質量／抵抗、CCD、安定性。
• unity-csharp-scripting — これらのパターンが前提とする FixedUpdate／Update の使い分け。
• unity-navmesh — 力による移動を伴わないエージェントの移動。