コンテンツにスキップ

コア ABI と SDK

プロトコルとエントリーポイント

Section titled “プロトコルとエントリーポイント”

ネイティブプロトコルは shinki.emu.native.c.v3 で、ABI の数値バージョンは 3 です。動的コアは shinki_emu_query をエクスポートし、静的統合では同じ形の Query 関数を登録します。Rust の契約は Source/FamilyApi/shinki-emu-abi にあり、生成される C ヘッダーは include/shinki_emu.h です。C++ はこのヘッダーを使い、ABI 定義を別に保守することはしません。

境界を越えるのは C レイアウトの値だけです。具体的には、バージョン付きヘッダー、長さ上限のある借用バイト列、不透明ハンドル、ステータスコード、関数ポインターです。Rust のコンテナや例外の巻き戻しは ABI を越えません。動的ライブラリと不変の descriptor ストレージは常駐したままです。query はバージョンと関数テーブルの出力ポインターを受け取り、未対応のバージョンでは出力を null にします。query は I/O を行わず、worker を起動せず、logger もインストールしません。

  1. query は不変の CoreApi テーブルを取得し、バージョン、サイズ、必須の関数ポインターを確認します。
  2. initialize は通常のコア操作の前に診断機能を接続します。
  3. describe は family/plugin の識別子、バージョン、フォーマット、型付き設定、能力を返します。CPU surface は必須の能力です。0 以外の描画サイズは、descriptor で宣言され、その範囲内にある場合に限り有効です。
  4. probe はゲームディレクトリを調べます。NO_MATCH は正常な結果です。返される文字列はモジュールのストレージを借用しており、次の通常呼び出しまで有効なので、ホストは必要なメタデータを先にコピーします。
  5. open は設定を検証してネイティブセッションを作成します。失敗時はリソースを片付けて null ハンドルを返します。成功時は session/context/output の識別子と surface のメタデータを返します。
  6. input は入力を順序付きの所有型イベントとしてコピーし、キューに入れます。control は一時停止、再開、または保持済みで安全に再試行できる操作を要求します。ポインター座標は、現在表示しているフレームのラスターピクセルとその識別子に対応します。
  7. state と frame は公開済みの状態と画面を読み取るだけで、VM を進めません。失敗したセッションは型付きのエラーを持ちます。ホストが再試行を提示するのは、コアが安全と宣言している場合だけです。
  8. cancel は並行して呼び出せます。ブロック中のネイティブサービスを起こす必要があり、キャンセル対象の操作の後ろで待ってはいけません。
  9. close は結果にかかわらずハンドルを消費し、戻る前に worker とコールバックの終了を待ちます。ホストは新しい cancel を止め、実行中の cancel が戻るのを待ってから close します。
  10. extension は名前とバージョンを持つ C テーブルをネゴシエートします。未対応の場合は UNSUPPORTED と空の出力を返します。任意の shinki.module_owner は、セッションをまたぐ実際のリソースに owner を提供します。この owner はモジュールの owner スレッドで作成され、すべてのセッションが終わったあとに破棄されます。

通常の ABI 呼び出しは、ホストの owner スレッドで直列に実行されます。VM の進行、描画と音声のスケジューリング、リソースのライフサイクルは、コア自身のネイティブ owner が担当します。Manager が提供するのは入力、制御、ホストサービスだけで、advance コールバックはありません。キャンセルと epoch のチェックにより、古いセッションや古い出力世代から遅れて届いた結果は拒否されます。

共有 Rust 診断ブリッジは元のイベントを一度だけ転送します。ホストのコールバックが同じ静的リンクの tracing subscriber にイベントを出力しても、そのネストしたイベントを ABI 経由で再転送しません。スレッドローカルのガードはフィールドの整形とコールバックを保護し、通常の復帰でも巻き戻しでも解除されます。他のスレッドと後続イベントは独立して処理されます。shinki-emu-abi/diagnostic-bridge を使うすべてのコアに適用され、ログレベルや worker のスタック容量は変更しません。

