ツール

Studio の MCP サーバーには以下の 77 個のツールがあり、プラグインがさらに追加できます。プラグインのツールを参照してください。ツールの説明はエージェントが読むものなので英語で書かれており、それぞれにいつ使うかが書かれています。「Studio での表示」は、Studio がエージェントログとステータスバーでその呼び出しを呼ぶ名前です。

「プロジェクトを変更」が「する」のツールは、エージェントによる変更を許可がオフの間は拒否されます。開いているプロジェクトに対するものは、エージェントの一時停止中、プロジェクトの凍結中、Team のライブセッション中にも拒否されます。それ以外のツールは読み取りだけを行います。テストプレイもこちらに含まれるため、エージェントは変更の許可がなくてもゲームを確認できます。

プロジェクトを対象とするツールはすべて、省略可能な project（プロジェクトフォルダーの絶対パス）を受け取ります。必要になるのは複数のプロジェクトを開いているときだけです。

セッションとガイド

プロジェクト

アセット

キャラクターと変数

キャラクターの編集は 1 回ごとに 1 ステップの取り消しになります。ほかの種類のキャラクターをレイヤー立ち絵に、またはレイヤー立ち絵をポーズに切り替えると見た目が失われるため、character_upsert、character_layered_set、character_layers_import は、呼び出しに confirmSwitch: true がない限りこれを拒否し、その見た目を選んでいるストーリーの行を示します。Live2D と Spine のキャラクターは読み取りだけで、設定は Studio のキャラクターエディタで行います。

ダイアログのアバターは、ダイアログとバックログでセリフの横に表示される顔の画像です。character_upsert は、より具体的なものがない場所に表示する defaultAvatar と、avatars を受け取ります。avatars はポーズごとに 1 枚、レイヤー立ち絵の場合は avatarAxes に挙げた軸のタグの組み合わせごとに 1 枚で、たとえば衣装にかかわらず表情ごとに 1 枚にできます。どちらもなければ、作者がキャラクターパネルを開いたときに Studio が立ち絵からアバターを切り出します。Live2D と Spine のキャラクターには既定のアバターだけがあります。

ストーリー

インターフェース

ui_install_standard_screens は、空のテンプレートから作ったプロジェクトや、インターフェースを失ったプロジェクトのためのものです。スタートはプロジェクト自身のストーリーを始め、画面が使うファイル、配色の項目、翻訳キー、入力アクション、セーブのフィールド、永続変数も一緒に取り込まれます。プロジェクトがすでに埋めているゲーム UI のスロットは、呼び出しが replace: true を渡さない限りそのままです。現在の開始ページが空なら、スプラッシュが開始ページになります。プロジェクトが実行していないプラグインを必要とするページ（Gallery の鑑賞画面など）は、それを開くボタンとともに除かれます。導入全体が 1 ステップの取り消しで、dryRun: true は書き込まずに何を追加するかを返します。

テンプレートストアのページはロジックのないレイアウトです。エージェントがブループリントでつなぐまで、スタートボタンもセーブスロットもスライダーも何もしません。すぐに動く画面が必要なら、標準画面から始めるほうが適しています。

ブループリント

すべての .bp ドキュメントが通るチェックは、別のページやゲーム UI の要素を指す Element ノードを拒否します。ブループリントが届くのは自分のページの要素だけだからです。また、本体がループに戻る配線を持たないループには警告を出します。そのループは 1 回だけ実行されて止まります。blueprint_remove は dryRun: true を受け取ります。

翻訳とボイス

翻訳単位は、ストーリーのセリフ 1 行、キャラクター・シーン・エンディング・/rename の名前、ページやコンポーネント上の語、名前付きの翻訳キー、プラグインが提供するテキストのいずれかです。どれも同じ id の体系を使うので、同じように一覧にして書き込めます。ストーリーのセリフの id は、そのままボイスのセリフの id でもあります。

• 状態。 翻訳の状態は missing、machine、translated、reviewed、stale のいずれかで、最後のものは翻訳した後に原文が変わったことを表します。localization_set は指定がなければ machine で書き込み、翻訳の表では機械翻訳と表示されます。音声の状態は missing、linked、approved、stale のいずれかで、ボイスの表ではリンク済みの音声は収録済み、古いものは古いと表示されます。
• マークアップ。 翻訳単位の原文では、ゲームが埋める値が {0}、装飾した語や間が ‹1›word‹/1› や ‹2/› のようなランタグで示されます。これらや {name} プレースホルダー、改行を失った翻訳も書き込まれますが、その単位には警告が付きます。
• リビジョン。 各単位には rev があります。エージェントが一覧にした後に原文が変わった単位は飛ばされ、新しい原文とともに返されます。
• 収録ファイル名のパターン。 既定は {scene}_{index}_{character} で、{locale} と {unit} も使えます。大文字と小文字、空白、句読点、フォルダーを無視して、各アセットのライブラリ上の名前と照合します。複数のアセットや複数のセリフが共有する名前は、推測せずにあいまいなものとして返します。

