webg

物理エンジンを使う

本章では、重力、衝突、反発、摩擦、回転、スリープを扱うwebgの物理エンジンを説明します。 CPU(Central Processing Unit:中央処理装置)版のPhysicsSpaceとCompute版(GPUで計算する版)のComputePhysicsSpaceは、bodyの位置、姿勢、速度、質量、材質と、Box、Sphere、Capsule、PlaneのColliderを同じ考え方で設定します。 まずCPU版でNodeと物理bodyを組み合わせる基本構成を学び、次にCompute版でGPU上の状態を通常のNodeへ同期する方法と、GPU状態を描画へ直接渡してCPU・GPU間の転送を減らす方法を確認します。

この章の読み方

この章を読む前に必要な知識

03章の位置・姿勢・回転と05章のWebgApp更新処理を知っていると読みやすくなります。物理学の専門知識は、webgのAPIを読み進める中で必要な範囲を学べます。

初回に読む範囲

PhysicsSpace、PhysicsNode、各Collider、床と箱の基本例を先に読んでください。

必要になったときに読む範囲

Joint、物理マテリアル、接触イベント、Compute版の描画方法は28章と合わせて参照してください。

この章を終えた時点でできること

bodyをPhysicsSpaceへ登録し、CPU(Central Processing Unit:中央処理装置)版またはCompute版の結果をNodeの表示へ接続できます。

物理エンジンが扱う動きを理解する

物理エンジンは、位置と速度を時間に沿って更新し、重力、衝突、反発、摩擦によって物体の動きを決めます。 本章では、PhysicsSpace、PhysicsNode、Colliderの役割を確認し、床と箱の最小例から、接触イベント、問い合わせ、コリジョンレイヤー、SceneYAMLによる設定へ進みます。

利用と内部実装の読み分け: 本章では床と箱の例からbody・Collider・材質の接続を学び、28章でイベント・問い合わせ・SceneYAML設定と更新順序へ進みます。OBB、SAT、接触点、慣性、ソルバーの式を調べる場合は、42章の内部実装を参照してください。

これまでの章では、Node、Space、Shape、SceneYAML、そしてレイキャストや衝突判定など、3Dシーンを構成するための基礎的な部品を扱ってきました。 これらを組み合わせることで、物体を表示し、ユーザー入力で動かし、境界ボックスによって重なりを調べる基礎的な機能は実装可能です。

しかし、より本格的なゲームやインタラクティブなシーンを構築しようとすると、座標指定による移動に加え、「重力で落下し、床に当たって跳ね返り、摩擦で停止し、他の物体と押し合う」といった自然な物理挙動へのニーズが生じます。 こうした挙動をアプリケーション側のコードで個別に実装すると、落下処理や衝突応答のロジックが各アプリへ分散します。物理エンジンへまとめると、共通の更新規則として再利用できます。

webgの物理エンジンは、こうした物理挙動を効率的に実現するための軽量な基盤です。 webgの物理エンジンは、外部の大規模な汎用物理エンジンとは用途を分け、webgのシーングラフと座標管理へ自然に統合できる、学習しやすく拡張しやすい剛体物理を提供します。

本章の目標は、物理エンジンが更新する位置・速度と、描画シーンが参照するNode transformのつながりを理解することです。 まず、PhysicsNode、PhysicsSpace、Collider の役割と基本操作を学びます。 次に、28章でSceneYAMLから物理オブジェクトを宣言する方法を確認します。 広域判定、詳細判定、ソルバーの内部計算を調べる場合は42章へ進みます。

物理エンジンが提供する価値

物理エンジンが必要になるのは、「視覚的な挙動」と「当たり判定の結果」を継続的に一致させたいときです。

たとえば、単純に箱を落下させるだけであれば、Node.move() や setPosition() を毎フレーム呼び出すだけで実装できます。 しかし、「床に当たった瞬間に停止させる」「反発係数に応じて跳ね返す」「斜め方向の速度を摩擦で減衰させる」「複数の箱が同時に接触した際に互いに押し戻す」といった処理を追加し始めると、単純な座標更新だけでは管理しきれなくなります。