既存の Descriptor.capabilities に任意の意味ビットを追加します。ABI バージョン 3、C レイアウト、fingerprint は変更しません。

  • CAP_NATIVE_SCRIPT_IDENTITY(64):明示された変換スクリプトの hash を検証し、そのセーブ・既読を分離します。marker のないゲームは従来の保存先を使います。
  • CAP_CONFIGURED_FONT_PRIORITY(128):設定したフォントを、スクリプトや復元状態の優先フォントより先に使用します。ruby と UI テキストも対象です。
  • CAP_NATIVE_EMBEDDED_TEXT(256):ネイティブ SC の表示オペランドが Unicode scalar リテラルを扱い、実行時翻訳表なしで埋め込み訳文を表示します。Musica レシピは 256、RFVP の GBK/統一フォント用レシピは 192 を要求し、同じ descriptor/receipt 検証を使います。
  • CAP_NATIVE_NAME_RESOURCES(512):ネイティブ SC の姓名定数と元の表示・履歴規則を使い、リソースがない場合だけ EXE を読み取り専用で参照します。Yorino は 256|512=768 を要求し、EXE は変更しません。

Luau レシピは出力 profile の plugin_id、configuration と並べて required_capabilities = 192 を指定できます。receipt にも要件を保持します。Manager はインポートするゲームの追加や設定の保存前とセッションの開始前に、実際にロードした選択コアの describe を確認します。自動インポートでは、変換完了後に要件が変更された receipt も拒否します。機能が不足すれば操作を拒否してコアの更新を案内し、未知の要件があれば profile 自体を拒否します。バージョン文字列やファイル名から機能を推測しません。旧 profile で省略されたフィールドは 0 とし、新 receipt でも 0 は書き出さないため、従来のレシピは影響を受けません。

判断基準は descriptor の能力ビットだけです。CAP_TEXT_HOOK がなければ none、CAP_TEXT_HOOK だけなら synchronous、CAP_TEXT_HOOK | CAP_ASYNC_TEXT の両方があれば async-v1 です。CAP_ASYNC_TEXT だけを宣言しても無効です。現在バージョンを固定している外部コア 9 個はすべて none を宣言しています。外部コアは、自身のスケジューリング方式を保ったまま同期置換を採用できます。SDK コアかどうかは所有関係で決まります。Musica は SDK の自社コアで、Artemis は SDK の音声を使っていても外部コアです。CMVS は独立したワークツリーで保守されています。

ABI バージョンは 3 のままです。OpenRequestTextV1 は基本の OpenRequest をそのまま含み、末尾に AsyncTextServiceV1 へのポインターだけを追加します。サービステーブルは自身のバージョン 1 とサイズを持ちます。ホストは基本ヘッダーの size を拡張構造体のサイズに設定します。コアはまず size が拡張部分を含むかを確認し、そのうえでサービスのバージョン、サイズ、コールバックを検証します。null ポインターは置換の無効化を意味します。既存の外部バイナリは、レイアウトが変わらない HostServices.text の同期コールバックを引き続き使います。async-v1 コアは同期パスにフォールバックしません。

submit は戻る前に長さ上限のあるテキスト項目をコピーし、完了するまで poll は即座に PENDING を返します。待つのはテキストの送りだけで、画面、アニメーション、入力、音声は動き続けます。結果には置換の意味、テキスト項目 ID、(session_epoch, context_epoch, request_id) の識別子が保持されます。request ID は同じ context 内で増加します。未確認の同じリクエストを再送しても、二重には実行されません。CAPACITY は呼び出し側のバッファに必要な容量を返し、provider や拡張を再実行しません。完了した結果は acknowledge まで保持されます。cancel は指定したリクエストだけを破棄し、invalidate は context を進めて、古いリクエスト、コンテキスト、provider のキャッシュを破棄します。コールバックはネットワークやスクリプトの完了を待ってはいけません。

