エンジンの仕組み — どこでも動くスクリプトエンジン

kaedevn で作った作品が Web でも Android でも PC でも同じように動く秘密は、プラットフォームに依存しないスクリプトエンジンの設計にあります。約80,000行のソースコードが、この「どこでも動く」を支えています。

コンパイラとインタプリタの違い

kaedevn には2つのスクリプト処理系があり、それぞれ仕組みが異なります。

• packages/compiler — KS (.ks) / コンパイラ — スクリプトを事前に Op[]（命令配列）に変換。実行時は OpRunner が命令を順に処理
• packages/interpreter — KSC (.ksc) / インタプリタ — スクリプトを逐次解釈して直接実行。デバッグモードやエラー候補提示を搭載

コンパイラはスクリプト全体を事前に機械が読める形に変換してから実行します。インタプリタはスクリプトを1行ずつ読みながらその場で実行します。

2つのスクリプト形式

kaedevn には用途の異なる2つのスクリプト形式があります。

KS（Kaede Script）— タグベース、20コマンド

TyranoScript に近いシンプルな形式です。セリフや基本演出を素早く記述するのに向いています。

@bg id="room"
@ch name="sakura" pose="smile" pos="C"
桜「おはよう！今日もいい天気だね」
@choice text="一緒に出かける" target="go_out"
@choice text="家でのんびり" target="stay_home"

対応コマンド（20種）:

• 映像 — @bg, @ch, @ch_hide, @ch_clear, @overlay, @overlay_hide, @show, @hide, @move, @fade
• 音声 — @bgm, @bgm_stop, @se, @voice
• 制御 — @wait, @jump, @choice, @if, @set
• エフェクト — @screen_filter

KSC（Kaede Script Code）— TypeScript 風、型安全

TypeScript に近い構文で、変数・条件分岐・関数定義・型チェックなどの高度なロジックが書ける形式です。

bg("room")
ch("sakura", "smile", "C")

#sakura
「おはよう！今日もいい天気だね」
#

if (affection >= 10) {
    choice {
        "一緒に出かける" { jump("go_out") }
        "デートに誘う"   { jump("date") }
    }
} else {
    choice {
        "一緒に出かける" { jump("go_out") }
        "家でのんびり"   { jump("stay_home") }
    }
}

KSC の型システム:

• number — affection = 5
• string — playerName = "太郎"
• boolean — isClear = false
• object — {hp: 100, mp: 50}
• array — [1, 2, 3]
• union — number | string
• 関数 — def get_rank(score) { ... }

コンパイルから実行までの流れ

KS の場合（4段階パイプライン）

.ks スクリプト
    |
    v
Tokenizer ── 字句解析（行を分類）
    |           lineClassifier で COMMAND / TEXT / LABEL を判定
    v
Parser ───── 構文解析（コマンドレジストリ参照）
    |           commandRegistry.ts が全コマンドの定義源
    v
Transformer ─ 変換・最適化
    |
    v
Finalizer ── 検証 + Op[] 出力
    |           プラットフォーム非依存の命令列
    v
OpRunner ─── 1命令ずつ実行、描画エンジンに委譲

KSC の場合（インタプリタ）

.ksc スクリプト
    |
    v
インタプリタ ── スクリプトを逐次解釈して直接実行
    |              TypeScript 風の構文を1行ずつ処理
    v
HostAPI ────── 描画エンジンに命令を委譲

KSC インタプリタはデバッグモード（ブレークポイント、変数ウォッチ、ステップ実行）やエラー候補提示（Levenshtein 距離による類似コマンドの提案）を搭載しています。

重要なのは、コンパイラの出力する Op[] がプラットフォームを問わず共通 である点です。同じ命令列を Web ブラウザでも Nintendo Switch でも実行できます。

Op 型（中間表現）— エンジンの共通言語

コンパイラが出力する命令の種類は以下の通りです。

