KSC 実行パイプライン全体図（Phase 1 完了時点）

作成日: 2026-04-29 ／ 更新日: 2026-06-10 更新日: 2026-04-29

AI レビュアー / 新規開発者向け: KSC のコンパイル・実行に関わるパッケージは複数あり、過去の遺産（deprecated）と新しい設計が共存しています。本文書を最初に読んでください。

• 旧: packages/interpreter（直接インタプリト方式、deprecated、新規利用禁止）
• 新: packages/ksc-compiler（コンパイラ+VM 方式、Web/Native 共通） ← これが現役

関連: 20-engine-architecture.md（2026-03-22 時点の概要、KS/KSC + IOpHandler モデル中心）。本文書は Phase 1 の host-binding パターン以降を扱う。

---

1. 一目で把握する図

                    KSC source (.ksc)
                          │
                          ▼
    ┌───────────────────────────────────────────────┐
    │  packages/ksc-compiler                        │  ← Web/Native 共通の単一コンパイラ
    │  lexer → parser → checker → emitter           │
    └───────────────────┬───────────────────────────┘
                        │
                        ▼
                   IR (中間表現、JSON-serializable)
                        │
        ┌───────────────┴───────────────────┐
        ▼                                   ▼
  ┌─────────────────────┐           ┌──────────────────────┐
  │ TS VM               │           │ C++ KscVM            │
  │ ksc-compiler/vm.ts  │           │ packages/ksc-vm-cpp  │
  │ (Web preview 用)    │           │ (実機 / ksc_runner)  │
  └──────────┬──────────┘           └──────────┬───────────┘
             │ HostAPI.call(name, args)        │ ksc::HostAPI::call
             ▼                                 ▼
  ┌──────────────────────────┐    ┌──────────────────────────────┐
  │ Web HostAPI 実装         │    │ Native HostAPI 実装          │
  │ ├─ KscHostAdapter        │    │ ├─ BillingHostBinding        │
  │ │  (VN dispatch)         │    │ ├─ EntityHostBinding         │
  │ └─ EcsHostAdapter        │    │ ├─ CameraHostBinding         │
  │    (ECS 21 host 関数)    │    │ ├─ TweenHostBinding          │
  │                          │    │ └─ CollisionHostBinding      │
  └────────────┬─────────────┘    └────────────┬─────────────────┘
               │                                │
               ▼                                ▼
       PixiJS / WebGL              SDL2 / OpenGL ES (3.0+) / NVN
       Web Audio API               SDL_mixer
       IndexedDB                   FileStorage
       (ブラウザ)                  (macOS / iOS / Android / Switch)

---

2. 「コンパイラ 1 つ + VM 2 つ」が肝

両 VM は HOST_CALL opcode で文字列名 + 引数を host に投げる 設計。具体的な機能（描画・音・課金・ECS 等）は host 実装に外注されている。

---

3. ホストバインディング一覧（2026-04-29 時点、26 関数）

すべて ksc-compiler/src/checker/builtins.ts で型登録済、emitter.ts の TOP_LEVEL_HOST_CALLS で engine. 前置きなしの bare 名でも呼べる。

---

4. 各層のソース位置

コンパイル層（共通）

packages/ksc-compiler/
├── src/lexer.ts         (~390 行) — トークナイザ。class/new/this 等のキーワードも
├── src/parser.ts        (~1265 行) — AST 生成。class V0 の脱糖もここ
├── src/checker.ts       (~780 行) — 型チェック + scope 管理 + builtin 登録
├── src/checker/builtins.ts — ホスト関数の型シグネチャ全集
├── src/emitter.ts       (~930 行) — IR 生成、TOP_LEVEL_HOST_CALLS
├── src/vm.ts            (604 行) — TS VM 実装
└── src/types/           — AST / IR / Token / Value / KscType 型定義

VM 層

TS VM:
  packages/ksc-compiler/src/vm.ts
  - HostAPI 受け取り、HOST_CALL を委譲
  - CALL_METHOD で this 自動 bind

C++ KscVM:
  packages/ksc-vm-cpp/src/KscVM.cpp
  packages/ksc-vm-cpp/include/kaedevn/ksc/{KscVM,HostAPI,Value,IR}.hpp
  - 同 37 opcode、bit-exact parity
  - VMState シリアライズ対応（save/load）

Web 側 HostAPI 実装

packages/web/src/engine/
├── KscHostAdapter.ts       — VN ops（showDialogue/setBg/showChar/playBgm/...）
├── EcsHostAdapter.ts       — ECS 21 関数（spawn/setPos/tweenTo/overlap/...）
├── KscRunner.ts            — TS VM 駆動 + AWAIT/resume ループ
└── ecs/                    — 内部 ECS 実装（C++ EntityRegistry の TS ミラー）
    ├── Components.ts       — Transform / Sprite / Layer / Collider 型
    ├── EntityRegistry.ts   — 世代付きハンドル + sparse parallel arrays
    ├── Camera.ts
    ├── Tween.ts
    └── Collision.ts