また、通常の衝突判定(collision detection)やレイキャスト(raycast)は、「当たっているかどうか」を調べるための問い合わせAPIです。 15章で扱った Space.raycast() や Space.checkCollisions() は、物体の選択や重なり判定の結果を返す問い合わせAPIです。「当たった物体をどう押し戻すか」「速度をどう変化させるか」という物理的な応答(response)は、物理エンジンの更新処理が担当します。

物理エンジンは、以下のような一連の処理を統合的に管理します。

  1. 重力や速度に基づいた物体の位置更新(積分)。
  2. 接触候補となる物体ペアの抽出(ブロードフェーズ:広域判定)。
  3. 実際の接触法線とめり込み量の算出(ナローフェーズ:詳細判定)。
  4. めり込みを解消するための位置補正。
  5. 反発と摩擦による速度の変化(インパルス:衝撃量による応答)。
  6. 静止した物体を休止状態にし、必要に応じて復帰させる最適化。
  7. 接触イベントや問い合わせAPIを通じたアプリケーション側への通知。

webg の物理機能は、これらを PhysicsSpace と PhysicsNode を中心に構築しています。

物理エンジンの全体構成

全体構成を三つの系統へ分ける目的は、物体の状態、判定形状、シミュレーションの進行を独立して設定・交換できるようにすることです。 見た目を表すNodeへすべての処理を集めず、静的ボディと動的ボディの違い、コライダーの種類、物理空間全体の時間を別々に管理できます。 物理機能の中核となるクラスは次のように構成されます。

PhysicsNode は Node を継承しています。 これは webg における重要な設計上の特徴です。 物理オブジェクトも通常のNodeと同様に Space へ配置し、Shape を付与できるようにしています。 これにより、見た目の位置と物理的な位置を同一のオブジェクト上で管理でき、同期の手間を省いています。

ただし、物理更新中のダイナミック(dynamic)なボディに対して、スクリプトから自由に setPosition() を行うと、物理計算の結果と手動の座標更新が衝突します。 そのため、dynamic ボディでは通常のトランスフォーム書き換えを制限しています。 強制的に移動させたい場合は teleport() を、一時的に手動配置したい場合は pauseDynamic() / resumeDynamic() や setBodyType() を使用します。

PhysicsSpaceは、描画のためのSpaceとは異なる役割を持ちます。 Spaceがシーングラフと描画を管理するのに対し、PhysicsSpaceは固定時間刻み、重力、接触解決、スリープ管理、問い合わせ処理を扱う物理専用の空間です。 両者は分離されていますが、PhysicsNodeがNodeを継承していることで密接に連携しています。

Collider は、見た目の Shape とは独立して設定されます。 たとえば、見た目は球体として描画していても、物理判定は箱形にすることが可能です。 また、床の見た目は薄い箱であっても、物理判定は無限平面に設定することで、計算の安定性を高めることができます。

現在、次の4種類のコライダーが用意されています。

BoxCollider の場合、ブロードフェーズでは計算負荷を抑えるためにそのOBBを包むワールドAABB(軸平行境界ボックス)を使用し、ナローフェーズやクエリ、レイキャストでは向きを持つボックスとして厳密に判定します。

実装例:床と箱を落下させる

床と箱の最小例は、静的ボディ、動的ボディ、コライダー、重力、毎フレームのstep()という必須要素を、複雑なシーンから切り離して確認するために使います。 04章のHTMLのmodule scriptへ、次の初期化コードと後続の更新コードを続けて記述してください。例えばuser/physics_intro/physics_intro.htmlへ保存すると、ここに示す相対パスを使えます。

画面では箱がY=12から落ち、Y=0の平面へ接触して、反発と摩擦の設定に従って停止します。箱の高さは2なので、水平に接地したときの中心はY=1付近です。最初にこの構成を確認すると、後から追加する回転や接触イベントの影響を個別に調べられます。

import WebgApp from "../../webg/WebgApp.js";
import Shape from "../../webg/Shape.js";
import Primitive from "../../webg/Primitive.js";
import PhysicsSpace from "../../webg/PhysicsSpace.js";
import BoxCollider from "../../webg/BoxCollider.js";
import PlaneCollider from "../../webg/PlaneCollider.js";

const app = new WebgApp({ document, useMessage: false });
await app.init();
app.createOrbitEyeRig({
  target: [0, 3, 0], distance: 24, yaw: 20, pitch: -15,
  minDistance: 8, maxDistance: 40, wheelZoomStep: 1
});
const space = app.space;