• テキスト — TEXT_APPEND（話者名 + 本文）
• 映像 — BG_SET, CH_SET, CH_HIDE, CH_CLEAR, OVL_SET, OVL_HIDE, SHOW, HIDE, MOVE, FADE, SCREEN_FILTER
• 音声 — BGM_PLAY, BGM_STOP, SE_PLAY, VOICE_PLAY
• 制御 — CHOICE, JUMP, VAR_SET, IF（ネスト対応）
• 待機 — WAIT（click / timeout / voiceend）
• アニメーション — Timeline キーフレーム

スクリプトエンジンの役割

スクリプトエンジン（KS の OpRunner / KSC のインタプリタ）はスクリプトの「頭脳」です。以下を担当します。

• 実行制御: コンパイル済み命令の順次実行（KS）/ スクリプトの逐次解釈（KSC）
• 変数の保持: フラグや好感度などのゲーム状態を管理（グローバル/ローカルスコープ対応）
• フロー制御: if 分岐、ジャンプ、サブルーチン呼び出し（call / ret）、for / while ループ
• 選択肢の処理: プレイヤーの選択を受け取り、対応するラベルへ移動

スクリプトエンジン自体は画面描画や音声再生を一切行いません。「背景を room に変えて」「BGM を再生して」といった命令を発行するだけです。実際の描画は、各プラットフォームの実装（Web なら PixiJS、Switch なら SDL2）が担当します。

IEngineAPI — プラットフォームを繋ぐインターフェース

スクリプトエンジンと描画エンジンの間には IEngineAPI という抽象インターフェースが定義されています。

IEngineAPI
  ├── showText(speaker, body)     テキスト表示
  ├── showChoice(options)         選択肢表示 → 選択結果を返す
  ├── setBg(assetId)              背景変更
  ├── showCh(charId, exprId, pos) キャラクター表示
  ├── hideCh(charId)              キャラクター非表示
  ├── playBgm(assetId)            BGM 再生
  ├── playSe(assetId)             効果音再生
  └── wait(mode, ms)              待機

このインターフェースを実装するだけで、新しいプラットフォームに対応できます。実際に以下の実装が存在します。

• WebOpHandler — Web ブラウザ（PixiJS） — 本番用
• SDL2Engine — Switch / Android / PC — ネイティブ
• TestEngine — ユニットテスト用（画面なしで動作検証）
• ConsoleEngine — コンソールデモ（テキスト出力のみ）

デバッグモード

Kaede Script のコード記法（KSC）を実行するインタプリタにはデバッグ機能が組み込まれています。

• ブレークポイント: 任意の行番号で実行を一時停止
• 変数ウォッチ: 変数の値をリアルタイムで監視
• トレースログ: 実行された全行を記録
• ステップ実行: 1行ずつ進める

エラーハンドリング

スクリプトにミスがあった場合、kaedevn は親切なエラーメッセージを返します。

• Levenshtein 距離による類似コマンドの候補表示（「@bgg と書きましたが、@bg のことですか？」）
• スタックトレース: 呼び出し元の行番号と関数名
• 前後のコンテキスト: エラー箇所の周辺行を表示

// 実行時にエラーを検出
affection = "高い"  // Error: number型の変数にstringを代入できません
jump(123)           // Error: jump()の引数はstringである必要があります

なぜこの設計なのか

従来のノベル系エンジンは、特定のプラットフォーム（Windows や Web）に密結合していました。kaedevn は最初から Nintendo Switch への移植を見据えて、エンジンのコア部分とプラットフォーム固有の処理を明確に分離しています。

この設計により:

• 作者は1回書くだけ: 同じスクリプトが全プラットフォームで動く
• 移植コストが最小: 新しいプラットフォームに対応するには IEngineAPI を実装するだけ
• テストが容易: スクリプトエンジン単体でスクリプトの正しさを検証できる（画面なしで 107 以上のテストが通る）
• 2つの入口: 初心者は KS のタグベース、上級者は KSC の TypeScript 風構文を選べる

関連ドキュメント

• KS スクリプト仕様書 — KS コンパイラの全コマンド
• KSC スクリプト仕様書 — KSC インタプリタの全コマンド
• マルチプラットフォーム — SDL2 ネイティブエンジン
• アセットのポータビリティ — 共通アセット設計