bevy-voxel-runtime

Bevy 0.19 — 本番向けボクセルランタイム

このスキルを使う場面

• 編集がセクション境界をまたぐ、または AO／ライティングのハローサンプルに影響する場合。
• 新しい編集やアンロード／再ロードの後に、バックグラウンドの再メッシュ結果が届く可能性がある場合。
• メッシュ／コライダーのアップロード、キューの増加、または表示セクションの遅延によってフレームスパイクが発生する場合。
• プロトタイプで、編集のたびに AsyncComputeTaskPool タスクを 1 つずつ生成している場合。

ブロックカタログとメッシャーが正しくなった後に、このスキルを使ってください。編集、バックグラウンドでのメッシュ生成、メインスレッドでの表示の間のランタイム契約を担います。ワーカーの結果はあくまで提案であり、ワールドのリビジョンによって引き続き受け入れられる必要があります。

標準パターン

use bevy::prelude::*;
use std::collections::{BinaryHeap, HashMap, VecDeque};

#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
struct SectionCoord { x: i32, y: i32, z: i32 }

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
struct WorkToken {
    coord: SectionCoord,
    revision: u64,
    epoch: u64,
}

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
enum WorkState {
    #[default]
    Idle,
    Queued,
    Running,
    RunningAndDirty,
    Ready,
}

#[derive(Resource, Default)]
struct RemeshRuntime {
    state: HashMap<SectionCoord, WorkState>,
    latest: HashMap<SectionCoord, WorkToken>,
    queued: BinaryHeap<PriorityEntry>,
    completed: VecDeque<MeshResult>,
}

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
struct PriorityEntry {
    // Include the token or queue generation so obsolete heap entries can be skipped.
    priority: i64,
    queue_generation: u64,
    token: WorkToken,
}

struct MeshResult {
    token: WorkToken,
    mesh: MeshPayload,
    collider: ColliderPayload,
}

struct MeshPayload;
struct ColliderPayload;

ワーカーの入力には、セクションと必要なハローを含む不変のスナップショットを保持させてください。バックグラウンド処理中に ECS の借用、アセットの借用、ワールドロックを保持してはいけません。

注意点と不変条件

1. メッシャーが実際に読み取るステンシルから、ダーティ化の範囲を導き出してください。内部の編集では 1 つのセクションがダーティになります。面の境界での編集では、直交する隣接セクションもダーティになります。アンビエントオクルージョン、スムーズライティングなど、ハローの読み取りによっては、辺や角で隣接するセクションも必要になることがあります。
2. 各セクションに単調増加するコンテンツリビジョンとライフサイクルエポックを割り当ててください。各ジョブと結果にその両方を記録してください。座標だけで有効性を判定してはいけません。
3. セクションごとに、キュー待ち、実行中、結果保留のいずれかの処理意図を最大 1 つにしてください。実行中のジョブに対して編集が行われた場合、そのセクションを再びダーティにします。同等のジョブを新たに生成してはいけません。
4. ワーカーの起動数、完了結果の保管数、メッシュ／コライダーの適用数、アップロードのバイト数、適用時間に上限を設けてください。スレッドプールはバックプレッシャーの代わりにはなりません。
5. 表示状態を置き換える直前に、リビジョンとエポックを再確認してください。古い結果は却下し、その数を記録してください。古いタスクに新しい編集を上書きさせてはいけません。
6. 受け入れたリビジョンのメッシュと対応するコライダーは、まとめて切り替えてください。リビジョン N のジオメトリを表示しながら、衝突判定が N-1 のままにならないようにしてください。

ランタイムの流れ

edit -> compute dirty footprint -> bump revisions -> coalesce queue intent
     -> priority scheduler -> bounded task starts -> completed-result queue
     -> validate token -> bounded main-thread upload -> mesh+collider swap
                                      \-> stale reject + metric

• 編集の収集とダーティ化を、明示的に順序付けしたシミュレーションセットで実行してください。
• ワーカースロットが空いたときだけスナップショットを作成してください。それ以外の場合は、タスク入力を割り当てずに、キュー内の編集を引き続き統合します。
• 衝突判定が重要な表示中のセクション、近い順に並べた表示中のセクション、画面外の作業の順に優先してください。遠方の作業がいつまでも処理されないことを防ぐため、経過時間も考慮してください。
• 計測したフレームごとの予算内で、Update／PostUpdate、または排他的システムを使ってアップロードを適用してください。GPU アセットの作成はワールドのメインスレッドで行う処理であり、ワーカーの処理ではありません。
• アンロード／再ロード後にタスクが完了した場合、新しいセクションのリビジョン番号がたまたま同じでも、エポックの不一致によって結果を却下できます。

該当する詳細ガイドを選ぶ

問題	参照先
ダーティ化の範囲、ハローのセマンティクス、リビジョンとライフサイクルトークン	ダーティ化とリビジョン
統合、優先度ヒープ、タスクの所有権、キューの上限	キューと優先度
古い結果の却下、表示状態のアトミックな切り替え、診断	適用とテレメトリ

本番環境向けレビューのチェックリスト

• 境界での編集によって、変更されたサンプルをメッシュが読み取るすべてのセクションが再メッシュされる。
• 同じ座標でのアンロード／再ロードによって、以前の結果が無効になる。
• 1 つのセクションに対する 1,000 件の編集が集中しても、1,000 個のタスクではなく、上限内の作業が生成される。
• 古い結果がメッシュ、コライダー、リビジョン、準備完了状態を変更できない。
• 未処理作業の追いつき処理が、件数とバイト数／時間の両方の予算を守る。
• 表示中の衝突判定の欠落が、遠方の見た目上の作業より優先される一方で、後者が永続的に処理されない状態にならない。
• キューの深さ、経過時間、タスクの遅延、古い結果の数、統合された数、アップロードのバイト数、受け入れたリビジョンを、代表的なビルドで確認できる。

関連項目

• bevy-voxel-data — 安定したシリアライズ済みブロック ID と高密度なランタイムパレット。
• bevy-voxel-pipeline — メッシュ生成と block-mesh-rs。
• bevy-diagnostics-profiling — 診断、スパン、プラットフォームごとの予算。
• bevy-physics — コライダーの所有権と物理演算のスケジューリング。