const physics = new PhysicsSpace({
  gravity: [0.0, -9.8, 0.0],
  fixedTimeStepMs: 1000.0 / 120.0,
  solverIterations: 4
});

const floor = space.addPhysicsNode(null, "floor", {
  bodyType: "static"
});
floor.setPosition(0.0, 0.0, 0.0);
floor.setCollider(new PlaneCollider([0.0, 1.0, 0.0]));
floor.setPhysicsMaterial({
  restitution: 0.0,
  friction: 0.7
});
physics.addBody(floor);

// 無限の判定平面に合わせ、表示用の床の上面をY=0へ置く
const floorShape = new Shape(app.getGPU());
floorShape.applyPrimitiveAsset(Primitive.cuboid(16, 0.1, 16, floorShape.getPrimitiveOptions()));
floorShape.endShape();
floorShape.setMaterial("smooth-shader", { color: [0.2, 0.6, 0.5, 1] });
const floorVisual = space.addNode(null, "floor_visual");
floorVisual.setPosition(0, -0.05, 0);
floorVisual.addShape(floorShape);

const box = space.addPhysicsNode(null, "box", {
  bodyType: "kinematic",
  mass: 1.0,
  linearDamping: 0.2
});
box.setPosition(0.0, 12.0, 0.0);
box.setCollider(new BoxCollider([2.0, 2.0, 2.0]));
box.setPhysicsMaterial({
  restitution: 0.1,
  friction: 0.5
});
physics.addBody(box);

// 判定用の箱と同じ寸法のShapeを、物理位置を持つNodeへ取り付ける
const boxShape = new Shape(app.getGPU());
boxShape.applyPrimitiveAsset(Primitive.cube(2, boxShape.getPrimitiveOptions()));
boxShape.endShape();
boxShape.setMaterial("smooth-shader", { color: [1, 0.5, 0.3, 1] });
box.addShape(boxShape);

box.setBodyType("dynamic", {
  clearVelocity: false,
  restoreVelocity: false
});

ここで重要なポイントは、位置やコリジョンを設定した後に dynamic へ切り替えている点です。 dynamic に設定された後は、物理エンジン側がボディのトランスフォームを制御します。 初期配置を行う際は kinematic に設定しておくことで、通常の setPosition() を安全に使用できます。

毎フレームの更新処理では、描画の前に physics.step(deltaMs) を呼び出します。

app.start({
  // WebgAppの経過秒数をミリ秒へ換算し、描画の前に物理を進める
  onUpdate: ({ deltaSec }) => {
    physics.step(deltaSec * 1000.0);
  }
});

PhysicsSpace.step(deltaMs) は、内部で固定タイムステップに分割して stepFixed(dtSec) を呼び出します。 これにより、ブラウザのフレームレートが変動しても、物理挙動が不安定になるのを防いでいます。

Compute版の物理エンジン

CPU版とCompute版は、同じ物理法則を異なる実行場所へ接続する二つの経路です。 どちらもbody、Collider、材質、重力、固定時間刻み、接触、摩擦、反発、スリープを使って剛体を計算します。 違いは、主に物理状態をどこへ置き、どこで計算し、計算結果を描画へどのように渡すかです。

利用者が設定する物理項目と基本的な意味は、次のように対応しています。

共通項目 CPU版 Compute版
bodyの設定 位置、姿勢、速度、質量、材質 同じ
body種別 dynamic、kinematic、static 同じ
Collider Box、Sphere、Capsule、Plane 対応するComputeCollider
物理設定 重力、固定刻み、反発、摩擦、減衰 同じ意味
body操作 速度設定、力積、トルク、sleep/wake 同じ意味
物理計算 固定時間刻み、接触、摩擦、sleep 固定時間刻み、接触、摩擦、sleep

Compute版では、GPU上の固定長なBodyStateへ状態をまとめて配置するため、内部のデータ構造と接触候補の作り方をGPU向けに構成しています。 CPU版とCompute版では内部の演算順序や丸めが異なる場合がありますが、利用者が扱うbodyの種類、材質、速度、sleep/wakeの考え方は共通です。

