ランタイム

kagari-desktop-runtime は、kagari build でビルドしたゲームを Windows、macOS、Linux で実行します。ウィンドウを開き、GPU で描画し、オーディオを再生し、キーボード・マウス・ゲームパッドを読み取ります。ランタイムプロファイル native_v0 を実装しています。--headless を付けると、ウィンドウなしでスクリプトに従って実行します。ヘッドレスモードを参照してください。

ゲームの実行

ゲームをビルドし、kagari build が書き出したディレクトリをランタイムに渡します。

kagari build --manifest-path example/test_game1/kagari.toml
kagari-desktop-runtime example/test_game1/target/v0

Kagari リポジトリ内でなら、何もインストールせずに次のように実行できます。

cargo run -p kagari-cli -- build --manifest-path example/test_game1/kagari.toml
cargo run --release -p kagari-desktop-runtime -- example/test_game1/target/v0

プレイにはランタイムのリリースビルドを使ってください。デバッグビルドはかなり遅くなります。

コマンドライン

kagari-desktop-runtime [OPTIONS] [GAME_DIR]

GAME_DIR に game.kagari がない場合、ランタイムはステータス 2 で止まり、target/v0 のような kagari build が書き出したディレクトリを渡すよう促します。

GAME_DIR の既定は実行ファイルのディレクトリなので、配布するゲームでは実行ファイルを game.kagari とアーカイブの隣に置きます。プレイヤーは引数なしで起動できます。ゲームの配布を参照してください。

ウィンドウ

ウィンドウのタイトルとフルスクリーン状態は、ゲームのシステムが設定したものになり、実行中の変更にも追従します。ウィンドウはゲームのデザイン解像度で開き、必要ならプライマリモニタの 90% に収まるよう縮小されます。ウィンドウのサイズを変えると、画面は収まるように拡大縮小され、余白には黒帯が入ります。マウスの位置はデザインピクセルに変換し直されます。

ウィンドウを閉じるとゲームは正常に終了し（ゲームの終了処理が実行されます）、ステータス 0 で終わります。

データディレクトリ

設定とセーブは、データディレクトリ内の <name>.kisave という名前のファイルです。既定では、プラットフォームのデータディレクトリの Kagari/<title> です。<title> はゲームのウィンドウタイトルです。

<title> では、/ \ : * ? " < > | と制御文字が _ に置き換えられ、前後の空白と末尾のドットが取り除かれ、空のタイトルは Kagari Game になります。したがってタイトルを変えると設定とセーブの保存先も変わります。配布後はタイトルを変えないでください。

--data-dir <DIR> はこのディレクトリを置き換え、タイトルに依存しないようにします。ファイルはアトミックに書き込まれる（一時ファイルに書いてから名前を変える）ため、セーブ中にクラッシュしても以前のファイルは壊れません。データディレクトリが見つからない場合、ランタイムは警告をログに出し、設定とセーブは保存されません。

ランタイムプロファイル native_v0

デスクトップランタイムはランタイムプロファイル native_v0 を実装しています。動画を除く std 全体です。対応するアセット形式はランタイムプロファイルにあります。kagari build はデコードできないアセットと検証に通らないシェーダーを拒否するので、runtime-compatibility = ["native_v0"] でビルドできたゲームには実行時に非対応のアセットはありません。シェーダーにはストレージバッファを持つ GPU が必要で、モーションのシェーダーにはさらにコンピュートシェーダーが必要です。これらのない GPU では、ランタイムは警告をログに出し、その効果を設定されていないものとして描きます。STD リファレンスのランタイムプロファイルも参照してください。

デバイスがなくてもランタイムは動作を続けます。

• オーディオ出力がない: audio output unavailable (…); running silent をログに出し、音なしで動作します。
• ゲームパッドが使えない: 警告をログに出し、キーボードとマウスだけで動作します。
• アーカイブが見つからない、音声をデコードできない: 警告をログに出し、そのアセットは存在しないものとして扱われます。

ログ

ランタイムは stderr にログを出します。既定のレベルは kagari=info,wgpu=warn で、使用中の GPU アダプタ、ウィンドウのバックエンド、データディレクトリが出力されます。変更するには RUST_LOG を設定します（例: RUST_LOG=debug）。

ゲームがエラーで停止したとき

ゲームのコードが実行時に失敗すると、ゲームはエラーで停止します。算術オーバーフロー、ゼロ除算、範囲外のインデックス、recursion-depth より深い呼び出し、std の関数が発生させたエラーなどです。そのとき:

1. ゲームが停止します。保留中の遷移は破棄され、すべての音声が止まります。以降のエラーは無視されます。
2. ウィンドウは黒い画面になり、左上に白い文字でエラーメッセージを表示します。
3. ランタイムは kagari-desktop-runtime: game stopped: <message> を stderr に出力します。
4. ウィンドウはプレイヤーが閉じるまで開いたままで、閉じたときの終了ステータスは 3 です。

起動中（main の実行中、ウィンドウが開く前）にゲームのコードでエラーが起きると、同じメッセージを出力し、ただちにステータス 3 で終了します。それ以外の理由でゲームを開始できない場合は、kagari-desktop-runtime: cannot start the game: <reason> を出力してステータス 2 で終了します。

• .kagari ファイルが不正、または検証に失敗した。
• .kagari ファイルが、このランタイムにないビルトインをインポートしている（the bytecode imports `<path>`, which this runtime does not provide）。たとえば新しいランタイム向けにビルドされたファイルです。
• フォントを読み込めない。フォントアセットが見つからないかデコードできない、またはシステムの既定フォントが読み込まれていない（the system font `<path>` is not loaded）。
• システムのテキストスタイルが、読み込めないアセットを参照している。

終了ステータス

ステータス 0 以外では、ランタイムは kagari-desktop-runtime: <message> を stderr に出力します。

システム要件

実行時には、Vulkan、Metal、DirectX 12、OpenGL のいずれかの GPU ドライバが必要です。使えるハードウェアアダプタがない場合はソフトウェアのフォールバックアダプタを試し、それもなければステータス 4 で終了します。Linux ではさらに Wayland または X11 と ALSA が必要です。

ソースからランタイムをビルドするには、次のシステムパッケージが必要です。