はじめに

『言語リファレンス』は、Kagari でビジュアルノベルを書いて出荷するための方法を説明します。エンジンの概念、言語、特殊な型と属性、ツール、ランタイムを扱います。コンパイラの診断は独立したセクション 診断 にあります。

Kagari とは

Kagari はビジュアルノベルエンジンです。次のものから成ります。

• 言語。Rust に近い言語で、ゲーム全体をこれで書きます。物語、その演出、そして物語を取り巻くゲームシステム（タイトル画面、メニュー、セーブ、設定）です。
• コンパイラ。kagari コマンドです。プロジェクトを検査し、物語を解析し、一つの .kagari ファイルとアセットアーカイブにビルドします。
• ランタイム。ビルドしたゲームを Windows、macOS、Linux で実行します。

ゲームの各部分は、それを書く関数の種別によって区別されます。

どの種別がどの種別を呼べるかはコンパイラが検査します。物語は pushdown fn だけで構成され、チューリング完全なコードはエントリーシーンを開始することでしか物語に入れません。そのため、任意のコードに対してはどんなツールにも答えられない問いに、コンパイラが物語について答えられます。すべての選択肢が何かしらのアームを提示するか、あるシーンに到達できるか、あるステップがどの経路で到達しても同じ画面を表示するか、といった問いです。理由は 設計思想：構成による解析可能性 で説明します。ゲームの残りの部分は自由に計算できます。

本リファレンスの対象読者

本リファレンスは、Kagari でゲームを作るスタジオを対象とします。シーンを書くシナリオライター、それを演出するスクリプター、ゲームシステムを作りゲームを出荷するエンジニアです。プログラミングの基礎知識を前提とします。言語は Rust の構文と多くの規則を受け継いでいるので、Rust を知っていると役立ちます。Kagari が Rust と異なる点は Rust との違い にまとめてあります。

本リファレンスの構成

Kagari が初めての読者は、概要と中核概念を順に読み、構文の部はリファレンスとして使ってください。各概念の章から、その章で使う構文へリンクしています。

最初の例

static mut VISITED_A: bool = false;

const STALL_A: ImageAsset = asset("bg/stall_a.png");

enum Ending { Normal }

#[scene]
#[entry]
pushdown fn Day1() -> Ending {
    s!(t!["The school festival starts today."]);
    StallA();
    StallA();
    Ending::Normal
}

#[scene]
pushdown fn StallA() {
    if VISITED_A {
        s!(t!["The stall is already packing up."]);
        return;
    }
    VISITED_A = true;
    s!(who = "Hanako", render = at_stall_a, t!["Welcome to stall A!"]);
}

const fn at_stall_a(mut screen: Screen) -> Screen {
    screen.background().change(STALL_A).apply_animation(fade(ms(500)));
    screen
}

• Day1 は エントリーシーン です。ゲームシステムはここから物語を開始し、その戻り値によって、どのエンディングに到達したかがシステムに伝わります。
• それぞれの s!(…) は ステップ です。物語が止まってプレイヤーを待つ地点です。t![…] はそのテキストで、who は話者を示します。
• StallA() は シーン StallA を呼び出します。シーンが戻ると、物語は呼び出しの後から続きます。二回目の訪問では別の台詞が表示されます。
• VISITED_A は 物語変数 です。物語の一回の実行にわたる大域的な状態で、有限型をもちます。
• at_stall_a は レンダー関数 です。ステップに入ったときに画面がどう変わるかを表します。ここでは 0.5 秒のクロスフェードで背景を切り替えます。

完全なゲームには、このほかに ゲームシステム を記述する fn main と、ソースを収める プロジェクト が必要です。kagari init はその両方をテンプレートから作成します。

kagari init my-game
cd my-game
kagari build
kagari-desktop-runtime target/v0

表記規則

• 暫定 は、まだ確定していない設計を表します。後のバージョンで変わりうる名前、既定値、境界的な場合の規則です。
• kis と付いたコードブロックは素のコードで、.kis ファイルでも .kix ファイルでも有効です。kix と付いたコードブロックは s!(…)、choice!{…}、t![…] などの フォーム を使っており、.kix ファイルでだけ書けます。
• ステップ は常に、物語がプレイヤーの入力を待つ地点、つまり s!(…) か choice!{…} を指します。二つのステップの間にあるものは、待たずに実行されます。
• σ（シグマ）は物語状態を表します。物語内の位置、各フレームのローカル変数を含むコールスタック、物語変数です。
• 診断は E5003 や W5004 のようにコードで呼びます。すべての診断は 診断 に一覧があります。
• スタジオ はゲームを書くチームを、エンジン はそれを実行するランタイムを指します。

他のセクション

• チュートリアル は、Kagari の導入から最初のゲームまでを案内します。
• 『STD リファレンス』 は、標準ライブラリ std のすべてのアイテムを説明します。画面、アニメーション、音声、テキスト、システム、セーブ、UI です。
• 診断 は、コンパイラが報告するすべての診断の一覧です。
• 『Kagari Develop Guide』（リポジトリ内、英語のみ）は、Kagari 自体の開発者向けです。設計判断、コンパイラの内部、ファイル形式、ランタイムの内部を扱います。