Native 側 HostAPI 実装

packages/native-engine/src/engine/
├── BillingHostBinding.{hpp,cpp}     — 課金（5 関数）
├── EntityHostBinding.{hpp,cpp}      — ECS（8 関数）
├── CameraHostBinding.{hpp,cpp}      — カメラ（4 関数）
├── TweenHostBinding.{hpp,cpp}       — トゥイーン（4 関数）
├── CollisionHostBinding.{hpp,cpp}   — 衝突（5 関数）
├── ecs/
│   ├── Components.hpp                — Transform / Sprite / Layer / Collider POD
│   └── EntityRegistry.{hpp,cpp}      — 世代付きハンドル
├── Camera.{hpp,cpp}                  — Camera struct + updateCameraFollow
├── Tween.{hpp,cpp}                   — TweenManager
├── Collision.{hpp,cpp}               — AABB free functions
└── RenderSystem.{hpp,cpp}            — Layer z-order sort + Camera 変換

IR / 型仕様

両 VM が同じ IR を解釈するため、packages/ksc-compiler/src/types/ir.ts が 唯一の真実のソース。packages/ksc-vm-cpp/include/kaedevn/ksc/IR.hpp はそれを C++ 側に写経した同期実装。

---

5. KSC 作者から見た書き味

// プレイヤーをスポーンして衝突判定 + tween 移動
const player = spawn(100, 100);
setSprite(player, 1);
setCollider(player, 32, 48, "player");

// 移動アニメーション
await tweenTo(player, 500, 100, 1000, "easeInOut");

// 衝突判定
const enemy = aabbQuery(0, 0, 1280, 720, "enemy");
if (enemy !== null) {
  destroy(enemy);
}

// カメラ追従
cameraFollow(player);

// 課金（既存の billing API と同居）
if (!owned("premium_pack")) {
  const r = await purchase("premium_pack");
  if (r.status === "granted") { /* ... */ }
}

// class（V0、データクラス相当）
class Player {
  hp: number = 100;
  x: number = 0;
  constructor(initX: number) {
    this.x = initX;
  }
}
const p = new Player(50);

Web preview でも実機（Switch / iOS / Android）でも同じスクリプトが同じ HOST_CALL 名で動作します。

---

6. 旧 vs 新 — どちらを使うべきか

packages/interpreter（deprecated、2026-04-29 〜）

• 直接インタプリト方式
• IEngineAPI 経由で機能を提供
• 既存利用先は packages/web/src/engine/_deprecated/WebEngine.ts のみ
• 詳細: packages/interpreter/DEPRECATED.md

packages/ksc-compiler（現役） ← 新規プロジェクトはこちら

• コンパイラ + IR + VM
• HostAPI 経由で機能を提供
• Web/Native 両対応、parity 保証
• ECS / Camera / Tween / Collision / Billing の全 26 host 関数

旧設計の Interpreter.ts の executeBuiltin メソッドや IEngineAPI の interface は 新パスでは参照しません。レビュー時に「ECS 命令が executeBuiltin に無い」という指摘は、旧パスを誤って見ていることになります。

---

7. 規模・テスト

2026-04-29 時点（Phase 1 #1〜#8 完了）:

---

8. 計画文書（実装の経緯）

実装の意思決定経緯は docs/09_reports/2026/04/29/ 配下を参照:

---

9. AI レビュアー向けチェックリスト

リポジトリのアーキテクチャをレビューする際:

1. ✅ docs/landing/codebase-docs/22-ksc-pipeline-overview.md（本文書）を読む
2. ✅ docs/09_reports/2026/04/29/04-engine-evolution-plan.md で実装フェーズを確認
3. ⚠️ packages/interpreter/ を見たら DEPRECATED.md を確認、新パスへ誘導されていることを認識
4. ✅ KSC の host 関数を追加するなら 05-host-binding-pattern-spec.md のチェックリスト 14 ステップに従う
5. ✅ 「Web は Interpreter、Native は Compiler」という二分法は誤り — どちらもコンパイラ共通で VM だけ違う

---

10. 関連ドキュメント

同じシリーズ

• 20-engine-architecture.md — 2026-03-22 時点の概要（KS/KSC + IOpHandler モデル中心、Phase 1 前）
• 08-pkg-ksc-compiler.md — KSC コンパイラパッケージ詳細
• 09-pkg-web-engine.md — Web 側エンジン詳細
• 10-pkg-interpreter.md — deprecated パッケージ詳細
• 13-pkg-native-engine.md — Native エンジン詳細
• 21-ksc-billing-api.md — KSC 作者向け課金 API リファレンス

計画・設計

• docs/09_reports/2026/04/29/ — Phase 1 計画書群
• docs/09_reports/2026/04/21/01-phase1-ksc-vm-billing-plan.md — Phase 1 起点