babylonjs

Babylon.js 8

クイックリファレンス

Babylon.js は、Web 向けの強力なオープンソース 3D エンジンです。バージョン 8 は WebGL2 と WebGPU をサポートしています。

座標系： 左手系（X＝右、Y＝上、Z＝前）。回転の単位はラジアンです。

NPM パッケージ：

• @babylonjs/core - エンジン、シーン、メッシュ、マテリアル、カメラ、ライト
• @babylonjs/gui - 2D／3D GUI コントロール
• @babylonjs/loaders - glTF、OBJ、STL ローダー
• @babylonjs/materials - 追加のマテリアルタイプ
• @babylonjs/inspector - デバッグ用インスペクター

ツリーシェイキング： バンドルを最小限にするには、深いパスからインポートします：

import { Scene } from "@babylonjs/core/scene";
import { Vector3 } from "@babylonjs/core/Maths/math.vector";
import { Color3, Color4 } from "@babylonjs/core/Maths/math.color";
import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { PBRMaterial } from "@babylonjs/core/Materials/PBR/pbrMaterial";
import { ArcRotateCamera } from "@babylonjs/core/Cameras/arcRotateCamera";

副作用インポート（エクスポートを参照せずに機能を有効化します）：

import "@babylonjs/core/Meshes/thinInstanceMesh";
import "@babylonjs/core/Rendering/edgesRenderer";
import "@babylonjs/core/Collisions/collisionCoordinator";
import "@babylonjs/loaders/glTF/2.0/glTFLoader";

最小限のシーン設定

import { Engine } from "@babylonjs/core/Engines/engine";
import { Scene } from "@babylonjs/core/scene";
import { ArcRotateCamera } from "@babylonjs/core/Cameras/arcRotateCamera";
import { HemisphericLight } from "@babylonjs/core/Lights/hemisphericLight";
import { Vector3 } from "@babylonjs/core/Maths/math.vector";
import { CreateSphere } from "@babylonjs/core/Meshes/Builders/sphereBuilder";
import { CreateGround } from "@babylonjs/core/Meshes/Builders/groundBuilder";

const engine = new Engine(canvas, true);
const scene = new Scene(engine);
const camera = new ArcRotateCamera("cam", 0, Math.PI/4, 10, Vector3.Zero(), scene);
camera.attachControl(canvas, true);
const light = new HemisphericLight("light", new Vector3(0, 1, 0), scene);
const sphere = CreateSphere("sphere", { diameter: 2 }, scene);
const ground = CreateGround("ground", { width: 6, height: 6 }, scene);
sphere.position.y = 1;

engine.runRenderLoop(() => scene.render());
window.addEventListener("resize", () => engine.resize());

主なパターン

PBR マテリアル（リアルなレンダリングで最も一般的）

const pbr = new PBRMaterial("pbr", scene);
pbr.albedoColor = new Color3(1.0, 0.766, 0.336);
pbr.metallic = 0.3;
pbr.roughness = 0.7;
// Optional: connect to environment for reflections
pbr.reflectionTexture = scene.environmentTexture;
mesh.material = pbr;

シンインスタンス（高性能なバッチ処理）

import "@babylonjs/core/Meshes/thinInstanceMesh";
const buffer = new Float32Array(16 * count);
for (let i = 0; i < count; i++) {
  Matrix.Translation(x, y, z).copyToArray(buffer, i * 16);
}
mesh.thinInstanceSetBuffer("matrix", buffer, 16, false);
mesh.thinInstanceBufferUpdated("matrix");

アセットの読み込み（glTF）

import "@babylonjs/loaders/glTF/2.0/glTFLoader";
const container = await BABYLON.LoadAssetContainerAsync("model.glb", scene);
container.addAllToScene();

オブザーバブルパターン（Babylon のイベントシステム）

scene.onBeforeRenderObservable.add(() => { /* per frame */ });
const observer = scene.onPointerObservable.add((info) => { /* pointer events */ });
scene.onPointerObservable.remove(observer); // unsubscribe

プロシージャルモデリング — アニメーション対応の階層構造

ジオメトリをアタッチする前に、各関節に TransformNode を配置してプリミティブから複雑なモデルを構築します。自由度ごとにピボットを 1 つ設け、ジオメトリのローカル位置を関節からのオフセットとして扱います。

const robotRoot = new TransformNode("robotRoot", scene);
const shoulderPivot = new TransformNode("shoulderPivot", scene);
shoulderPivot.parent = robotRoot;                  // pivot lives at the joint axis
const upperArm = CreateCapsule("upperArm", { height: 1.2, radius: 0.16 }, scene);
upperArm.parent = shoulderPivot;
upperArm.position.y = 0.6;                          // geometry sticks out from joint
// Animation later: shoulderPivot.rotation.y = ...  // rotates whole arm cleanly

