最初のゲーム機能拡張

依存の追加

Agent Bridgeの配布版に対応するAPIを使います。Minecraftに依存しない共通モジュールの例です。

repositories {
    maven {
        url = uri("https://miyomiyo-mods.pages.dev/maven")
        content { includeGroup("dev.miyomiyo.agentbridge") }
    }
}
dependencies {
    compileOnly "dev.miyomiyo.agentbridge:agent-bridge-api:1.0.0"
}

実行時のAPIはAgent Bridgeが提供します。自分のMODへshadeして同梱しないでください。ローダーのメタデータではMOD ID mcagent へのclient依存を宣言します。専用サーバーではclient連携クラスを読み込まないでください。任意連携の場合は、APIを参照するクラスをロードする前に導入済みか確認します。

queryの登録

VisitExtension.javaはJavaだけで動く一式の例です。現在のワールド参加中に次元を移動した回数を返します。ゲーム機能APIと診断APIだけでコンパイルでき、本体の実装・Minecraft・JSONライブラリには依存しません。

META-INF/services/dev.miyomiyo.agentbridge.api.AgentExtensionへ次の一行を入れます。

example.VisitExtension

公開の引数なしコンストラクタとregisterではワールド参照、ファイルI/O、背景処理、AI接続を行いません。登録は全体として受理または拒否されます。registrarを後から使うために保持しないでください。

この例でmc_query(source="example_visit:visit", parameters={})を提供します。情報取得はqueryを優先し、独立した操作が必要な場合にtoolを追加します。詳しい利用案内は必要時に取得するguideへ置きます。

ツールと設定

ToolDefinitionでワールド/場所の有効範囲、効果、再送の扱いを宣言します。READ_ONLYは観測、ASSISTANCEは支援表示等の管理です。GAME_CHANGEはチートONと操作ごとの確認が必要で、コマンドの自動許可設定では許可されません。

ToolResult.okは成功、partialは不完全な観測を返します。presentedは役立つ支援を実際に表示した後だけ使います。進捗の受領通知ではなく、これだけでタスクが完了するわけでもありません。

設定はsettingsへページとStoreを登録します。本体が項目の配置と編集中の値を管理します。独自の設定画面はclient APIから登録します。設定や秘密情報を自動でモデルへ渡すことはありません。保存するのは既定値との差分だけとし、現在の既定値と同じ値は項目を省略します。

共通のUIツールへ表示形式を追加する

ExtensionRegistrar.ui(UiDefinition, ToolHandler)を使うと、独立したツールを増やさずにmc_ui_putへ表示形式を追加できます。nameはsurfaceの選択値、parametersSchemaはその形式の引数です。呼出しの外枠はtarget・taskId・opId・surface・parametersで共通です。

登録した名前・用途の説明・完全な引数schemaは、標準MCPのtools/listに載ります。何ができるかはdescriptionに書き、長い記法や例だけをguideへ分けてください。機能の存在をguideの中だけに隠さないでください。

UI操作はワールド単位、支援表示への効果、タスク内の操作IDによる再送管理として扱います。handlerは受理・表示・取消・退出後の片付けを所有します。名前は全拡張で一意で、組込みのquestionと同じ名前も登録できません。

画面やHUDを追加する場合

client APIはゲーム機能APIとは別のJARです。Minecraftとローダーを設定した開発プロジェクトに、対象に合うものを追加します。

groupとversionは上の例と同じです。Fabric用JARのMinecraft名はintermediaryで、Loomが開発環境の名前へ変換します。ゲーム機能APIと診断APIはPOMの依存宣言から取得されます。client APIも拡張へ同梱せず、実行時はAgent Bridgeの型を使います。画面の派生クラス用に、Javadocには公開型のprotectedコンストラクタも掲載します。

共通の設定UIを使う

項目を宣言する場合はSettingsFormとSettingFieldを登録します。配置・入力欄・表示条件・保存中の状態は本体のフォームが扱います。独自画面が必要な場合は、client APIのdev.miyomiyo.agentbridge.client.settingsにある同じ部品を使えます。

例えばSettingsScreen.init()内では次のようにボタンを置けます。

var frame = settingsFrame(320, 48);
addRenderableWidget(SettingsWidgets.button(
        Component.translatable("gui.back"), button -> onClose())
    .bounds(frame.left(), height - 32, frame.width(), 20).build());

renderContentsからrenderSettingsFrame(graphics, frame)を呼びます。独自画面は編集中の値・保存・取消・親への復帰を自身で管理します。部品の描画や画面のresizeだけでは保存されません。任意のMinecraft Screenを登録する契約も変わりません。

画面の被覆と入力フォーカス

ClientOverlayScreenとSettingsScreenは、既定ではゲームに重ねるOVERLAYです。背景を全面に描く場合は、コンストラクターで次のように宣言します。

super(title, ScreenPresentation.FULLSCREEN, 0xEF111923);

共通基盤が背景を描き、Minecraftへ一時停止を要求します。実際に止まるのはLAN公開していないシングルプレイだけです。UI、通信、背景処理を自分で停止/再開する必要はありません。全画面では、InvMove導入時の移動も接続形態に関係なく禁止されます。

独自のネイティブScreenはScreenPresentation.Hostで被覆を公開できます。この場合、背景描画と標準のpause要求は画面の実装側が担当します。共通のネイティブ確認画面はClientConfirmationScreenを使えます。画面名や設定/資料などの用途から判定する仕組みではありません。

テキスト入力はMinecraftの単行/複数行部品を使い、入れ子の部品はContainerEventHandler.getFocused()で実際のフォーカス先を返してください。InvMoveとの連携はその経路を観測します。入力がないOVERLAYではInvMoveの通常設定へ委ねるので、カーソルが表示されているだけで移動を止めることはありません。

キー操作を追加する場合

ClientRegistrar.shortcutへShortcutKeyとKeyModifiersを宣言します。同じキーIDの修飾別操作は、一つのMinecraftキー設定を共有します。画面やワールドの外で受け取った入力は、後から再生しません。

本体のShortcutKey.ASSISTANTは既定G（修飾なしは質問・セットアップ、Shiftはマウス操作）。ShortcutKey.LAYOUTは既定未割当です。Hの資料箱はReportsが独自のキーとして登録します。拡張は独自ID・翻訳キーで追加でき、同じキー・修飾の重複登録は拒否されます。通常のキー登録時に宣言し、ワールドへ入るたびに登録し直さないでください。