Internal Modules

モジュール構成

Navara の Rust コードベースは、機能グループごとに整理された 40 以上のクレートで構成されています。各クレートは Bevy ECS Plugin として構造化されており、自身のシステム、コンポーネント、リソースを共有 ECS ワールドに登録します。この設計によりエンジンはモジュール化され、合成可能になっています。例えば、navara_wasm_api は 6 つのコアクレートのみを使用し、navara_wasm はそのすべてを統合します。このセクションでは、主要なモジュールカテゴリの概要を説明します。

コアシステム

エンジンの基盤は、ほぼすべての他のモジュールが依存する少数のコアクレートで構築されています。

navara_core は基本的な GIS 数学ユーティリティ、AABB 計算、楕円体計算を提供します。navara_math はベクトルと行列の演算、幾何学的計算、その他のコア数学型を扱います。これら 2 つのクレートが、すべての地理空間処理の数学的基盤を形成します。

navara_ecs は中央コーディネーターであり、Bevy ECS フレームワークをラップしてメインエンジンループを管理します。システム実行順序、コンポーネント登録、入力処理・タイル状態遷移・描画コマンド生成を含むフレームごとの状態更新を管理します。

navara_quadtree は LOD 管理のための階層的空間インデキシングを提供します。エンジン全体のタイル管理、空間クエリ、カリング操作に使用されます。

データ処理とフォーマットサポート

Navara は複数の地理空間データフォーマットをサポートしており、それぞれ専用のクレートで処理されます。

navara_layer はレイヤー階層とデータソース抽象化を管理し、基盤となるフォーマットに関係なく統一されたインターフェースを提供します。navara_tile はラスターおよびベクターデータのコアタイリングシステムを処理し、タイルリクエストのスケジューリング、キャッシング、LOD 管理を含みます。

フォーマット固有のクレートが解析を処理します：Mapbox Vector Tiles 用の navara_mvt、GeoJSON フィーチャーコレクション用の navara_geojson、3D Tiles タイルセット用の navara_cesium3dtiles、バッチ 3D モデル用の navara_b3dm、GLB/GLTF モデル用の navara_glb です。navara_parser はこれらのフォーマット固有パーサーを調整する統一解析インターフェースを提供します。

フィーチャーレンダリング

navara_feature はビルボード、3D モデル、ポイント、ポリゴン、ポリライン、テキストなどの高レベルフィーチャーレンダリング戦略を処理します。地理空間フィーチャーがレンダリング可能なジオメトリにどのように変換されるかを定義します。navara_feature_component は各フィーチャータイプの ECS コンポーネント定義を提供します。

navara_material はマテリアルシステム（マテリアル定義、シェーダーパラメータ、テクスチャ管理）を管理します。navara_geometry はメッシュ生成や空間計算などの幾何学的処理を扱い、martini は RTIN アルゴリズムを使用した高性能な地形メッシュ生成を提供します。

WASM モジュールとビルドパイプライン

Rust クレートは、それぞれ異なるユースケースをターゲットとする 3 つの個別の WASM モジュールにコンパイルされます。

navara_wasm は web/wasm/navara_engine/ にコンパイルされ、40 以上のすべてのクレートを含むフル 3D エンジンです。カメラ、レイヤー、フィーチャー、タイル、ECS システム統合を含む完全なエンジン API を提供します。@navaramap/three が通信するモジュールです。

navara_wasm_worker は web/wasm/navara_engine_worker/ にコンパイルされ、処理に特化したクレートを含みます。地形メッシュ構築やポリゴン/ポリラインバッチ処理など、CPU 負荷の高いバックグラウンドタスクのために Web Worker で実行されます。

navara_wasm_api は web/wasm/navara_engine_api/ にコンパイルされ、6 つのコアクレート（navara_core、navara_math、navara_camera など）のみを含みます。座標変換や数学的操作のための軽量でステートレスなユーティリティ関数を提供します。@navaramap/three-api が通信するモジュールです。

ビルドパイプラインは cargo-make によって管理され、厳密な順序に従います：まず Rust クレートを WASM にコンパイルし、wasm-bindgen で TypeScript バインディングを生成し、Web 依存関係をインストールし、TypeScript パッケージをビルドし、最後にサンプルとアセットを準備します。

WASM API 設計ポリシー

Navara は、WASM で生成されたクラスを公開 TypeScript API で直接公開しないという厳格なポリシーを適用しています。wasm-bindgen が生成するクラスには手動のメモリ管理要件があり、Rust がメモリを解放すると JavaScript の参照が無効になり、use-after-free エラーやメモリリークにつながります。

代わりに、@navaramap/three と @navaramap/three-api の公開関数は、プレーンな JavaScript オブジェクトまたは Three.js 型を入力として受け取り、内部で WASM オブジェクトを作成し、操作を実行し、結果をプレーンな JavaScript/Three.js 型に変換して返し、WASM オブジェクトを解放します。このラッパーパターンにより、利用者が WASM メモリを手動で管理する必要がなくなります。

NormalizeWASMClass<T> ユーティリティ型（@navaramap/core から提供）は、WASM クラス定義から free() メソッドを削除し、getter/setter ペアをプレーンなプロパティに変換することで TypeScript 型を導出するために使用されます。

サポートシステム

いくつかのクレートが、エンジンの残りの部分が依存するインフラストラクチャを提供します。

navara_camera は入力処理、射影行列、視錐台計算を備えた 3D カメラシステムを実装します。navara_input はマウス、キーボード、タッチ入力を処理します。navara_event と navara_event_store はシステム間通信のためのイベントバスを提供します。navara_data_requester はタイルやデータの読み込みのための HTTP リクエスト、データキャッシング、リクエストキューイングを管理します。

navara_buffer_store は効率的なリソース追跡のためのメモリプール管理とバッファアロケーションを処理します。navara_window はビューポート寸法とスクリーン座標計算を管理します。navara_occluder はレンダリングパフォーマンスのためのオクルージョンカリングを提供し、navara_fog は距離ベースの大気フォグエフェクトを実装します。