CPU版ではPhysicsNodeが物理状態と描画用Nodeを兼ね、PhysicsSpace.step(deltaMs)がJavaScript側の状態を更新します。 Compute版では物理bodyをComputePhysicsSpaceへ登録し、encode(commandEncoder, deltaMs)でGPUコマンドへ固定stepを記録します。 ここで選ぶのは、同じ物理モデルを実行し、GPU計算と描画を同じコマンドエンコーダーへ記録する方法です。

Compute版の計算結果を通常のShapeとNodeへ反映する場合は、readback後にsyncNodeFromPhysics()またはsyncNodesFromPhysics()を呼び出します。 この構成では、利用者側の描画はCPU版に近いままです。 さらにCPUとの転送を減らして高速化したい場合だけ、GPU上のBodyStateを描画用WGSLから直接参照します。 この直接描画では、利用者が描画用WGSL、Storage Bufferのレイアウト、Computeと描画の順序を記述します。

したがって、最初はCPU版と同じ物理項目を設定し、Compute版では計算結果をNodeへ同期する方法から始められます。 body数が増え、readbackやNode同期が処理時間の問題になった場合にだけ、GPU状態を直接描画する構成へ進みます。

20〜22章への注記: 本節では、Compute版物理エンジン固有のAPI、処理段階、描画方法の選び方だけを説明します。WGSLの構文、ストレージバッファ、ピンポン方式、Compute Pass、WebgApp({ computeFrame: true })、GPU処理と描画を同じcommand encoderへ記録する方法は、20〜22章のコンピュート処理の解説で詳しく説明します。本節のコードを自分の描画処理へ拡張する場合は、20〜22章を参照してください。

Compute版が物理計算で行う処理

Compute版は、GPUで多数のbodyを同じ処理フローへ入れられるように、状態の配置と接触候補の作り方をCompute向けに再構成しています。 2本のBodyStateストレージバッファを交互に使い、一方を固定stepの入力、もう一方を出力として扱います。 固定stepが終わるたびに入力と出力を入れ替えるため、前の状態を読みながら同じ状態へ書き戻すデータ競合を避けられます。

1回の固定stepでは、次の順にGPU処理を記録します。

  1. 現在の位置と速度から、次の位置を含む予測AABBを作る。
  2. 予測AABBをXZ平面のGridへ登録し、Y方向の移動範囲(swept Y)も使って候補を絞る。
  3. bodyごとの候補bitsetをsolverの反復より前に一度だけ生成する。
  4. 候補bitsetを再利用し、形状ごとの接触計算と法線・摩擦・位置補正をcombined local solverで処理する。
  5. 線速度、角速度、接触支持、スリープカウンターを次のBodyStateへ書き込む。

候補bitsetをsolverの各反復で作り直さないため、接触候補の生成と接触応答の反復を分けられます。 この構成は、密集したbodyの候補を減らしながら、同じ候補を複数回の局所solverで再利用するためのものです。 スリープは固定stepをまたいでBodyStateに保持され、停止中のbodyはsleep状態のまま計算量を抑えます。 活動中のbodyからの接触、法線方向の速度、設定されたwakeしきい値など、明示されたwake条件を満たすと計算へ復帰します。

Compute版の初期化

Compute版では、まずWebgAppからGPUを取得し、そのGPUをComputePhysicsSpaceへ渡します。 bodiesにはposition、orientation、速度、bodyType、質量、ComputeBoxColliderなどを指定します。 idを指定する場合は正の整数を使い、readback後にどのNodeへ同期するかを明確にします。

import WebgApp from "./webg/WebgApp.js";
import ComputePhysicsSpace from "./webg/ComputePhysicsSpace.js";
import ComputeBoxCollider from "./webg/ComputeBoxCollider.js";
import ComputePlaneCollider from "./webg/ComputePlaneCollider.js";

const app = new WebgApp({
  computeFrame: true,
  autoDrawScene: false
});
await app.init();
const gpu = app.getGPU();

