ブロックで作って、
その世界を歩きまわる。

第1章

このデモとは

「ブロックを置いて世界を作って、その中を自分で歩けたら楽しいよね？」を、そのまま動くコードにしたサンプルです。

このデモは、Babylon.js ファミリーの WebGPU 専用ランタイム Babylon Lite の公式リポジトリに含まれる、Sandblox（サンドブロックス）です。名前のとおり「サンドボックス（自由に遊べる砂場）」＋「ブロック」。緑の大きな土台（ベースプレート）の上に、スタッド（丸い突起）付きのブロックを置き、動かし・伸ばし・複製し・塗り・壊し——そして四角い人形になって、作ったばかりの世界を歩いて跳んで確かめられます。作った世界はブラウザに自動保存され、ファイルとして書き出し／読み込みもできます。

プログラムとしての見どころは、次の3点です。

第2章

あそびかた

コードを読む前に、まず触ってみるのがいちばんの近道です。「歩く操作」と「作る操作」の2系統があります。

歩く（キャラクター操作）

作る（ビルドツール）

第3章

用語ミニ辞典

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

第4章

全体の地図

エントリの sandblox.ts は、エンジン・空・光を用意し、「ワールド」「キャラクター」「ツール群」の3つを組み立てて描画を回します。

flowchart TD
    ENTRY["sandblox.ts
エンジン・シーン・空・光"]
    subgraph WORLD["ワールド（作られる側）"]
        direction LR
        WS["workspace
全パーツの台帳"]
        PART["part
1個のブロック"]
        REND["part-renderer
一括描画"]
        STUD["stud-*
突起の質感"]
    end
    subgraph PLAYER["キャラクター（遊ぶ側）"]
        direction LR
        CHAR["character
四角い人形"]
        PC["player-controller
歩く/跳ぶ/カメラ"]
    end
    subgraph BUILD["ツール（作る道具）"]
        direction LR
        TB["toolbar
5ボタン"]
        TM["tool-manager
1つだけ有効"]
        TOOLS["move/clone/resize
paint/delete"]
    end
    ENTRY --> WORLD
    ENTRY --> PLAYER
    ENTRY --> BUILD
    PART --> REND
    REND --> STUD
    TOOLS --> WS
    PC --> WS
  

矢印は「上が下を利用する」向きです。中心にいるのは workspace.ts——世界にある全パーツの唯一の台帳です。ツールは「クリックした先に何があるか」をここに問い合わせ、キャラクターは「どこにぶつかるか」をここから受け取ります。作る側と遊ぶ側が、この1枚の台帳を通してつながっています。

第5章

起動の流れ

ページを開いてから世界が現れるまで、sandblox.ts は次の順で準備を進めます。

flowchart TD
    A["① エンジンとシーンを用意
空色 (0.58, 0.79, 0.98)"] --> B["② 光と影・空のスカイボックス"]
    B --> C["③ 台帳(workspace)と描画器(part-renderer)"]
    C --> D["④ ベースプレート 512×16×512 を1枚置く"]
    D --> E["⑤ 保存データを復元
無ければ default-map.json を取得"]
    E --> F["⑥ 四角い人形を組み立て・影に登録"]
    F --> G["⑦ ツール群とツールバーを配線"]
    G --> H["⑧ PlayerController を起動しループ開始"]
  

特徴的なのは④と⑤です。足場の緑の板は特別扱いではなく、「ロックした大きな Part を1枚置くだけ」。そして⑤で、前回ブラウザに保存した世界があればそれを復元し、なければリポジトリ同梱の default-map.json をネット越しに取ってきて並べます。URL に ?fresh=1 を付けて開くと保存を消して初期マップから始められます。

第6章

パーツという単位

担当：part.ts。この世界にあるものは、キャラクターと空をのぞいて全部これです。

Part が持つのは、大きさ size・位置 position・回転 rotation（クォータニオン）・色 color・ロック状態 locked だけ。あらゆる変更は必ず setSize / setPosition / rotate90 / setColor といった専用の入口を通り、その中で「描画器に新しい姿を書き込む」「変更を通知する」の2つを確実に行います。データと表示がズレない、いちばん基本の作法です。

生まれるとき Part は、描画器に「1枠ください」と allocInstance で場所を確保し、workspace（台帳）に自分を登録します。消えるとき（destroy）は逆に、枠を返し台帳から抜けます。この登録・解除の対称性が、何百個のブロックを破綻なく出し入れできる秘密です。

第7章

一気に描くしくみ

担当：part-renderer.ts（334行）。何百個のブロックを、たった数回の描画命令で出す心臓部です。

コツは thin instancing。単位立方体のメッシュを1つだけ用意し、それを「位置・回転・大きさ」の行列と「色」を差し替えながら大量に複製します。ブロックが100個あっても、送るのは100個ぶんの行列と色の配列だけ。描画命令の数はブロック数に左右されません。

このデモは用途別に3つのプールを分けています。混ぜないことで影の計算が破綻しないよう工夫しています。

アルファ値に「面の向き」を隠す

各インスタンスは 16個の行列＋RGBAの色を持ちます。ここで面白いのが、色のアルファ（A）は透明度ではなく「どの面が上か」を表す点。(面番号 + 0.5) / 8 という式でこっそり埋め込み、シェーダ側がこれを読んでスタッドを描く面を決めます（番号6＝スタッドなし）。使っていないチャンネルに情報を相乗りさせる、賢いパッキングです。

// 上向きの面を、色のアルファに符号化して忍ばせる
// 面番号 0:+X 1:-X 2:+Y 3:-Y 4:+Z 5:-Z、6以上=スタッドなし
alpha = (faceIndex + 0.5) / 8;

もう一つの地味な要は枠の使い回し。ブロックを消すと、内部では「最後の枠を空いた場所へ詰める」入れ替え方式で穴を埋めます。このとき色の配列も一緒に詰め替え、外から見える番号（ハンドル）は変わらないよう対応表を更新——だから途中でどれを消しても、他のブロックの参照が壊れません。

第8章

スタッドの質感

担当：stud-texture.ts と stud-material-plugin.ts。あの「丸い突起」を、テクスチャ1枚とシェーダで作ります。

まず stud-texture.ts が、突起1個ぶんの小さなタイル（64×64 ピクセル）をコードで描き起こします。丸角四角の SDF（符号付き距離関数）から「高さの地図」を作り、そこから2枚を生成——平らな面よりわずかに明るいグレーの色テクスチャ（下地の明るさ 0.82／突起の頂上 1.0）と、傾きを表すノーマルマップ。継ぎ目なく敷き詰められるよう、端は反対側を参照して計算しています。

次に stud-material-plugin.ts が、共有マテリアルの標準シェーダに WGSL の断片を差し込みます（マテリアルプラグイン）。第7章でアルファに隠した「上向きの面番号」をここで復号し、その面が本当に上を向いているか（法線との内積が 0.995 以上か）を確かめて、スタッドの色と法線を合成。90°刻み回転なので、面が必ずワールドの軸に一致する——だから面ごとの向きのテーブルが正確に効きます。ブロックを倒せばスタッドも一緒に横を向きます。

第9章

光と空

担当：lighting.ts と world.ts。晴れた屋外の空気感を、2灯＋空でつくります。

影は動く世界に合わせて毎フレーム描き直す設定です（forceRefreshEveryFrame）。誰がその影を落とすかは setShadowCasters で登録——キャラクターの全メッシュと、ブロック用・斜面用の描画メッシュが対象です。巨大なベースプレートを影の“落とす側”から外しているのは、それを入れると影の範囲が広がりすぎて解像度が無駄になるからです。

第10章

ブロック人間

担当：character.ts（647行・最大のファイル）。あの四角い人形を、角を丸めた箱と円柱だけで組み立てます。

このファイルは「形を作るだけ」で、動きは一切持ちません。土台（root）は足元＝高さ0にあり、そこから各パーツを積み上げます。腕と脚は「ピボット（回転の支点）」からぶら下げ、少し下にずらして取り付けることで、肩・股から振り出せるようにしています。

顔は 128×128 のキャンバスにコードで描いた笑顔テクスチャ。白を透明に抜き、黒で目（楕円）と口（二次曲線のスマイル）を描き、頭の正面に貼ります。すべての箱・円柱は角を bevelRadius 0.05 でわずかに丸め、輪郭にやわらかい光の線を出しています。

第11章

歩く・跳ぶ・見まわす

担当：player-controller.ts が、入力・物理・移動・アニメ・カメラの5つの部品をまとめ、毎フレームの処理順を仕切ります。

flowchart LR
    IN["input
キー/マウス"] --> PH["physics
重力/ジャンプ/着地"]
    PH --> MV["movement
水平移動/衝突/段差"]
    MV --> FS["footstep
足音"]
    FS --> AN["animation
手足を動かす"]
    AN --> CAM["camera
視点を更新"]
  

この順番には意味があります。先に上下（重力・着地）を解決してから左右（水平移動・衝突）を処理し、カメラは最後に確定した位置を追う。1フレームの経過時間は最大 0.05 秒に頭打ちして、重い瞬間でもすり抜けないようにしています。

キャラクターの当たり判定は、幅 0.5×0.5・高さ 5 の箱。ブロックの AABB と重なったら、はみ出しの小さい軸へ押し戻す「スライド衝突」で、壁に沿って自然に滑ります。

第12章

手足のアニメ

担当：animation-controller.ts。3つの動きをコードだけで作り、なめらかに切り替えます。

アニメの正体は、腕・脚のピボットを X 軸まわりに回すだけの手作りクリップ。外部のモーションデータは使いません。状態はキーを押した／離した・跳んだ・着地したといったイベントで切り替わり、切り替わるたびに 150ms かけて前の動きへブレンド（クロスフェード）します。

「歩き→待機」「待機/歩き→跳躍」「跳躍→着地」の遷移は、キーの状態を毎フレーム調べるのではなく、物理側や入力側が投げるイベントに反応する形。ポーリングではなくイベント駆動なので、状態のとり違いが起きにくい素直な作りです。

第13章

5つのツール

担当：toolbar.ts と tools/ フォルダ。作る道具は、画面下のボタンと数字キーで切り替えます。

要は tool-manager.ts。「必ず1つだけ有効」を守るため、切り替え時はまず古いツールを止めてから新しいツールを起動します。各ツールは activate() / deactivate() だけを持つ最小の約束（Tool インターフェース）で、共有の道具箱（マウス・ドラッガー・選択枠・音）を受け取ります。

ツールバーは 1〜5 で選択、Esc で解除。同じボタンをもう一度押すと解除になります。ボタンは click ではなく mousedown で反応し preventDefault する——こうしてキャンバスからフォーカスを奪わないので、ツールを持ったままでも WASD で歩けます。

14色の「クラシック」パレット

ペイントの色は、あの積み木でおなじみの定番14色。paint-tool.ts に定数として並んでいます。

第14章

マウスで掴むしくみ

担当：mouse.ts・dragger.ts・ray-helpers.ts と adornments/。「クリックした先のブロック」を、どう突き止めているのか。

核は mouse.ts——ツール用マウス操作の唯一の窓口です。マウスが動くたびに画面の点から3Dの光線を作り（ray-helpers.ts、reverse-Z 前提のアンプロジェクト）、台帳にレイキャストして「今どのパーツ・どの面・空間のどこ」を指しているかを更新。その結果を、登録された各ハンドラへ「消費できるイベント」として順に配ります。誰かが consumed を立てたら、そこで配布は止まります。

掴んで動かす部分は dragger.ts が担当（移動ツールと複製ツールが共用）。カーソル下の面にブロックを吸い付かせ、1スタッドのグリッドにスナップし、土台の外（±256）へは出さない。ドラッグ中に R / T で90°回して置き直せます。選択中のブロックを囲む青い枠線（selection-box.ts、12本の辺）も、これらのツールが共通で使う目印です。

第15章

音の合成

担当：sounds.ts（247行）。効果音は1つも音声ファイルを使わず、WebAudio でその場合成します。

AudioContext は最初に音を鳴らす瞬間に遅延生成し、WebAudio が使えない環境（ヘッドレステスト等）では静かに何もしません。波形はサイン波やノイズを、フィルタと音量エンベロープで加工して作ります。

足音は歩きクリップに合わせ、着地している間だけ 1/3 秒ごとに再生。[1,3,3,2,3,2] という強弱の並びで、単調にならない歩きのリズムを作っています。

第16章

保存と持ち運び

担当：persistence.ts・world-io.ts・map-io-ui.ts。作った世界を残し、ファイルとして持ち運びます。

心臓は world-io.ts が定めるたった1つの保存フォーマット。自動セーブ（localStorage）も、書き出し／読み込みも、default-map も、全部この同じ形を使うので互換性が保たれます。キー名は短く詰め、ロックされたパーツ（＝土台）は保存しません。

// world-io の JSON（version 1）
{ version: 1,
  parts: [
    { s:[2,1,1],  // size 大きさ
      p:[0,0.5,0], // position 位置
      q:[0,0,0,1], // quaternion 回転
      c:[0.16,0.5,0.73], // color 色
      sh:1 // shape 1=斜面（省略=ブロック）
    }
  ] }

persistence.ts は、パーツが変わるたびに 250ms だけ待ってまとめて保存（デバウンス）し、タブを閉じる直前にも書き出します。読み込み側は防御的で、version が違ったり値の形が壊れていたら、その要素を飛ばして「1未満なら1に丸める」と安全に倒します。map-io-ui.ts の Export/Import は同じ形式なので、保存データとエクスポートしたマップは互換。右上のリーダーボード（Builder 1000〜9999／スコア0）は、雰囲気づくりの飾りです。

第17章

設計テーマ

35ファイルに散らばって見えて、じつは一貫した4つの考え方が通っています。

第18章

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

コードリーディングのおともに。行数は master ブランチのソース実測値です。character.ts が最大で、合計およそ5,293行。

行数は master ブランチ（2026年時点）のソース実測値です。合計およそ5,293行（35ファイル）。README を含めると36ファイル。