bevy-voxel-data

Bevy 0.19 — ボクセルデータ（RON、パレット、KTX2 アトラス）

このスキルを使用する場面

• 作成者が編集できるテキスト形式で、改造可能なブロックカタログを定義する場合。
• メッシュ生成時の高速な検索に備えて、BlockId（u16／u32）をキーとするランタイムパレットを構築する場合。
• すべてのチャンクで 1 つのマテリアルを共有できるよう、ブロックごとのテクスチャを 1 つのアトラスにまとめる場合。
• GPU に適した圧縮形式で配信するため、アトラスを KTX2 に切り替える場合。
• ランタイムのチャンクストレージ形式（フラット配列、RLE、パレット圧縮、ハイブリッド）を選ぶ場合。
• プロシージャルなワールド生成を最適化する場合：極値の境界チェック、ノイズのアップサンプリング、ノイズのキャッシュ、バイオーム間でのノイズ共有。
• 依存関係を導入する前に、Rust／Bevy のボクセルクレートのエコシステムと現状の不足点を調査する場合。

標準的なエンドツーエンドのフロー

1. RON でブロックを定義する（assets/blocks.ron）。id は変更不可のシリアライズ対象の識別子で、name は表示用テキストであり、変更できます。

(
    blocks: [
        ( id: "core:air", name: "Air", visibility: Empty ),
        ( id: "core:grass", name: "Grass", visibility: Opaque,
          faces: ( top: "textures/grass_top.png",
                   bottom: "textures/dirt.png",
                   side: "textures/grass_side.png" ) ),
        ( id: "core:stone", name: "Stone", visibility: Opaque,
          faces: ( all: "textures/stone.png" ) ),
    ],
)

2. Rust のコア型 — BlockCatalog は Bevy の Asset、Palette は Resource です。

pub type BlockId = u16;

#[derive(Debug, Deserialize, Clone, Eq, Hash, PartialEq)]
#[serde(transparent)]
pub struct StableBlockId(pub String);

#[derive(Debug, Deserialize, Asset, TypePath)]
pub struct BlockCatalog { pub blocks: Vec<BlockDef> }

#[derive(Resource, Default)]
pub struct Palette {
    pub by_id: Vec<PaletteEntry>, // dense, process-local BlockId
    pub by_stable_id: HashMap<StableBlockId, BlockId>,
}

#[derive(Clone)]
pub struct PaletteEntry {
    pub stable_id:  StableBlockId,
    pub name:       String,
    pub visibility: Visibility,
    /// Atlas tile per face: [−X, −Y, −Z, +X, +Y, +Z] (block-mesh order).
    pub face_tiles: [u16; 6],
}

3. パレットを構築する — 一意で安定した ID を検証し、カタログを走査して、各面のパスを AtlasIndex から検索し、密なランタイム BlockId 値を割り当てます。カタログの順序はこのランタイムレイアウトに影響する場合がありますが、永続化の契約ではありません。セーブデータやネットワーク形式には安定した ID を直接保存するか、独自の安定 ID パレットを含め、読み込み時にマッピングし直します。

4. アトラスをバインドする — StandardMaterial.base_color_texture にバインドし、メッシュ生成時に tile_x = tile_index % atlas_cols として頂点ごとの UV を計算します。

トピック

トピック	リファレンス
RON スキーマ全体、すべてのフィールド、serde のデフォルト、パーサーに関する注記	references/ron-schema.md
BlockDef／BlockFaces／Visibility 型、build_palette の全体、face_tiles のスロット規約	references/palette.md
KTX2 のパッキング、タイルサイズの予算、ミップマップの安全性を考慮したパディング、プラットフォームごとの BC7／ETC2／ASTC	references/ktx2-atlas.md
StandardMaterial のバインド、UV の計算式、頂点ごとの発光、サンプラー設定、アルファモード	references/atlas-binding.md
ランタイムのチャンクストレージ形式 — フラット配列、RLE、パレット圧縮、ハイブリッド — RAM 使用量の推定付き	references/storage-formats.md
プロシージャル生成のパターン — ノイズのアップサンプリング、バイオーム間の共有、極値の境界、キャッシュ	references/generation.md
Rust／Bevy のボクセルクレートのエコシステム調査（block-mesh、building-blocks、feldspar など）	references/ecosystem.md

注意点

• KTX2 はオプトインです。 Bevy は ktx2 Cargo フィーチャーで KTX2 をサポートします（3d バンドルではデフォルトで有効です）。サイズを削減した WASM ビルドでは、ktx2 と zstd を明示的に追加してください。BC7（デスクトップ）または ETC2／ASTC（モバイル）を使用してください。詳細は references/ktx2-atlas.md を参照してください。
• ランタイム BlockId は永続的な識別子ではありません。 現在のカタログに合わせて再構築される密なインデックスです。core:stone のような変更不可の名前空間付き ID を永続化し、重複を検証したうえで、読み込み時に現在のランタイムパレットへマッピングしてください。
• ミップレベルが 1 以上の場合、テクスチャのにじみが発生します。 各タイルの周囲に 2 ピクセルのパディングを追加するか、各スライスで clamp_to_edge を設定したテクスチャ配列に切り替えてください。詳細は references/ktx2-atlas.md および references/atlas-binding.md を参照してください。
• Translucent ブロックには別のドローコールが必要です。 2 つ目のマテリアルに AlphaMode::Blend を使用し、チャンクごとに別のメッシュバッチを用意してください。半透明の四角形は不透明な四角形と結合できません。
• リリースビルドでアトラスをランタイムにベイクしないでください。 コンテンツのビルド時にベイクスクリプトを実行し、.ktx2 と JSON インデックスをコミットして、起動時に両方を読み込んでください。

関連項目

• bevy-voxel-pipeline — face_tiles を受け取るメッシュ生成ステップです。
• bevy-voxel-runtime — 編集時の dirty 化、リビジョン、上限付きの再メッシュ、メッシュ／コライダーの適用について説明します。
• bevy-save-load — バージョン管理された永続化と安定 ID の移行について説明します。
• bevy-custom-assets — RON カタログローダーの実装について説明します。
• bevy-pbr-materials — アトラスを StandardMaterial に接続する方法について説明します。