const physics = new ComputePhysicsSpace(gpu, {
  maxBodies: 200,
  maxPlanes: 1,
  bodies: [{
    id: 1,
    bodyType: "dynamic",
    position: [0.0, 12.0, 0.0],
    orientation: [1.0, 0.0, 0.0, 0.0],
    collider: new ComputeBoxCollider([2.0, 2.0, 2.0]),
    mass: 1.0,
    material: {
      restitution: 0.3,
      friction: 0.5,
      linearDamping: 0.2,
      angularDamping: 0.2
    }
  }],
  planes: [
    new ComputePlaneCollider([0.0, 1.0, 0.0], {
      planeDistance: 0.0
    })
  ],
  bounds: {
    minX: -8.0,
    maxX: 8.0,
    minZ: -8.0,
    maxZ: 8.0,
    floorY: 0.0
  },
  gravity: [0.0, -9.8, 0.0],
  fixedTimeStepMs: 1000.0 / 120.0,
  solverIterations: 8,
  persistentSleep: true
});

ComputePhysicsSpaceは、ここでGPUへ初期状態を転送します。GPU処理のエンコードと送信は、毎フレーム呼出側が担当します。 毎フレーム、呼出側がGPUCommandEncoderを作り、physics.encode(encoder, elapsedMs)で必要な固定stepを同じencoderへ記録し、描画処理と合わせてqueue.submit()します。 この分離により、Compute結果を同じフレームの描画へ渡す場合も、アプリケーション側が処理順序を確認できます。

app.start({
  onComputeFrame({ deltaSec }) {
    const encoder = gpu.device.createCommandEncoder();
    physics.encode(encoder, deltaSec * 1000.0);

    // ここへ通常の描画、またはBodyStateを読む描画用WGSLを記録します
    gpu.queue.submit([encoder.finish()]);
  }
});

この例のコメント部分に通常描画を追加する方法は20〜22章のcomputeFrameとCompute-firstの説明を参照してください。 実行可能な床と箱の例は、CPU版の最小例であるexamples/27_01.html、GPU計算結果を通常のNodeへ同期するCompute版の基本例であるexamples/27_02.html、CPUとGPU間の転送を削減できる高速化構成であるexamples/27_03.htmlで確認できます。

Compute版の状態を描画へ渡す2つの方法

Compute版の物理状態を描画へ渡す方法は、通常のNodeへ同期する方法と、GPU上の状態を直接読む方法に分かれます。 どちらも同じComputePhysicsSpaceの計算結果を使いますが、CPUを経由する場所と、利用者が用意する描画処理が異なります。

examples/27_02.htmlは、利用者側のWGSLを書かない方法です。 createStateReadbackBuffer()で読み戻し先を作り、encodeStateReadback()を同じcommand encoderへ記録し、submit完了後にreadStateReadback()でBodyStateを読み取ります。 その後、syncNodeFromPhysics()またはsyncNodesFromPhysics()で通常のNodeへ位置と姿勢を反映します。 通常のShape、Node、WebgAppをそのまま利用しやすい反面、GPUからCPUへのreadback、Nodeの更新、CPU側のトランスフォーム処理が発生します。 readbackは非同期なので、完了を待つ間も描画を止めない場合は、表示される状態が最新の固定stepより遅れることがあります。

examples/27_03.htmlは、利用者側で描画用WGSLを書く方法です。 getRenderState()は現在の状態バッファ、バッファ番号、body数、BodyStateの配置情報を返します。 getStateBuffers()を使って2本の状態バッファへあらかじめbind groupを作り、毎フレームのbufferIndexに対応するbind groupを選べば、CPUへ位置や姿勢を読み戻さずに頂点シェーダーから直接参照できます。 物理計算から描画までGPU上で続けられるため、body数が多い場合にreadbackとNode同期を省ける可能性があります。 ただし、body数が少ない場合の差は小さく、描画用WGSL、BodyStateのメモリ配置、Computeと描画の同期を利用者側で正しく記述する必要があります。 GPU状態を直接描画する方式は、CPUとの転送を減らせる構成です。実際の負荷は、物体数、描画方式、更新処理を揃えて測定します。

Compute版の診断情報とサンプル固有の追跡

Compute版の内部状態を調べる必要がある場合は、Space作成時にdiagnostics: trueを指定します。getDiagnosticBuffer()でGPU上の汎用diagnostic bufferを取得し、createDiagnosticReadbackBuffer()、encodeDiagnosticReadback()、readDiagnosticReadback()、getDiagnosticsFromReadback()を順に使うと、bodyごとのsleep flag、線速度・角速度、sleep counter、支持接触、wake判定、接触力積の要約を明示的に読み出せます。通常の描画や物理計算が暗黙にCPU readbackを行うことはなく、readbackのcopy、submit、mapのタイミングはアプリケーション側で決めます。

