斜め見下ろしの世界を、
タイル1枚から組み上げる。

第1章

このデモとは

「あの斜め見下ろしの Civ みたいな世界地図、3Dモデルなしで、絵（スプライト）を並べるだけで作れるの？」に、動く実装で答えるサンプルです。

このデモは、Babylon.js ファミリーの WebGPU 専用ランタイム Babylon Lite の公式リポジトリに含まれる、freeciv（フリーシブ）——オープンソースの Civ クローン「Freeciv」の見た目を借りた、アイソメトリック（斜め見下ろし）の世界地図です。本物の Freeciv タイルセット（amplio2）を読み込んで、ダイヤ形のタイルを何千枚も敷き詰め、大陸を自動生成し、都市・道・川・野生動物、そして霧・昼夜・雲・きらめく水面まで描き込みます。

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

第2章

あそびかた

コードを読む前に、まず地図をぐりぐり動かすのが近道です。マップ探索と、1体だけ動かせる斥候（スカウト）がいます。

第3章

用語ミニ辞典

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

第4章

全体の地図

エントリの freeciv.ts（664行）が司令塔。タイルセットを読み、世界を生み、レイヤーを積み、演出を配線して、1本のループを回します。

flowchart TD
    ENTRY["freeciv.ts
司令塔(2Dスプライトのみ)"]
    subgraph DATA["読む"]
        SPEC["spec-parser + atlas
10枚の.spec→絵の切り出し"]
        WGEN["worldgen
96×96の大陸生成"]
    end
    subgraph DRAW["描く"]
        TMAP["tilemap
15レイヤーに配置"]
        FX["fog/daynight/atmosphere
water/glints/dust…"]
        PRES["present
なめらかズーム合成"]
    end
    LIVE["live
斥候・野生動物"]
    ENTRY --> DATA
    ENTRY --> DRAW
    ENTRY --> LIVE
    WGEN --> TMAP
    SPEC --> TMAP
    TMAP --> PRES
    FX --> PRES
  

矢印は「上が下を利用する」向きです。freeciv.ts は、10枚のタイルシートを並列で読み込み→世界を生成し→15枚のスプライトレイヤーを積み上げ→動くものと演出を配線し→毎フレーム、シミュレーション更新・ズーム補間・各演出の更新を回します。「読む」「描く」がはっきり分かれているのが最初の目印です。

第5章

タイルセットを読む

担当：spec-parser.ts と atlas.ts。本物の Freeciv タイルセットを、コードで読み解きます。

Freeciv のタイルは、1枚の大きなPNGに格子状に並んでいて、その「どのマスがどのタイルか」を .spec という INI 風のテキストが定義します。spec-parser.ts はこれを自前で解析——シート画像のパス、格子の原点・セル幅・間隔、そして「行・列・タグ名」の対応表を読み取ります。

flowchart LR
    SPEC[".spec テキスト"] --> PARSE["parseSpec
格子geometry+タグ表"]
    PNG["シートPNG"] --> ATLAS["loadFreecivSheet
共有テクスチャ+アトラス"]
    PARSE --> ATLAS
    ATLAS --> FRAME["frameOf(タグ)
= 行×列数+列"]
  

atlas.ts は、その設計図に沿ってPNGを GPU テクスチャに載せ、グリッドごとにタグ名 → フレーム番号の引き表を作ります。テクスチャはニアレスト（最近傍）フィルタ——ドット絵をくっきり保ち、1px の境界を越えて色がにじまないようにします。10枚のシート（地形・丘・山・海・水・都市・ユニット・動物・選択枠…）から、15枚の描画レイヤーが作られます。

第6章

斜め格子の座標

担当：iso.ts（79行）。マス目 (x, y) と、画面のピクセル座標を行き来する数学です。

タイルは横 TILE_W = 96・縦 TILE_H = 48 の 2:1 ダイヤ形。マス (x, y) の画面中心は、次の一行で決まります。

// マス目 → 画面ピクセル（アイソメトリック変換）
isoCentre(x, y) = [ (x - y) * 48,   // = TILE_W/2
                    (x + y) * 24 ]; // = TILE_H/2
// 逆変換 worldToTile はこれを解いて四捨五入 → 点の下のダイヤに吸着

この式のおかげで、隣り合うマスが画面上で綺麗な菱形の格子になります。iso.ts はさらに、8方向の隣接マス（DIR8）や、ダイヤの辺を共有する4方向（EDGES＝川や海岸で使う“実質的な東西南北”）、画面方向を Freeciv のスプライト向き記号に変換する表（SPRITE_DIR）を提供します。これらは世界生成と描画の両方が共通で使う、いわば“方位磁針”です。

第7章

世界を生成する

担当：worldgen.ts（526行）。シードから、海に囲まれた1つの大陸を組み上げます。

まず高さの地図を作ります。5オクターブの値ノイズ（fBm）に、中心からの距離で効く放射状の減衰（1 - 距離²×1.15）を掛ける——だから縁は海に沈み、中央が陸になります（高さ < 0.32 は海）。そこへ別の低周波ノイズ＝湿度と、赤道からの緯度を組み合わせて、11種類の地形を振り分けます。

// 地形の振り分け（抜粋・実際のしきい値）
if (elevation < 0.32) → Ocean          // 海面
if (lat > 0.86)       → Arctic         // 極地
if (lat > 0.72)       → Tundra / Mountains
if (elevation > 0.78) → Mountains
if (elevation > 0.62) → Hills
// 残りは湿度で: 乾→砂漠/平原、湿→湿地/密林/森、中間→草原

地形ができたら、生活を吹き込みます。川は高地（高さ > 0.66）から湧き、辺づたいに一番低い隣へ流れ下って海に達したものだけ残す（最大8本／“取り残された水たまり”は消す）。都市は草原か平原に、間隔6マスで最大9つ——中心には首都 Babylon（人口5）、Carthage・Paris・Kyoto は固定座標に。道路は都市どうしを最小全域木で最短につなぎ、約9%の陸地には地形に合った資源や灌漑・鉱山を配置します。

第8章

レイヤーで描く

担当：tilemap.ts（368行）。生成された世界を、正しい順でタイル絵に置き換えていきます。

描画は奥から手前へ（x+y の昇順＝画家のアルゴリズム）。1マスは、複数レイヤーにまたがる絵の積み重ねとして表現されます。

第9章

なめらかズーム

担当：present.ts（167行）。ドット絵タイルを、隙間なく・なめらかに拡大縮小する巧妙な仕掛けです。

問題はこうです。ダイヤ形タイルを中途半端な倍率（例：1.7倍）で直接描くと、タイルの継ぎ目に髪の毛のような隙間（クラック）が出ます。かといってピクセルを整数倍でしか拡大しないと、ズームがガクガクします。

解決は2段構え。まずタイルを、2倍のスーパーサンプリングをかけたオフスクリーンの画像に、継ぎ目が出ない“きりのいい倍率”（0.5/1/2/4/8 のいずれか）で描く。次にその画像を、1枚の板として、実際に見せたい中途半端な倍率へ滑らかに縮小して画面に貼る。こうして「くっきり」と「なめらか」を両立します。描画は ワールド → 合成板 → HUD の3パスで流れます。

第10章

動くもの

担当：live.ts（285行）と dust.ts。止まった地図に、命を吹き込む層です。

動くものは2種類。1つはプレイヤーが操る斥候（スカウト）——命令があるまで待機し、目的地が指示されると、経路を1マスずつ約 620ms/マス で歩きます（滑らかに補間）。選択中は大きさは変えず、透明度がゆっくり明滅して「選ばれている」ことを示します。もう1つは6体の野生動物（狼・熊・豹・虎・ワニ・ゴリラ・蛇から）——都市以外の隣マスへ気ままに歩き回ります。すべてシード固定で、毎回同じ動き。

第11章

クリックの手ごたえ

担当：pick.ts と commandfx.ts。操作に“手ごたえ”を返す、ゲームフィールの層です。

マウスを乗せると、pick.ts がそのタイルに水色の枠を置き、地形・資源・改良・川/道・座標をまとめたツールチップを出します（3Dのピッキング機能ではなく、座標計算だけで実現）。斥候を選んで行き先をクリックすると、freeciv.ts のダイクストラ経路探索（道の上は移動コスト 1/3 に割引）が最短路を求め、斥候がそこへ歩き出します。

その瞬間の視覚フィードバックが commandfx.ts。すべて WGSL シェーダで1枚の板に描かれます。

第12章

戦場の霧

担当：fog.ts（256行）。未踏の土地を霞ませる、あの“霧”です。

ポイントは、霧をタイルごとの絵で置かないこと。もしそうすると、ダイヤの継ぎ目に不自然な段差が出ます。代わりに、世界に貼りついた1枚の連続したモヤの板を用意し、そのシェーダが「タイルごとの視界の強さ」を記録した小さなテクスチャをなめらかに（バイリニアで）読んで、モヤの濃さを決めます。

CPU 側は「踏破済み・現在視界・霧の濃さ」を配列で管理。地図は最初から全域が踏破済みで、見ていない土地は薄い霧（0.72）、視界に入ると 450ms かけて晴れます。視界の半径は都市の周り2マス・斥候の周り3マス。さらにシェーダは、fBm ノイズで霧のふちを揺らして、風にたなびくように見せます。

第13章

昼と夜

担当：daynight.ts（215行）。N キーで、世界が昼と夜を行き来します。

N を押すと、5000ms かけて昼 ⇄ 夜へなめらかに遷移し、到達した側でとどまります（自動ループはしません）。夜は、画面全体を覆う1枚の暗い青の板（rgb(0.04, 0.06, 0.18)）の不透明度を、時間に比例して最大 0.62 まで上げるだけ。そして日が傾くと、各都市が暖色の光（rgb(1.0, 0.82, 0.5)）を加算でにじませ、街の灯がともります。

第14章

空・雲・水・きらめき

担当：atmosphere.ts・water.ts・glints.ts。空と海の“生きた”質感です。

これらに共通するのが、「世界に貼った1枚の板＋自前 WGSL シェーダ」という作り。板のスプライトの色（tint）に「画面上の世界の矩形」や「タイル位置＋位相」を忍ばせ、ピクセルごとに模様を合成します。霧・雲・水・きらめきはすべてこの共通テクニックで、CPU の負担をほぼ増やしません。

第15章

古地図と縁取り

担当：backdrop.ts・vignette.ts・minimap.ts。世界の“額縁”と俯瞰図です。

backdrop.ts は、島の背後に1569年の Mercator 世界地図（パブリックドメイン）を敷きます。暗く落とし、紙のような色をかぶせて“古びた抽象背景”に加工。さらに海岸が外洋へ溶け込むよう、青いにじみ（sea halo）を島の縁に足します。静的で、地図と一緒にパン・ズームします。

vignette.ts は、画面の四隅を暗く落とす周辺減光。中央 50% は明るいまま、隅へ向かってなめらかに暗くして、背景の“余白”を目立たなくします。minimap.ts は右下のミニマップ（長辺180px）——世界を1タイル＝1ピクセルのデータ画像として一度に描き、地形色・都市の点・現在の表示範囲（回転した四角形をはみ出さないよう切り抜き）を重ね、クリック／ドラッグでそこへ表示を飛ばせます。

第16章

設計テーマ

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

第17章

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

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

行数は master ブランチ（2026年時点）のソース実測値です。合計およそ4,342行（19ファイル）。