新規制作とSSP資産への対応

Utataneで動くコンテンツを新しく作る場合と、SSPなどで動いている既存コンテンツを対応させる場合の入口をまとめます。Utatane専用形式へ作り直す必要はありません。まず一般的な伺かのディレクトリ構成と電文を保ち、macOSで実行できない部分だけを切り分けてください。

Utataneは開発中で、SSPの全機能を再現しているわけではありません。対応の有無はゴースト互換状況、Native SHIORI / SAORI、UKADOC互換表から確認できます。

最初に選ぶ経路

作るもの	新規に作る場合	SSP向けの既存資産がある場合
ゴースト	カタログから導入できるYAYA、里々、華和梨、美坂などを使うと、Windows DLLを同梱したままでも辞書をmacOS上で実行できます	構成を変えずにNARまたはSSPフォルダから取り込み、導入したSHIORIで動く範囲を先に確認します
SHIORI	辞書型の既知SHIORIを使うか、標準SHIORI ABIのmacOS用dylib、またはSHIOLINK外部プロセスとして作ります	Windows固有コードを分離してmacOS用dylibを追加します。未移植DLLは設定済みWineでの互換確認に限られます
SAORI	カタログの対応SAORIを使うか、標準SAORI ABIのmacOS用dylibとして作ります	SHIORIから送るSAORI/1.0電文を維持し、Windows API部分だけをmacOS向けに移植します

「Windows版を残しつつUtataneにも対応する」なら、OSごとに配布物を完全分離する前に、同じ辞書・設定を両方で使えるか試すのが近道です。Utataneは、代表的なWindows DLL名と辞書構成を見て導入済みのmacOS用dylibを選びます。

ゴーストを新しく作る

最低限、次の形で用意します。実際には使用するSHIORIの辞書やシェル定義も必要です。

example-ghost/
├── descript.txt
├── ghost/
│   └── master/
│       ├── descript.txt
│       ├── 使用するSHIORIの設定・辞書
│       └── SHIORI名.dll（対応dylibが導入済みなら識別用）
└── shell/
    └── master/
        ├── descript.txt
        ├── surfaces.txt
        └── surface0.png

ghost/master/descript.txtのshioriには使用するモジュール名を書きます。省略した場合は従来のベースウェアと同じくshiori.dllを探します。古いゴーストとの互換用にalias.txtの指定も読みますが、新規作成ではdescript.txtへ明記してください。

最初は次の小さい動作だけを作り、順番に増やすと原因を分けやすくなります。

OnBootで短いSakuraScriptを返します。
OnClose、OnAITalkを返します。
OnMouseDoubleClickとOnChoiceSelectを追加します。
サーフェス、SERIKO、着せ替えを追加します。
SAORI、ネットワーク更新、ゴースト間通信など外部要素を追加します。

SakuraScriptやイベントごとの差は、SakuraScript互換表とSHIORIイベント互換表で確認してください。

既存のSSP向けゴーストを対応させる

最初からUtatane専用の分岐を足さず、元のNARをインストールするか、「SSPフォルダから取り込む」で確認します。次の順で問題を分けます。

ゴースト一覧に名前が出るか
OnBootの会話とサーフェスが出るか
ランダムトーク、クリック、選択肢が動くか
終了と再読み込み後に変数が保たれるか
追加シェル、バルーン、着せ替え、更新が動くか
SAORIや外部プログラムを使う機能だけを個別に試します。

起動しない場合は、まずghost/master/descript.txtのshiori、ファイル名の大文字小文字、辞書の文字コードを確認します。macOSのファイルシステムでは、配布先によって大文字小文字の違いが問題になることがあります。

Windows DLL、EXE、COM、レジストリ、Windowsのウィンドウハンドルに依存する機能は、そのままでは動きません。問題がある機能ごとに、次の順で検討してください。

同じ機能を持つ対応SAORIへ置き換えます。
その機能を使わずに済む代替動作を用意します。
必要ならmacOS版モジュールを追加します。

Wineは利用者側の追加設定が必要です。通常の会話までWineを必須にする前に、内蔵実装で動く範囲を確認してください。

SSPとUtataneで応答を変える必要がある場合でも、まず実際に異なる項目だけに限定してください。OS判定、HWND、プロセス操作などは互換値や未対応値になることがあります。共通のSHIORIイベントとSakuraScriptで済む処理は共通化します。

SHIORIを対応させる

既知の辞書型SHIORI

YAYA / AYA、里々、華和梨、美坂などは、ゴーストに同梱されたdylib、共通導入版の順に探します。既存ゴーストはWindows用DLLを識別名として残したまま動かせる場合があります。対応する辞書形式、制約、実験的機能はNative SHIORI / SAORIを参照してください。

