ボクセルの世界を、
ブロック1個ずつ分解する。

第1章

このデモとは

「Minecraft みたいなゲームって、どう作られているの？」に、動くコードで答えてくれるサンプルです。

このデモは、Babylon.js ファミリーの新しい WebGPU 専用ランタイム Babylon Lite の公式リポジトリに含まれるサンプルの１つです。ブラウザの中に草原・森・砂漠・雪山・海のある世界が生成され、歩き回ってブロックを壊したり置いたりできます。時間が経つと夕焼けになり、夜には星空の下でグロウストーンが光ります。

プログラムとしての特徴は次の3点です。

第2章

あそびかた

コードを読む前に、まず遊んでみるのがいちばんの近道です。画面をクリックするとマウスが視点操作モードになります。

第3章

用語ミニ辞典

この先の章で出てくることばを先にまとめて紹介します。分からなくなったらここに戻ってきてください。

第4章

全体の地図

エントリポイントの minecraft.ts はたった 236 行。オーケストラの指揮者のように、実際の演奏（実装）は 23 のコンポーネントに任せています。

flowchart TD
    MAIN["minecraft.ts（236行）
ぜんぶの組み立てとフレームループ"]
    subgraph FEATURE["機能・ゲームロジック層 ─ 約1,860行"]
        direction LR
        CTRL["controls
操作と移動"]
        WSIM["water-sim
水の流れ"]
        FALL["falling-blocks
砂の落下"]
        MOBS["mobs
動物"]
        LGT["lighting
昼夜の司令塔"]
    end
    subgraph RENDER["描画・マテリアル層 ─ 約1,384行"]
        direction LR
        CR["chunk-renderer
チャンク出し入れ係"]
        MESH["mesher
三角形づくり"]
        VMAT["voxel-material
WGSLシェーダ"]
        ENV["sky / clouds /
particles / highlight"]
    end
    subgraph WORLDL["ワールド生成・照明層 ─ 714行"]
        direction LR
        WORLD["world
ブロック保管庫"]
        GEN["worldgen
地形の計算"]
        WLGT["world-light
明るさの計算"]
    end
    subgraph BASE["基盤層 ─ 476行"]
        direction LR
        BLK["blocks
ブロック図鑑"]
        NOISE["noise
決定論ノイズ"]
        UTIL["raycast / audio /
constants"]
    end
    MAIN --> FEATURE
    FEATURE --> RENDER
    RENDER --> WORLDL
    WORLDL --> BASE
  

矢印は「上の層が下の層を利用する」という依存の向きです。下の層ほど土台に近く、constants.ts（チャンクの寸法などを決める定数、わずか18行）と noise.ts は他に何も依存しません。逆に minecraft.ts は組み立てるだけで、ゲームのルールを1つも持っていません。この「薄い入口＋役割ごとの部品」という形は、大きなプログラムを読むときの目印になります。

第5章

起動の流れ

ページを開いてから世界が表示されるまで、プログラムは5つのステップを順番に進みます。

flowchart TD
    A["① エンジンとシーンを用意
createEngine / createSceneContext"]
    B["② テクスチャの台紙づくり
Kenney の PNG を fetch して1枚のアトラスに合成"]
    C["③ 世界と部品を生成
World・レンダラー・水・落下・動物・HUD…"]
    D["④ warmAround：準備運動
海を先に満たし、周囲13×13チャンクを一気にメッシュ化"]
    E["⑤ registerScene → startEngine
描画ループ開始！"]
    A --> B --> C --> D --> E
  

ポイントは④の warmAround() です。ふだんチャンクのメッシュ化は「1フレームに3個まで」という予算で少しずつ進みますが、最初の1回だけは予算を無制限にして、プレイヤーの周囲をぜんぶ作り切ってからループを始めます。おかげで、世界が虫食いのままチラチラ現れる「ポップイン」が起きません。

同時に、海の底に口を開けた洞窟へ先に水を流し込んでおきます（プリフラッド）。これをサボると、海中なのに空気で満たされた不自然な「乾いた穴」が最初のフレームに見えてしまうのです。

第6章

地形のつくりかた

担当：worldgen.ts（197行）と noise.ts（82行）。世界のすべては seed という1つの数字（このデモでは 1337）から計算されます。

flowchart TD
    S["seed と座標 (x, z)"] --> H["高さを決める
大陸＋丘＋細かい凸凹の3層ノイズ"]
    S --> T["気温と湿度を決める
べつの低周波ノイズ2枚"]
    H --> B["バイオーム判定
海・砂浜・砂漠・平原・森・雪"]
    T --> B
    B --> F["柱を下から積む
岩盤→石(鉱石まじり)→土→表面ブロック"]
    F --> C["洞窟をくり抜く
3Dノイズが濃い場所を空気に"]
    C --> W["海面より低ければ水を注ぐ"]
    W --> V["木とサボテンを植える"]
  

バイオームの決まりかた

高さと「気温・湿度」の2つのノイズから、上から順に条件を当てはめて決まります。

鉱石は深さで出やすさが変わります。ダイヤは深さ14未満でおよそ0.8%、金は22未満で1%、鉄と石炭はどこでも数%。洞窟は海面+8より深い場所だけに掘られるので、山の中腹に不自然な横穴が開くことはありません。

第7章

光のしくみ

担当：world-light.ts（317行）。洞窟に潜ると暗くなり、グロウストーンを置くと周りが照らされる。あの「Minecraft らしい光」の正体です。

各ボクセルは 0〜15 の明るさを2種類持ちます。空から届く「スカイライト」と、光るブロックが放つ「ブロックライト」です。光は1ブロック進むごとに1ずつ弱まりながら、波紋のように広がります（BFS）。この2つの値を1バイトに詰めて、チャンクごとにキャッシュします。

flowchart TD
    A["パスA：柱ごとに「空の見える床」を探す
上から見て最初の不透明ブロックの1つ上"]
    B["パスB：床より上を明るさ15で一括塗り"]
    C["影との境目のセルだけをBFSの出発点にする
まっ平らな地表は伝播不要なのでスキップ"]
    D["BFSで1ずつ弱めながら広げる
真下方向だけは弱まらない（日光の柱）"]
    E["中央チャンク分を切り出してキャッシュ"]
    A --> B --> C --> D --> E
  

さらに面白いのが _anyEmitters という1個のフラグです。自然の地形には光るブロックが1つも生成されないので、プレイヤーが初めてグロウストーンを置くまで、ブロックライトの計算はまるごとスキップされます。「起きないことは計算しない」──怠惰は美徳、という好例です。

第8章

ブロックが絵になるまで

数字の並び（ブロックID）が画面のピクセルになるまで、データは5つの部品をバケツリレーされます。

flowchart LR
    A["worldgen
ノイズから地形"] --> B["world
ブロックの保管庫"]
    B --> C["world-light
明るさを計算"]
    C --> D["mesher
見える面だけ三角形に"]
    D --> E["chunk-renderer
GPUへ登録"]
    E --> F["voxel-material
WGSLシェーダで着色"]
  

mesher：三角形をケチる職人

16×16×96 のチャンクには最大 24,576 個のブロックが入りますが、実際に描くのは「空気に触れている面」だけ（面カリング）。さらに各頂点に、周囲のブロック配置から計算した AO（隅の暗さ）を焼き込みます。芸が細かいのは、四角形を2つの三角形に割るとき、明るい頂点同士を結ぶ向きに対角線をひっくり返すこと。これで AO のグラデーションに折り目が出ません。

頂点カラーは4項目の「メモ用紙」

各頂点の色（RGBA）には、色ではなく計算結果のメモが詰められています。

voxel-material：1本のシェーダ、3つの顔

WGSL シェーダは1本だけ書かれていて、テンプレートの差し替えで3変種が生まれます。opaque（石や土。ふつうに描く）、cutout(葉やサボテン。透明部分を切り抜き、A フラグが立った葉だけ風に揺れる)、blend（水・ガラス・氷。半透明で、A フラグが立った水面だけ頂点が波打つ）。太陽の向きによる面の明暗はシェーダ側で毎フレーム計算するので、夕日が差すと西向きの面だけ赤く染まります。仕上げに距離に応じた霧をかけ、遠くのチャンクの生成境界を上手に隠します。

第9章

毎フレームの仕事

1秒間に約60回、決まった順番で世界が更新されます。順番そのものが設計です。

flowchart TD
    P["① player.update
移動・視線・壊す/置く"] --> S["② falling / water
砂の落下と水の流れ"]
    S --> Q["③ renderer.processQueue
新しいチャンクを3個までメッシュ化"]
    Q --> L["④ lighting.tick
太陽を少し動かし、空と材質の色を更新"]
    L --> M["⑤ mobs / clouds / particles
動物・雲・粒の更新"]
    M --> H["⑥ 空をカメラに追従・HUD更新"]
    H -.次のフレームへ.-> P
  

「予算」の一覧表

このデモの秘訣は、重い処理すべてに上限（予算）が設定されていることです。仕事が予算を超えたら、残りは翌フレームに持ち越します。

第10章

壊す・置くと何が起きる？

左クリックの一瞬に、5つのシステムが連鎖して動きます。ゲームで最も「密度の高い」瞬間です。

flowchart TD
    CLICK["左クリック"] --> RAY["raycast：視線の先のブロックを特定
最大7ブロック先まで、格子を1マスずつたどる"]
    RAY --> SET["world.setBlock(空気)
変更を「編集差分」として記録"]
    SET --> INV["光キャッシュを無効化
チャンクの境目なら隣も"]
    SET --> RM["remeshEdit：触れたチャンクを作り直し
境目なら隣も（AOが変わるため）"]
    SET --> WN["water.onBreak
穴に水が流れ込むかも？"]
    SET --> FN["falling：真上をチェック
砂や砂利なら落ちはじめる"]
    SET --> FX["粒エフェクト＋効果音
音はWebAudioでその場で合成"]
  

第11章

水と砂の物理

担当：water-sim.ts（331行）と falling-blocks.ts（260行）。どちらも「イベントが起きた場所だけ調べる」省エネ設計です。

水：1リングずつ広がる「世代」方式

flowchart LR
    E["ブロックを壊した/置いた"] --> Q["そのセルと隣6方向を
キューに積む"]
    Q --> S["0.2秒ごとに
今の世代をまとめて評価"]
    S --> N["新しく水になったセルの隣は
「次の世代」へ繰り越し"]
    N -.1ブロックの輪ずつ広がる.-> S
  

毎フレーム全部の水を調べるのではなく、変化が起きた場所の周りだけをキューに積み、0.2秒に1回「1世代」ずつ進めます。新しく水になったセルの影響はわざと次の世代に持ち越すので、海底に穴を掘ると水が1ブロックずつ輪になって迫ってくる、あの Minecraft らしい見た目になります。

横方向への広がりは「海面より下」に限定されているのもポイントです。おかげで氾濫は必ず壁と海面で止まり、世界の果てまで水が暴走することがありません。

砂と砂利：エンティティになって落ちる

支えを失った砂は、ブロックのデータから一度取り除かれて「落下中の小さな箱メッシュ」に変身し、重力で落ちて、着地した瞬間にまたブロックへ戻ります。コードのコメントには、ボクセルゲームの落下物にありがちな3大バグへの対策が明記されています。

第12章

動物たち

担当：mobs.ts（491行、最大のファイル）。牛・豚・羊・にわとりが草原をのんびり歩き回ります。

驚くべきことに、動物の画像素材は1枚もありません。胴体・頭・足という「箱」をコードで組み立て、単色の頂点カラーで塗っています。足は股関節（ピボット）を軸に前後へ振れるので、ちゃんと歩いて見えます。まさに Minecraft の動物のレシピそのものです。

専用シェーダの mob-material.ts は地形と同じ太陽・環境光で動物を照らしますが、1つだけ違いがあります。動物は向きを変えて回転するので、法線（面の向き）をワールド行列で変換してから光を計算するのです。地形のチャンクは絶対に回転しないためこの計算を省略できる──「なぜ地形側にはこの処理がないのか」の答えまでコメントに書かれています。

第13章

セーブ＆ロード

担当：save-load.ts（118行）。世界まるごとの保存なのに、ファイルは驚くほど小さくなります。

// セーブデータの中身、これで全部！
interface SaveData {
  v: 1;               // フォーマットのバージョン
  seed: number;       // 地形の「種」
  time: number;       // 時刻（0〜1）
  player: PlayerState;// 位置と視線の向き
  edits: number[];    // [x, y, z, ブロックID, ...] 編集した場所だけ
}

地形は seed から毎回同じものが計算できるので、保存する必要がありません。保存するのはプレイヤーが手を加えた差分だけ。1万個ブロックを積んでも、数値4個×1万＝わずか数百KBです。水の氾濫や動物の位置すら保存しません──読み込み後にルール通り再計算すれば同じ状態に戻るからです。

ファイル保存には新しい File System Access API を使い、対応していないブラウザ（Firefox や Safari）では自動的にダウンロード方式へ切り替わります。読み込み後は起動時と同じ warmAround() を呼び直すだけで、「水は満ちていてメッシュも完成している」という保証がそのまま再現されます。

第14章

3つの設計テーマ

4,669行を貫くのは、この3つの考え方です。自分のプロジェクトにもそのまま持ち帰れます。

第15章

ファイル一覧（全25ファイル）

コードリーディングのおともに。行数は目安として。

ファイル名は GitHub 上の該当ファイルへのリンクです（別タブで開きます）。