この汎用diagnosticはCore共通のbody状態、接触要約、solver情報を提供し、特定のサンプルに依存しない構成です。たとえばfalling_dominoesでB29〜B32の力積やB31の段階変化を追跡する場合は、samples/falling_dominoes/FallingDominoSleepDiagnostic.jsがCPUエミュレータのtraceとCoreの汎用diagnosticを組み合わせます。Coreの公開情報と、固定シナリオを調査するサンプル固有情報を分けて扱えます。

内部の入力検証、BodyStateへの格納、GPUリソースの生成、WGSL生成、読み戻し後の形状問い合わせの補助は、@internalとして実装内部へまとめています。利用者は公開APIのencode()、getRenderState()、明示的な読み戻し、物体への命令、接触の問い合わせを使います。内部バッファの配置はコアが管理します。

Compute版コライダーの種類と制限

Compute版のbodyへ渡せる有限形状は、ComputeBoxCollider、ComputeSphereCollider、ComputeCapsuleColliderです。 床や壁のような無限平面は、ComputePlaneColliderをplanes配列へ渡します。 Box、Sphere、Capsuleは相互の組み合わせとPlaneとの接触に対応します。

Compute版のBodyStateでは形状の中心をbodyのpositionへそろえます。CPU版のcolliderOffset.xyzに相当する追加移動量は、現在のGPUレイアウトの対象外です。 物体の大きさに依存するしきい値や許容値は、寸法の基準となるscale.referenceLengthと各比率でまとめて設定します。

Compute版を選ぶときの注意

Compute版は、GPU上で多数のbodyを同じ規則で更新し、その結果をGPU内で次の処理へ渡す用途に向いています。 一方、接触イベントをJavaScriptですぐ処理したい、レイキャストや問い合わせ結果をCPU側で使いたい、通常のシーングラフ操作を中心にしたい場合は、CPU版のPhysicsSpaceが単純です。 Compute版でもreadback後の接触、manifold、Plane接触、接触イベントを取得できますが、必要なタイミングで明示的にreadbackを記録する必要があります。 通常描画ではGPU上の状態を参照し、CPUで調べる場面では読み戻しを明示します。接触情報を使う目的とタイミングに合わせて選択してください。

Jointによる拘束

接触は物体が重なったときだけ働く一時的な拘束ですが、Jointは二つのbodyが離れていても、指定したanchorや軸の関係を保ち続ける拘束です。 ロープ、振り子、ドア、車輪、機械部品の結合は、Jointで物体間の物理的なつながりを表します。JointをPhysicsSpaceへ登録し、固定時間刻みの更新で計算します。 これにより、重力や接触とJointの位置関係を同じ物理更新の中で確認できます。

CPU版のJoint APIは、共通のJoint、制約行を表すJointConstraintRow、XPBDを実行するJointSolverと、種類別の四つの定義に分かれています。 DistanceJointはanchor間の距離1自由度、BallSocketJointはanchor位置3自由度、HingeJointはanchor位置3自由度と軸の向き2自由度、FixedJointは位置3自由度と相対姿勢3自由度を拘束します。 種類別の数式は各Jointがconstraint rowへ変換し、PhysicsSpaceはJointの種類を判定せず、同じrow solverを全Jointへ反復します。

import DistanceJoint from "./webg/DistanceJoint.js";

const ropeJoint = new DistanceJoint({
  bodyA: pivot,
  bodyB: bob,
  localAnchorA: [0.0, -0.5, 0.0],
  localAnchorB: [0.0, 0.5, 0.0],
  distance: 2.0,
  compliance: 0.0,
  collideConnected: false
});

physics.addJoint(ropeJoint);

compliance=0.0は硬い拘束、正の値は有限の柔らかさを表します。 solverはfixed stepのdtからalpha = compliance / dt²を作り、constraint rowごとにpersistent lambdaを保持して、 deltaLambda = (-C - alpha * lambda) / (effectiveMass + alpha)で補正量を求めます。 solver後はJoint参加dynamic bodyのfixed step開始・終了transform差からphysical velocityを再構成します。 これにより、位置だけをteleportして拘束方向の速度を次stepへ残す状態を避け、重力や接触で予測された運動とJoint補正後の状態を次のfixed stepへ接続します。 jointSolverIterationsとjointPositionCorrectionIterationsを増やすと、複数Jointのchainで上部の補正結果を下部へ伝えやすくなりますが、計算量も増えます。

