Stack-chan MOD定義は、MOD Galleryと各エディタが共有する配布用メタデータです。
Moddableのmanifest.jsonはビルド方法を定義します。
.stackchan-blocks.jsonはブロックエディタで再編集するプロジェクトを保存します。
stackchan-mod.jsonは両者を置き換えず、正本となる編集ソースをsource.pathから参照します。
ルートオブジェクトは次のフィールドを持ちます。
- format：
tech.stackchan.modです。 - schemaVersion：MOD定義形式の互換性を示す整数です。
- id：Gallery内でMODを識別する逆ドメイン形式の文字列です。
- version：MOD自身のリリースバージョンです。
- type：正本となる編集ソースの形式です。
textまたはblockを指定します。 - name：Galleryへ表示する名前です。
- description：Galleryへ表示する説明です。
- source.path：MOD定義からの相対パスです。
- source.entrypoint：任意。テキストMODで、Galleryの「ソースを見る」から開く実装ファイルです。
- setup.url：任意。Galleryの「セットアップ手順」から開く絶対HTTPS URLです。
- targets：対応する実行対象のIDです。
- capabilities：任意。MODが実行時に必要とする公開capabilityです。
typeは実行形式を表しません。
テキストMODとブロックMODは、どちらもビルド後にXSアーカイブとして実行します。
type: "text"では、source.pathがModdableのmanifestを指します。
type: "block"では、source.pathが.stackchan-blocks.jsonを指します。
type: "text"でsource.entrypointを指定すると、ビルドの正本であるmanifestを維持したまま、利用者が最初に読むJavaScriptまたはTypeScript実装へ案内できます。
source.entrypointを省略した場合、「ソースを見る」はsource.pathを開きます。
setup.urlは、外部サービスやアプリケーションなど、MOD以外の準備が必要な場合に指定します。
Galleryはセットアップ手順を別タブで開きます。
Galleryは実機へ書き込む前に、capabilitiesを対象機種の能力および接続中hostのAPI世代と照合します。
hostのAPI世代は、ESP app descriptorのファームウェア版へ+stackchan.Nとして埋め込みます。
このsuffixを持たない従来hostはAPI 0として扱います。
API 1では、標準CoreS3 hostへaudio.usb、conversation.remote、ui.approvalを追加します。
これらを要求するMODはAPI 0のhostへ書き込めず、利用者へhost firmwareの更新を案内します。
任意のentrypointsは、XS archiveが公開する実行入口を列挙します。
省略時は従来どおり["mod"]として扱います。
mod：ホストrealmで実行するapp behaviorです。miniapp：制限されたCompartmentで定義を読み込み、ホスト所有のviewportへPiu UIを表示します。
二つを同じarchiveへ含める場合は["mod", "miniapp"]を指定します。
ホストは両者を独立して読み込みますが、mod.onLaunch()がfalseを返した場合はpackage全体の起動を中止し、mini-appも登録しません。
modを含むpackageはホストrealmで任意の処理を実行できるため、mini-app側のcontainmentにかかわらずpackage全体を信頼できる場合だけインストールしてください。
ビルド済みXSアーカイブを配布するMODは、任意のartifactsへ成果物を列挙します。
各成果物はformat: "xsa"、相対パス、対象機種を持ちます。
Galleryは編集ソースと実行成果物を別々に扱い、typeから実行互換性を推測しません。
すべてのパスはstackchan-mod.jsonがあるディレクトリからの相対パスです。
絶対パス、親ディレクトリ参照、バックスラッシュ、制御文字を含むパスは無効です。
この制約により、一つのMODパッケージから別のパッケージにあるファイルを暗黙に参照することを防ぎます。
機械検証にはstackchan-mod.schema.jsonを使用します。