ブーリアン演算（穴あけや溝の切削）には CSG2（Babylon 8）を使用します。回転対称なパーツ（ボトル、ハブ、柱）には CreateLathe を使用します。パスに沿ってスイープするパーツ（ケーブル、レール）には CreateTube または ExtrudeShape を使用します。[procedural-parametric-modeling.md](references/procedural-parametric-modeling

リファレンスファイル

特定のトピックについて詳しい API パターンを確認するには、以下のファイルを参照してください：

• core-concepts.md - エンジン／シーンの設定、カメラ、ライト、シャドウ、オブザーバブル、座標系
• meshes.md - メッシュビルダー、変換、TransformNode、インスタンス、シンインスタンス、クローン、マージ、ピッキング
• procedural-parametric-modeling.md - プリミティブからコードで高品質な 3D モデルを構築します。プリミティブの完全なカタログ（Lathe、Tube、Extrude、多面体、測地線、CSG2 ブーリアン、カスタム VertexData）、品質向上のテクニック（テッセレーション、ベベル、エッジ、マテリアルパレット）、および実例となるロボットアームを使った、アニメーション対応の親子／ピボット階層パターンを解説します。コードで複雑なモデルの構築を依頼された場合や、モデルをアニメーションさせる必要がある場合は、こちらをお読みください。
• materials.md - PBR、Standard、テクスチャ、環境／HDR、Node Material、Shader Material
• gui.md - AdvancedDynamicTexture、すべてのコントロールタイプ、コンテナー、レイアウト、イベント
• animation-loading.md - アニメーション API、グループ、イージング、スケルタルアニメーション、アセットの読み込み、AssetContainer
• performance.md - シーン／メッシュ／マテリアルの最適化、インスタンス化方式の比較、モニタリング、メモリ管理

オンデマンドドキュメント

リファレンスファイルに記載のないトピックについては、オンラインのドキュメントを取得してください：

• ドキュメントサイト： https://doc.babylonjs.com
• GitHub の raw Markdown： https://raw.githubusercontent.com/BabylonJS/Documentation/master/content/{path}.md
• doc-urls.md - すべてのドキュメントセクションの完全な URL マップ

特定のトピックを取得するには、URL マップでパスを確認してから、ドキュメントサイトの URL に対して WebFetch を使用するか、GitHub から raw Markdown を取得してください。

ライブドキュメントのみで扱われているトピック（リファレンスファイルにはありません）

• Physics V2（Havok）：/features/featuresDeepDive/physics
• WebXR／VR／AR：/features/featuresDeepDive/webXR
• ポストプロセスパイプライン：/features/featuresDeepDive/postProcesses
• Solid Particle System：/features/featuresDeepDive/particles/solid_particle_system
• 群集ナビゲーション：/features/featuresDeepDive/crowdNavigation
• Node Geometry（プロシージャル）：/features/featuresDeepDive/mesh/nodeGeometry
• Frame Graph：/features/featuresDeepDive/frameGraph
• Flow Graph：/features/featuresDeepDive/flowGraph
• Smart Filters：/features/featuresDeepDive/smartFilters
• Gaussian Splatting：/features/featuresDeepDive/importers（splat／ply形式）

よくある落とし穴

1. クォータニオンとオイラー角： mesh.rotationQuaternion を設定すると、mesh.rotation は無効になります。元に戻すには、mesh.rotationQuaternion = null とします。
2. 副作用のあるインポート： thin instances、エッジレンダリング、ローダー、衝突判定などの機能は、エクスポートを直接使用しない場合でも、そのモジュールをインポートする必要があります。
3. すべてを破棄する： Babylon.js は GPU リソースをガベージコレクションしません。メッシュ、マテリアル、テクスチャを使い終えたら、必ず .dispose() を呼び出してください。
4. マテリアルの共有： 共有マテリアルを変更すると、それを使用するすべてのメッシュに影響します。個別に変更するには、クローンを作成するか、新しいマテリアルを作成してください。
5. TransformNode と Mesh： グループ化や階層化には TransformNode を使用してください。空の Mesh オブジェクトは、視錐台の評価に CPU リソースを浪費します。
6. 左手座標系： glTF は右手座標系です。Babylon はインポート時に自動変換します。手動で座標を計算する場合は、調整が必要になることがあります。
7. アルファソート： 透明なメッシュでは、適切なレンダリング順序が必要です。mesh.alphaIndex またはレンダリンググループを使用してください。
8. Thin instance の制限： 表示・非表示は一括で切り替わり、境界ボックスは1つで、インスタンスごとのマテリアルもありません。個別の制御が必要な場合は、通常のインスタンスを使用してください。
9. ジオメトリを作成する前にピボットを設定する： アニメーションモデルをコードで構築する場合は、まずジョイントの TransformNode を作成して親にし、その後、ローカルオフセットを指定してジオメトリを子としてアタッチしてください。MergeMeshes の後からピボットを設定するのは困難です。階層が機能するようになってからマージしてください。
10. CSG2 のセットアップ： Babylon 8 の CSG2（Manifold を基盤とするブーリアン演算）を使用する前に、await InitializeCSG2Async() を一度呼び出す必要があります。また、ワールド空間で動作します。中間生成物である CSG2.FromMesh オブジェクトは WASM メモリを保持するため、必ず破棄してください。
11. 負のスケーリングは頂点の巻き順を反転させる： scaling.x *= -1 で階層をミラーリングすると、三角形の頂点の巻き順が反転し、裏面カリングが機能しなくなります。material.sideOrientation = Mesh.DOUBLESIDE を設定するか、ベイクし直して修正してください。