Operations ja

English | 日本語

実験的な機能です。 フレームワーク 1.4.0 で入ったもので、この先のバージョンで変わったり、無くなったりするかもしれません。

Operations（操作の登録簿）は中核（DragNWash.ModFramework、クラス Operations）にある登録簿で、各ライブラリや Mod にできることを、名前と単純な引数で呼べるようにします。Console の op コマンドも Bridge の MCP のツールも、裏ではこれを使っています。MCP のツールは、この PC の AI クライアント（Claude Code・VS Code・Cursor）がゲームを読むためのものです。中核が持つのは登録簿だけで、操作はそれぞれのライブラリが自分で登録します。

設計は docs/API_PLAN.ja.md（第 1 段階）にあります。

操作とは

部分	意味
名前	library.noun.verb。小文字で空白なし：inspector.member.get、saves.flags.list
説明	何をするかを 1 行で。人と AI クライアントが読みます
引数	それぞれに名前、型（String、Number、Boolean）、必須かどうか、説明、決まった値しか受け付けないときはその選択肢
種類	Read（何も変えない）か Write（ゲームの中の何かを変える）
戻り値	何を返すかの 1 行
持ち主	登録した Mod の GUID

ベクトルと色は、Inspector の行と同じ書き方のテキストで渡します。

登録する

Operations.Register(MyMod.Guid, "mymod.items.list", "The items my mod knows, optionally only those whose name contains a text.",
    OperationKind.Read, "a list of { name, count }",
    args =>
    {
        string filter = args.String("filter");
        int max = args.Int("max", 20);
        return Items(filter, max);   // リスト、辞書、文字列、数値、true/false
    },
    Operations.Parameter("filter", OperationType.String, "Only names that contain this."),
    Operations.Parameter("max", OperationType.Number, "At most this many (20 when left out)."));

• Operations.Register(ownerGuid, name, description, kind, returns, run, params parameters) は Operation を返します。名前がすでに使われていれば null を返し、誰が使っているかをログに書きます。大文字や空白を含む名前は例外になります。
• Operations.Parameter(name, type, description, required = false, params choices) で引数を作ります。選択肢を渡すと、その値だけを受け付けます（大文字・小文字は区別しません）。
• 関数には OperationArgs が渡され、Has(name)、String(name, fallback)、Number(name, fallback)、Int(name, fallback)、Bool(name, fallback) で引数を読めます。
• 返すのは単純な値で、null、文字列、数値、true/false、それからそれらのリストと、キーが文字列の辞書です。それ以外はテキストにして書き出します。失敗させたいときは、メッセージつきで例外を投げてください。
• ほかの Mod とぶつからないように、操作の名前は自分の Mod の名前で始めてください（mymod.…）。

探す・呼ぶ

• Operations.All ですべての操作が名前順に、Operations.Find(name) で 1 つが手に入ります（なければ null）。
• Operations.CallNow(name, args, caller) はその場で呼びます。メインスレッド専用で、OperationResult（Ok、Value、Error、ToJson()）を返します。
• Operations.Call(name, args, caller, done) はどのスレッドからでも呼べます。操作は次のフレームにメインスレッドで動き、結果はそこで done に渡されます。
• caller は、誰が呼んだか（"console"、"mcp:<クライアント>"）をログに残すための名前です。
• 引数は、操作が動く前に引数の定義と突き合わせます。必須の引数がない、知らない名前がある、型が違う、といった場合はエラーです。テキストは、引数の型に合わせて数値や true/false に変えます。
• Operations.ToJson(value, indented) で、結果を JSON にします。

すべての呼び出しに共通のきまり

• Unity のオブジェクトはメインスレッドでしか触れないので、誰が呼んでも、操作はメインスレッドで動きます。
• JSON で 200,000 文字（Operations.MaxResultChars）を超える結果はエラーになり、範囲を絞って呼び直すよう求めます。
• 呼び出しはすべて、誰が呼んだか、引数、うまくいったかどうかと一緒にログに残ります。書き換える操作は Info、読む操作は Debug です。誰が呼んだかは、操作の側から OperationArgs.Caller で読めます。
• 書き換える操作は OperationArgs.TakeBack(label, undo, before, after) で戻し方を渡し、登録簿はそれを Operations.Written で知らせます。Inspector の History にほかの Mod が変えたものも並ぶのは、これを聞いているからです。undo を Func<bool> で書けば、本当に戻せたかどうかを返せます。オブジェクトが無くなっていたり、誰かがあとから書き換えていたりすれば戻せていないことになるので、数える側は試した回数ではなく、実際に戻した件数を数えられます。
• Mod を読み直したり外したりすると、その Mod の操作も一緒に消えます。
• Register の直後に Operation.Audience を設定すると、その操作をどの入り口に出すかを決められます。入り口は Console（F1 のウィンドウ）、Page（この PC の Bridge のページ）、Mcp（AI クライアント）、Graphs（データ Mod のグラフ）で、初期値は 4 つすべての Anyone です。ゲーム自身のコードを見せるもの（コードグラフ）は Console | Page で、エディター自身の操作も、書き込みを含めて Console | Page です。
• Bridge が AI クライアントに出すのは読む操作だけで、それも Mcp を含むものに限ります。書き込みは、誰が求めても出しません。