ゲームのテキストの言語は project_settings_set で、ボイスの言語は voice_settings_set で設定します。localization_set、voice_link、voice_auto_link は dryRun: true を受け取り、チェックだけを行って何も書き込みません。character_layered_set と character_layers_import も同じです。

チェックとビルド

テストプレイのツールは、ゲームのウィンドウを前面に出さずに操作します。テストプレイの答えにはどれも、その回の実行で Dev Mode が報告したエラーと警告が、それぞれのシーンと行、またはページとともに含まれます。Dev Mode のウィンドウの問題バーが数えるものと同じです。

プラグインのツール

プラグインは、エージェント向けに独自のツールを提供できます。これらは Studio のツールと並んで、プラグイン ID とツール名からなる名前で提供されます。. と - はすべて _ に置き換えられ、2 つの部分は __ でつながれます。Gallery の narraleaf.gallery.add_entries は narraleaf_gallery__add_entries として提供されます。

プラグインのツールが提供されるのは、そのプラグインを読み込み、そこで有効にしているプロジェクトが開いている間だけです。状況が変わると、Studio の通知ストリームを開いたままのクライアントには一覧が変わったことが通知され、それ以外のクライアントは次に一覧を取得したときに新しい一覧を受け取ります。agent_status は、開いている各プロジェクトが提供するプラグインのツールを示します。

プラグインのツールは Studio 自身のツールと同じ検査を通り、「プロジェクトを変更」の意味も同じです。設定 → エージェント連携 → プラグインのツールで、プラグインごとにすべてのツールをオフにできます。プラグインの作者は エージェント用ツールを参照してください。

プラグインはガイドの章を同梱することもでき、agent_guide に plugin:<plugin id> を渡して読みます。

Gallery

組み込みの Gallery プラグインは鑑賞画面を埋めます。ガイドの章は plugin:narraleaf.gallery です。表示名はプラグイン自身のもので、翻訳されていません。

テキスト形式

エージェントは、プロジェクトの内容を 3 つのテキスト形式で読み書きします。

読み取りはそれぞれ revision を返します。それを付けた書き込みは、その間に内容が変わっていれば stale_revision で拒否されます。story_apply、ui_apply、ui_patch、blueprint_apply は dryRun: true を受け取り、テキストをチェックするだけで何も書き込みません。

.story のシーンで表せることの一部です。

• 装飾した語。 セリフ、地の文、選択肢では、{b}…{/b}、{i}…{/i}、{color=…}…{/color} で行の一部を装飾でき、1 行の中で入れ子にできます。この形式にタグのない装飾（ルビや文字サイズなど）を使った行は » の行として読み戻されるので、そのまま残します。
• 正確な位置。 /show、/image、/text、/transform の pos=x,y は、オブジェクトの中心を置く位置です。x と y はステージに対する割合で、x は左端（0）から右端（1）、y は下端（0）から上端（1）へ向かいます。left、center、right はそれぞれ 0.25,0.5、0.5,0.5、0.75,0.5 です。pos= と一緒に使う xoffset= と yoffset= はデザイン上のピクセルを加え、yoffset が正なら上へ動きます。
• ブループリントを実行する行。 ストーリーの行は、再生がそこに来たときに自分のブループリントを実行できます。プラグインのノードを呼ぶものも含みます。たとえば CG が表示された瞬間に鑑賞画面の項目を解放する、実績を付与する、といった用途です。エージェントはブループリントを blueprint_apply で、行を story_apply で書き込みます。

形式の詳細はガイドの story-format、ui-format、blueprint-format の章にあります。どのコマンド、ウィジェット、ノードがあるかは、カタログ系のツール story_commands、story_command、story_targets、ui_widgets、ui_widget、ui_usage、blueprint_nodes、blueprint_node が答えます。これらは実行中の Studio から読み取るので、エージェントは記憶に頼らずこれらに問い合わせるべきです。

ガイド

agent_guide は chapter を 1 つ受け取ります。省略すると、ある章をすべて一覧にします。

同じ章は MCP リソース narraleaf://guide/<chapter> として、プラグインの章は narraleaf://guide/plugin/<plugin id> として提供されます。make_game プロンプトは、省略可能な brief を付けて workflow から作業を始めます。