Manager の 2 つのパスは provider の AsyncTranslationService を共有し、同期互換コールバックも同じ結果を待ちます。Musica は自身の pump で一度だけ submit し、保持したバッファで poll するため、音声は止まりません。Enter、スペース、メインボタンのクリック、Ctrl を押すと、完了待ちの翻訳をスキップし、置換入力の原文を表示します。この入力は消費されるため、その行まで同時に送られることはありません。スキップモードでも完了待ちの翻訳はスキップされます。スキップ、ロード、巻き戻し、終了では遅れて届いた結果を破棄します。失敗時の再試行はテキストイベントと識別子を保持し、VM を再実行しません。

Ready 状態の FrameSurface には、実際のサイズ、stride、ピクセル・色・行順のメタデータ、フレームの識別子、不変の CPU リースが 1 つ含まれます。受け取る前にメタデータと epoch を検証します。Pending と Unchanged はピクセルの所有権を持ちません。表示時は宣言されたラスター/論理ジオメトリと色の解釈に従います。

各リースは一度だけ返却し、実際のアップロード API がピクセルを読まなくなってから返却します。owner と release コールバックはセッションの終了後も有効で、別のスレッドからも呼び出せます。返却処理では VM、デバイス、ウィンドウ、session、ホストサービスに触れてはいけません。フレームを保持してもゲームセッションは延長されず、コアが貸し出し中のピクセルを上書きすることもできません。ABI の CpuFrame ラッパーは、検証に失敗した場合でも受け取ったリースを返却します。

Source/SDK/shinki-emu-sdk は共通の仕組みを提供するもので、別のゲームランタイムを作るものではありません。runtime の値はプロセス内部でのみ使われます。native は設定の検証、epoch、キャンセル、遅れて届いたウィンドウ結果の拒否、独立した CPU リースを共通化し、native_input は VM を呼ばずに長さ上限のある入力をコピーします。NativeAudioOutput/NativeAudioConverter は、コアが所有するデバイススレッドに使われます。NativeAudioOutput::progress() は、受け付けたフレーム数と実際に再生されたフレーム数を 48 kHz のソース時間軸で返します。再生フレーム数からはデバイス遅延とリサンプラー遅延を差し引いてあり、コアはこれでメディアクロックを進めます。progress_reader() が返す NativeAudioProgressReader は複製でき、デバイススレッドが書き込み中でも待機中でも、別のスレッドから同じ時間軸を読めます。write は任意の長さを受け付け、デバイスブロックに満たない端数は次回へ持ち越します。デバイススレッドが待機に入る前に flush() を呼ぶと、受け付けた全フレームが再生まで届きます(詰めた無音も受け付け済みとして数えます)。ミキシング、メディアクロック、ネイティブのセーブ形式、ゲームのルールは引き続き各コアが担当します。具体的な API は SDK を参照してください。

パッケージ内のコアディレクトリ名は、ライブラリファイルの stem と同じです。

<library-stem>/
core.json
shinki_emu_<core>.dll # または libshinki_emu_<core>.so/.dylib
build.json
Resources/ # ネイティブコアが必要とする場合
licenses/
<ネイティブ依存ファイル>

core.json は shinki.emu.core_package.v1 を使い、plugin_id、library、version、abi、ファイルパスと SHA256 を記録します。マニフェストは自身を除くすべてのパッケージファイルを対象とします。コアライブラリは新しいファイル名プレフィックスと query シンボルを使います。パッケージングでは、アーキテクチャ、依存関係の閉包、ライセンスを確認し、パストラバーサル、リンク、大文字小文字の衝突を拒否し、まだ存在しない新しいディレクトリにだけ出力します。Manager はインストール前にパッケージ全体を検証し、旧製品のプロトコルやローダーの別名は受け付けません。コマンドはビルドとリリースを参照してください。

新しい外部パッケージは、元の upstream と組織 adapter の来歴を分けた identity を追加し、version がその安全な計算済み識別子と一致することを要求します。旧パッケージはこのフィールドを持たず、実際の SemVer を維持します。新 Manager はステージング前に catalog と package の plugin、version、identity を照合し、upstream/adapter の完全なラベルを表示します。C ABI と descriptor の版は独立したままです。版識別子の規則を参照してください。