Console の op

Console で使えます（Tool window ライブラリに入っています）。

コマンド	内容
op	すべての操作の一覧。書き換えるものには [write]
op help <name>	1 つを説明する（種類、持ち主、引数ごとの型、戻り値）
op <name> key=value ...	実行して、結果を JSON で表示（リストは 1 行に 1 つ）

名前と引数は Tab で補完できます。

op inspector.objects.find text=Light max=10
op saves.flags.list slot=1 filter=intro

フレームワークが登録する操作

bridge.page.open のほかは、すべて読む操作です。

ライブラリ	操作	引数	返すもの
中核	mods.list		Mods 画面の Mod：guid、名前、バージョン、読み込み済みか、次の起動でオンか、ライブラリか、作者、説明
中核	mods.network		このセッションで Mod がつないだ先と、それぞれ申告済みか
中核	game.info		フレームワーク・Unity・グラフィックスのバージョン、Direct3D 12 かどうか、OS、画面、開発者ツール
中核	scene.list		アクティブなシーン、読み込まれているシーン、ゲームのビルドにあるすべてのシーン
Tool window	log.read	max、source、level	Console の最新の行：時刻、レベル、出どころ、テキスト
Inspector	inspector.objects.find	text（必須）、max	名前にそのテキストを含むオブジェクト：パス、シーン、有効か
Inspector	inspector.objects.children	path	オブジェクトの子。パスがなければ一番上のオブジェクト
Inspector	inspector.components.list	path（必須）	オブジェクトのコンポーネントを順に、同じ型の中での番号つきで
Inspector	inspector.member.get	path、component（どちらも必須）、index、member、private	コンポーネントのメンバーを Inspector の表示どおりに、または 1 つのメンバー
Inspector	inspector.selection.get		Inspector で選ばれているもの
Inspector	code.graph	method（必須）、stub	ゲームのメソッドをブロックと分岐で（ページ専用）
Inspector	code.type	type（必須）	型のメソッドをまとまりごとに、その間の呼び出しとともに（ページ専用）
Inspector	code.callers	method（必須）	そのメソッドを呼ぶメソッド（ページ専用）
Inspector	code.search	text（必須）、max	名前にそのテキストを含む型とメソッド（ページ専用）
Inspector	code.stats		コードの索引の大きさ（ページ専用）
Assets	assets.textures.list	filter、max	メモリにあるテクスチャと大きさ
Assets	assets.materials.list	filter、max	読み込まれているマテリアルと、そのシェーダーとテクスチャ
Assets	assets.meshes.list	filter、max	読み込まれているメッシュと、頂点数・サブメッシュ数
Assets	assets.replacements.list	filter	Mod が入れているテクスチャの差し替え：テクスチャ、Mod、言語、ファイル
Assets	assets.fonts.language		フォントを用意している言語
Dialogue	dialogue.current		動いているノード、台詞か選択肢が出ているか、最後の台詞
Dialogue	dialogue.recent	text、max	このセッションで出た最近の台詞と選択肢（100 件まで）、話し手つき
Text	text.rewriters		ゲームのテキストを書き換える Mod を、動く順に
Text	text.shown	text（必須）、max	画面のテキスト：ゲームが設定したものと、表示されているもの
Flags and saves	saves.list		セーブスロットと、そのレベル、履歴のコピーの数
Flags and saves	saves.flags.list	slot（必須）、filter	スロットのイベントフラグと、フラグカタログの説明
Flags and saves	saves.flags.get	slot、id（どちらも必須）	1 つのイベントフラグ
Bridge	bridge.page.open（書き換え）	focus	この PC の Bridge のページを、サインインした状態で開く
Overrides	objects.writes		このセッションで Overrides ライブラリが変えたもの、誰が頼んだか、同じところを変えた別の Mod

1.4.1 では、Overrides ライブラリにグラフ向けの書き込みが 3 つ（objects.member.set、objects.material.set、objects.active.set）入り、Graphs ライブラリ自身の graphs.* も入りました。こちらはページのエディター専用で、ほかからは見えません。

各引数の説明と範囲は、Console の op help <name> で見られます。