新規ゴーストでは、SSPでも同じ辞書を使える既知SHIORIを選ぶと一つの配布物にまとめやすくなります。ただし、内蔵実装が元のSHIORIの全機能を再現しているとは限りません。使う関数や構文は実際に両方で確認してください。

独自SHIORI

自分でSHIORIを開発する場合は、SHIORI開発者向け対応ガイドを参照してください。新規開発と既存Windows版の移植、macOS用モジュールの関数の型・バッファの所有権、SHIOLINKの通信手順、配布前の確認を説明しています。

macOS用モジュールはghost/masterへ配置します。両OS向けに配布する場合は、descript.txtにshiori,example.dllとshiori.macos,libexample.dylibを併記してロード先を分けられます。Windows環境しか持っていない場合のmacOSビルド手順と、言語ごとの接続方法も専用ガイドにあります。

SAORIを対応させる

まず対応SAORIの一覧に同じ機能がないか確認します。対応SHIORIがSAORI構文から呼び出す場合、mciaudior.dllなどの既知名は導入済みのdylibへ接続されます。

独自SAORIは標準SAORI/1.0の電文と、SHIORIと同じloadu（またはload）、request、unloadを持つmacOS用モジュールとして移植します。既存版と要求・応答の意味を揃え、ファイル、音声、クリップボードなどOS依存部分だけを差し替えると、呼び出す辞書を共通化できます。

注意点は次の通りです。

モジュールと相対パスはghost/master内へ置きます。
macOS版はUTF-8のloaduを優先します。
Result、Value、ArgumentNなど、元のSAORIが返すヘッダーをテストします。
外部EXE、COM、独自ウィンドウ、Windows HWNDを前提にしません。
失敗や未対応操作は、空の成功応答ではなく呼び出し側が判別できる応答にします。

Windows版とmacOS版でファイル名を変える場合は、利用するSHIORI側でOSに応じてロード先を選ぶ必要があります。Utataneが任意のWindows SAORI名からmacOS版を自動推測するわけではありません。

Utataneでの確認方法

配布前の確認には、NARを使う方法と展開済みフォルダを使う方法があります。

macOS環境がない場合や、まず構成だけ確認したい場合: Utatane NAR検査へNARをアップロードします。SHIORIの判定、Utataneでの対応状況、基本的な構成上の問題を確認できます。
利用者と同じ条件: NARをUtataneへドラッグ＆ドロップして新規インストールします。
既存環境から確認: Utataneの「SSPフォルダから取り込む」を使います。
繰り返し編集: UtataneのコンテンツフォルダをFinderで開き、対象を編集して「現在のゴーストを再読み込み」します。
Utatane本体のDebugビルドで確認: Content/Local/Ghosts/へ置く（配布条件のある実物はコミットしない）

NARには一般的なinstall.txtを入れ、少なくともcharset、type、name、directoryを設定します。Utatane専用のインストール定義は必要ありません。refresh、同梱シェル・バルーンなど対応済み項目と制約はテキストファイル互換表で確認してください。

問題が起きたらデバッグ画面のログをコピーし、次を一緒に残してください。

UtataneのバージョンとmacOS、CPU（Apple Silicon / Intel）
ゴースト、SHIORI、SAORIの名前とバージョン
新規インストールか、既存環境からの取り込みか
再現に必要な操作と、期待した結果、実際の結果
SHIORI要求・応答、モジュールの読み込み失敗、文字コード変換失敗が分かるログ

状態ファイルが影響する問題は、新規インストール時と継続利用時を分けて確認します。Utataneの内蔵実装は、元のゴーストを不用意に変更しないため、可変状態をApplication Support側へ分離して保存するものがあります。

配布前チェックリスト

配布するNARが完成したら、次を確認してください。

SSPとUtataneの両方が対象なら、それぞれで新規インストールできること。
起動・終了、ランダムトーク、マウス反応、選択肢が動くこと。
再読み込みとアプリ再起動後も、保存した状態が保たれること。
ファイル名の大文字小文字と文字コードが正しいこと。
Windows専用機能に代替動作があるか、利用できないことを説明していること。
Apple Silicon・Intelの両方が対象なら、macOSモジュールも両CPUに対応していること。
更新URLを使う場合は、インストール済みの環境からも更新できること。
READMEに、確認したUtataneのバージョン、動く範囲、既知の制約を記載していること。

完全互換を確認できていない場合は、「Utatane対応」とだけ書くより、確認済みの操作と動かない機能を具体的に記載してください。問題報告や対応追加の相談では、再配布できないゴースト本体をリポジトリへ追加せず、最小の再現データとログを添えると調査しやすくなります。

Web上のNAR検査は静的な構成確認です。実際の表示、会話、SakuraScript、SERIKO、SAORIや外部プログラムの動作を保証するものではないため、配布前にはUtatane本体でも確認してください。