collideConnected=falseを指定したJointでは、接続した二つのbody間の通常接触を抑止し、Jointの拘束だけを残します。 Jointへ接続されたbodyを削除するときは、先にphysics.removeJoint(joint)を呼びます。 Joint参加bodyのsleep / wakeは現在、enabled Jointの誤差をsleep中に無視しないためfixed step開始時にwakeする構成です。

Compute版ではCPUのPhysicsNode参照をGPUへ渡さず、Compute spaceのbody IDを使ってJoint descriptorを登録します。 Joint bufferはbodyごとのadjacency、A/B各側のoriented record、XPBD lambda、直近の誤差欄を一つのStorage Bufferへまとめます。 contact solverの後に独立したWGSL XPBD passを実行し、1 invocationが自分側のoriented recordだけを書き換えることで、JointのA/B更新を競合なしに進めます。 collideConnected=falseの場合はcandidate生成時点で通常接触を除外し、Joint拘束は別passで継続します。

const computeJointId = computePhysics.addJoint({
  type: "DistanceJoint",
  bodyAId: 1,
  bodyBId: 2,
  localAnchorA: [0.0, -0.5, 0.0],
  localAnchorB: [0.0, 0.5, 0.0],
  distance: 2.0,
  compliance: 0.0,
  collideConnected: false
});

computePhysics.encode(commandEncoder, elapsedMs);

Compute版はDistanceJoint、BallSocketJoint、HingeJoint、FixedJointの基本rowを共通bufferへpackします。 maxJoints、maxJointsPerBody、jointSolverIterationsは初期化時に容量と反復回数を固定し、容量超過や未登録body IDは例外にします。 getJointBuffer()はGPU bufferとlayout情報を返します。lambdaや誤差をCPUで確認する場合は、別の明示的な診断readback APIを使います。

Jointのmotor、limit、break条件はまだ実装範囲外です。

PhysicsNode の詳細仕様

bodyTypeは、重力と衝突応答で動く物体、アプリケーションから動かす物体、動かない環境を同じPhysicsSpaceへ安全に混在させるために選びます。 位置をソルバーとアプリケーションのどちらが更新するかを明示すると、床が重力で落ちたり、アニメーションで動かす足場がソルバーに上書きされたりするのを防げます。 PhysicsNodeには用途に応じて3種類のbodyTypeがあります。

各設定は、ソルバー(接触を解決する計算処理)の内部で、位置や速度を更新する方法を選びます。

以下は、演出中だけ物理挙動を停止させ、位置を調整する例です。

box.pauseDynamic({
  clearVelocity: true
});

box.setPosition(0.0, 16.0, 0.0);
box.setLinearVelocity(0.0, 0.0, 0.0);

box.resumeDynamic({
  clearVelocity: false,
  restoreVelocity: false
});

瞬時に再配置したい場合は、teleport() メソッドを使用します。

box.teleport([0.0, 20.0, 0.0], {
  keepVelocity: false,
  wakeUp: true
});

また、物体に対して力(Force)やインパルス(Impulse:衝撃量)を与えることも可能です。

box.applyForce([0.0, 30.0, 0.0]);
box.applyImpulse([4.0, 10.0, 0.0]);
box.applyTorque([0.0, 0.0, 120.0]);

applyForce()は次の固定時間刻みの積分で速度に反映されます。 applyImpulse()は瞬間的に速度を変化させ、applyTorque()は角速度を変化させる力となります。 接触解決では、接触点と局所座標の対角慣性を使います。 これにより、中心から外れた位置への衝撃が自然な回転へ変換されます。

角速度の単位と内部処理

PhysicsNodeが公開APIとして保持する角速度は、setAngularVelocity(x, y, z)、getAngularVelocity()、SceneYAMLのangularVelocityのいずれも度/秒です。 つまり、[0.0, 90.0, 0.0]は「1秒間にY軸まわりへ90度回る」角速度を意味します。

これは、Node の姿勢指定やサンプルコードで角度を度数法(度)として扱ってきた流れに合わせた仕様です。 利用者側では、トルクや回転速度を見た目と対応させやすくなります。

一方、物理計算の低水準な内部処理では、外積omega x rや慣性テンソルの式を扱います。 このような計算では、角速度を通常ラジアン/秒で扱う必要があります。 そのためPhysicsSpaceは、外部状態の度/秒と内部計算のラジアン/秒を明示的に変換しています。

姿勢積分では、角速度の大きさとfixed stepから回転角を求め、軸角形式の有限回転Δqを作ります。CPU版はPhysicsMath.buildDeltaQuaternionStep()、Compute版はWGSLのintegrateOrientation()で同じくΔq ⊗ qを計算します。Box専用の特別な姿勢積分や、Sphere・Capsuleだけ異なる一次近似は使わず、CPU版の全形状で同じ更新規則を共有します。

この単位変換を混同すると、見た目の回転速度が極端に大きくなったり、反対にスリープ判定が厳しすぎたりします。 たとえばsleepAngularThreshold: 0.5の単位は毎秒0.5度です。角速度をラジアンで扱う箇所では、この値をラジアンへ換算します。

コリジョンと物理マテリアル

Colliderと物理マテリアルは、見た目の細かいメッシュとは別に、判定の形、反発、摩擦をシミュレーションへ伝えるために使います。 単純な判定形状を選べば、外観を保ったまま接触計算を軽くでき、マテリアルを変えるだけで床、壁、跳ねる物体の挙動を調整できます。 Colliderは物理判定用の形状であり、見た目のShapeとは別に設定します。

body.setCollider(new SphereCollider(2.0));

各コリジョンの基本的な指定方法は以下の通りです。

new BoxCollider([width, height, depth]);
new PlaneCollider([0.0, 1.0, 0.0]);
new SphereCollider(radius);
new CapsuleCollider(radius, segmentLength);

BoxCollider、SphereCollider、CapsuleCollider は有限な形状であるため、AABBを返すことができます。 一方、PlaneCollider は無限平面であるためAABBを持たず、ブロードフェーズ(広域判定)では特殊形状として処理されます。

物理マテリアル(物理演算マテリアル)は、見た目のマテリアルとは別に設定します。

body.setPhysicsMaterial({
  restitution: 0.7,
  friction: 0.05
});

接触する2つのボディのマテリアルは、ソルバー(解決器)内部で組み合わせて使用されます。 基本的には、反発は大きい方の値を採用し、摩擦は平方根で組み合わせた値を採用します。 マテリアルが設定されていない場合は、PhysicsSpace の defaultRestitution と defaultFriction が適用されます。

PlaneColliderとBoxColliderの特殊な扱い

PlaneCollider と BoxCollider の組み合わせには特別な扱いがあります。 静的な PlaneCollider の restitution が 0.0 の場合、その平面は「跳ねない床」として扱われ、床との反発計算には床側の値を優先します。

これは長い箱や梁(beam)の安定性のためです。 箱の端が床に当たると、上向きの反発インパルスは中心から大きく外れた位置に作用します。 その結果、線形の跳ね返りではなく大きなトルクになり、床が跳ねないマテリアルであるにもかかわらず、梁が立ち上がって暴れ続けることがあります。 webg では、床側が明示的に restitution: 0.0 の plane-box 接触では、床の「跳ねない」という指定を優先します。

さらにplane-boxでは、箱の床面に十分近い複数頂点を、支持面を表す頂点群としてまとめます。 細長い箱や薄い板が床へ倒れ込む途中では、一時的に角1点だけがめり込んだように見えることがあります。 この状態も、面接触へ移る途中の頂点群として扱えます。 頂点群を作れた場合は、その極値点から複数の接点を構成し、単一点を支点にして立ち上がる挙動を減らします。

まとめ

PhysicsSpaceへPhysicsNodeを登録すると、位置、姿勢、速度、質量、コライダーを物理計算へ接続できます。利用者はまずCPU版でNode同期と接触の基本を確認し、必要に応じてCompute版へ進みます。Box、Sphere、Capsule、Planeの形状を同じ設定の考え方で扱い、Jointや接触イベントなど更新後の利用方法は28章で確認します。