登録ポイント

登録ポイントは、プラグインがエディターに機能を追加する場所です。すべて Register(host) の中で host.Add…(データ型) として呼び出します。データ型は C# の record です。既定値のある項目は名前付き引数 (Order: 600) で渡せます。

登録ポイント	データ型	SDK	エディター画面
AddMenuItem	NpMenuItem	1.0	メニューバー
AddQuickAddItem	NpQuickAdd	1.0	メインツールバー「追加」
AddCommand	NpCommand	1.0	「コンソール」パネル
AddImporter · AddExporter	NpFileFormat	1.0	ファイル › インポート: … ・ビルド › エクスポート: …
AddContentTab	NpContentTab	1.0	下部エリアのパネル (ウィンドウメニュー)
AddMode	NpMode	1.0	モード列・ツールパネル・ビューポートのクリック
AddActorType	NpActorType	1.0	アウトライナー「タイプ」列
AddCellGuard	Func<int,int,int,bool>	1.0	すべてのブロック編集
AddSymmetry	Func<IReadOnlyList<NpBlock>, IEnumerable<NpBlock>>	1.0	配置・破壊・ブラシ・図形
AddShotScenario	NpShot	1.0	--np-shot=<id>
AddShortcut	NpShortcut	1.1	ツール › ショートカット…
AddSceneEvent	NpSceneEvent	1.2	ワールドロジック — ワールドロジック type の追加

共通のルールです。

• Id にはエディター内で ext.<プラグイン id>. が付きます。プラグイン内で重複しなければ十分です。
• Id (コマンドは Name、アクタータイプは Kind) が空、または実行関数 (Run ・ Spawn ・ Build) が null の場合は登録時に例外になります。その場合、プラグイン全体が有効になりません。
• 登録したコールバックで例外が発生すると、そのプラグインは隔離されます。
• Order は同じ場所の中での順序です。小さいほど前に来ます。既定値は 500 です。
• 画面の文字列に絵文字・絵文字記号を入れないでください。メニュー・タブ・モード名の絵文字記号は画面から取り除かれます。アイコンは Icon 項目にアイコン名 (prefab ・ block ・ light ・ trigger ・ logic …) で指定します。

AddMenuItem — メニュー項目

public sealed record NpMenuItem(string Id, string Menu, string Label, Action Run, string Shortcut = "", int Order = 500);

項目	説明
Id	項目 id
Menu	"파일" ・ "편집" ・ "창" ・ "도구" ・ "빌드" ・ "도움말"。それ以外の名前なら「ヘルプ」の前に新しいメニューを作ります。
Label	メニューに表示される文字列
Run	押すと実行
Shortcut	ショートカットの文字列 (例 "Ctrl+Alt+H")。解釈できるキーであればメニューの文字列の横に表示され、押すと実行され、ツール › ショートカット… で変更できます。
Order	メニュー内の順序。100 の位が変わるところに区切り線が入ります (例 499 と 500 の間)。

host.AddMenuItem(new NpMenuItem("hollow", "도구", "선택 속 비우기", () =>
{
    if (host.World.Selection is not { } b) { host.Message("먼저 영역을 고르세요"); return; }
    int n = host.World.Edit("속 비우기", e =>
    {
        for (int y = b.Min.Y + 1; y < b.Max.Y; y++)
            for (int z = b.Min.Z + 1; z < b.Max.Z; z++)
                for (int x = b.Min.X + 1; x < b.Max.X; x++)
                    e.Clear(x, y, z);
    });
    host.Message($"{n:N0}칸 비움");
}, Order: 550));

• 「ウィンドウ」メニューの項目は、パネル一覧の下に追加されます。
• エクスポート的な項目は「ビルド」に置きます。

AddQuickAddItem — クイック追加

public sealed record NpQuickAdd(string Id, string Label, string Category, Action<NpQuickAddContext> Spawn,
    string Keywords = "", int Order = 500, string Icon = "", string IconState = "");
public sealed record NpQuickAddContext(INpWorld World, NpCell Place);

項目	説明
Label	一覧に表示される名前
Category	分類名。新しい名前なら、内蔵の分類の後ろに新しい分類ができます。
Spawn	選ぶと実行。ctx.Place = 配置するマス (マウスの下のブロック面の外側のマス、なければ画面中央の手前)
Keywords	検索語 (空白区切り)。韓国語・英語を一緒に入れると見つけやすくなります。
Icon	アイコン名 (例 "prefab" ・ "light")
IconState	アイコンとして描くブロックステートの文字列。指定があれば Icon より優先します。

host.AddQuickAddItem(new NpQuickAdd("lamp_post", "가로등", "도로", ctx =>
    ctx.World.Edit("가로등", e =>
    {
        for (int y = 0; y < 3; y++) e.Set(ctx.Place.X, ctx.Place.Y + y, ctx.Place.Z, "minecraft:dark_oak_fence");
        e.Set(ctx.Place.X, ctx.Place.Y + 3, ctx.Place.Z, "minecraft:lantern[hanging=false]");
    }),
    Keywords: "lamp light 가로등", Icon: "light", IconState: "minecraft:lantern"));

AddCommand — コンソールコマンド

public sealed record NpCommand(string Name, string Usage, string Help, Func<string[], string> Run);

項目	説明
Name	コマンド名。空白なしで書きます。接頭辞が付かないため、前に自分の名前を付けます (例 road_count)。
Usage	使い方 1 行 (例 "road_count [블록 id]")
Help	説明 1 行
Run	引数 (名前の後ろの語) → コンソールに表示される結果の文字列

host.AddCommand(new NpCommand("road_count", "road_count [블록 id]", "선택 안에서 그 블록 수를 셈", args =>
{
    string id = args.Length > 0 ? args[0] : "minecraft:stone";
    long n = host.World.Blocks(host.World.Selection).LongCount(b => b.State.StartsWith(id));
    return $"{id}: {n:N0}칸";
}));

• 既に存在する名前 (内蔵・他のプラグイン) なら、そのコマンドは追加されません。
• Run で例外が発生すると、コンソールに失敗と表示され、プラグインは隔離されます。

AddImporter · AddExporter — ファイル形式

public sealed record NpFileFormat(string Id, string Label, string[] Extensions, Action<string> Run, int Order = 500);

項目	説明
Label	メニューの文字列。ファイル › インポート: Label ・ビルド › エクスポート: Label と表示されます。
Extensions	拡張子の一覧 (ドットなし、例 new[] { "csv" })。ファイルダイアログのフィルターに使います。
Run	ユーザーが選んだファイルのフルパスを受け取ります。
Order	メニュー内の順序

host.AddExporter(new NpFileFormat("road_stats", "블록 통계 CSV", new[] { "csv" }, path =>
{
    var rows = host.World.Blocks(host.World.Selection)
        .GroupBy(b => b.State.Split('[')[0])
        .OrderByDescending(g => g.Count())
        .Select(g => $"{g.Key},{g.Count()}");
    File.WriteAllLines(path, rows.Prepend("block,count"), new System.Text.UTF8Encoding(true));
}));

• エクスポートダイアログの既定のファイル名は <ワールド名>.<最初の拡張子> です。
• インポートでブロックを変更するときも、World.Edit 1 回にまとめます。

AddContentTab — パネル

public sealed record NpContentTab(string Id, string Label, Func<NpUi> Build, int Order = 500);

項目	説明
Label	パネルのタイトル。ウィンドウメニューのパネル一覧にもこの名前で表示されます。
Build	パネルの内容 (NpUi)。プラグインを有効にするときに 1 回呼び出します。
Order	パネル一覧での順序

host.AddContentTab(new NpContentTab("panel", "도로", () => new NpUi()
    .Title("도로 만들기")
    .Number("폭", _width, 1, 9, 1, v => _width = (int)v)
    .Check("가로등", _lamps, v => _lamps = v)
    .Button("선택 영역에 깔기", () => host.Message($"폭 {_width}"))));

• パネルは下部エリアに閉じた状態で作成されます。ユーザーがウィンドウメニューから開きます。開いた後は、別のエリアにドラッグしたり、フローティングウィンドウとして切り離したりできます。
• アイコンは plugin の画像です。
• NpUi の使い方は パネル UI (NpUi) にあります。

AddMode — モード

public sealed record NpMode(string Id, string Label, Func<NpUi>? Panel = null, Func<NpClick, bool>? OnClick = null,
    Action? Enter = null, Action? Exit = null, string Shortcut = "", int Order = 500);
public sealed record NpClick(NpCell Hit, NpCell Place, bool Shift, bool Ctrl);

項目	説明
Label	モード名 (モード列のツールチップ・ツールパネルの見出し)
Panel	ツールパネルに表示される内容。最初に表示するときに 1 回作成し、再利用します。なければタイトルだけが表示されます。
OnClick	ビューポートの左クリック。Hit = 当たったブロックのマス、Place = その面の外側のマス (配置する場所)。処理した場合は true を返します。
Enter ・ Exit	モードに入るとき・出るとき
Shortcut	モードに切り替えるショートカットの文字列
Order	プラグインのモード同士の順序。プラグインのモードは常に内蔵モードの後ろに来ます。

host.AddMode(new NpMode("flag", "깃발 꽂기",
    Panel: () => new NpUi().Title("깃발").Label("왼쪽 클릭 = 깃발 · Shift+클릭 = 지우기"),
    OnClick: c =>
    {
        var p = c.Shift ? c.Hit : c.Place;
        host.World.Edit(c.Shift ? "깃발 지우기" : "깃발", e =>
        {
            if (c.Shift) { for (int i = 0; i < 3; i++) e.Clear(p.X, p.Y + i, p.Z); return; }
            e.Set(p.X, p.Y, p.Z, "minecraft:oak_fence");
            e.Set(p.X, p.Y + 1, p.Z, "minecraft:oak_fence");
            e.Set(p.X, p.Y + 2, p.Z, "minecraft:red_wool");
        });
        return true;
    },
    Exit: () => host.Draw.Clear()));

• OnClick があると、そのモードでのビューポートの左クリックはすべて OnClick に送られます。既定のブロック配置は行いません。
• ブロックに当たらないクリック (空) では OnClick を呼び出しません。
• ドラッグ (押したまま動かす) はまだ受け取れません。クリックのみ受け取ります。
• モード列の先頭 8 個より後ろのモードは「その他」に入ります。プラグインのモードは通常「その他」にあります。
• プラグインを無効にするときにそのモードを使用中だった場合は、ブロックブラシモードに戻ります。

AddActorType — アクタータイプ

public sealed record NpActorType(string Kind, string Label, string Color = "#9a9a9a");

項目	説明
Kind	アクターの kind 文字列。前に自分の名前を付けます (例 "myroad.zone")。
Label	アウトライナー「タイプ」列の文字
Color	「タイプ」列の色 "#rrggbb"。解釈できなければ灰色です。

host.AddActorType(new NpActorType("myroad.zone", "도로 구역", "#44aaff"));

• その kind のアクターがアウトライナーに表示されるときの文字と色を決めます。
• SDK にはアクターを作成する API はまだありません。

AddCellGuard — セルガード

void AddCellGuard(Func<int, int, int, bool> guard);

true を返したマスは、どの編集でも変更できません。ブラシ・図形・塗りつぶし・コンソールコマンド・他のプラグインの World.Edit のすべてに適用されます。元に戻す・やり直しは検査しません。

host.AddCellGuard((x, y, z) => y < 0);   // y 0 より下は変更不可

• 複数のガードがある場合、1 つでも true ならブロックします。
• マスごとに呼び出されます。非常に軽い処理にしてください (辞書・ボックスの比較程度)。

AddSymmetry — 対称

void AddSymmetry(Func<IReadOnlyList<NpBlock>, IEnumerable<NpBlock>> expand);

ユーザーの編集 (配置・破壊・ブラシ・図形・ドラッグボックス・塗り) が変更するマスの一覧を受け取り、拡張した一覧を返します。内蔵の対称の後ろに連結されます。

host.AddSymmetry(cells => cells.Concat(cells.Select(b => b with { X = -b.X })));   // X=0 の面でミラー

• 元のマスを含めて返します。除外すると元の編集が消えます。
• 空気にするマス (破壊) は State が "minecraft:air" です。

AddShotScenario — 画面検証

public sealed record NpShot(string Id, Func<INpShotApi, Task> Run);

INpShotApi のメンバー	説明
World	ワールド (INpWorld)
LookAt(float ex, float ey, float ez, float tx, float ty, float tz)	カメラを目の位置 → 注視点へ向ける
Frames(int n)	n フレーム待つ (await)
Check(bool ok, string what)	判定を 1 つ記録 (PASS/FAIL)
Shot(string name)	画面を PNG で保存 (await)

サンプルと実行方法、制限は テストとデバッグ にあります。

AddShortcut — ショートカット

public sealed record NpShortcut(string Id, string Label, string Key, Action Run, string Mode = "");

項目	説明
Id	ショートカット id。ユーザーが変更したキーはこの id で保存されます。
Label	ショートカットウィンドウに表示される名前。前にプラグイン名を付けると見つけやすくなります (例 "도로: 속 비우기")。
Key	既定のキー文字列。下の表に従います。
Run	押すと実行
Mode	"" = どこでも。モード id = そのモードでのみ。自分のモードなら AddMode に書いた id をそのまま使います。

host.AddShortcut(new NpShortcut("hollow_key", "도로: 선택 속 비우기", "Ctrl+Alt+H", Hollow));
host.AddShortcut(new NpShortcut("flag_undo", "깃발: 마지막 지우기", "Shift+J", RemoveLast, Mode: "flag"));

キー文字列	解釈
Ctrl+Alt+H ・ ctrl + alt + h ・ Cmd+K (= Ctrl)	はい
Shift+F5 ・ Ctrl+Enter ・ Alt+Space ・ Ctrl+[	はい
J (修飾キーなしのキー 1 つ)	はい。内蔵キーと衝突しやすいため推奨しません。
1~8 ・ W/E/R ・ Ctrl++	いいえ → 登録時に例外 → プラグインが有効にならない

• キー = Ctrl ・ Alt ・ Shift とキー 1 つです。キー名は文字・数字 1 つ、F1〜F24、Enter ・ Space ・ Delete ・ Esc などの名前です。
• ユーザーはツール › ショートカット… (Ctrl+Alt+K) でキーを変更します。変更したキーは、プラグインを再び有効にしても残ります。
• 他のキーと衝突しても登録はされます。ショートカットウィンドウに赤く表示され、出力ログに記録されます。
• 同じキーの場合、モード専用キーがどこでも有効なキーより優先されます。エディターの固定キー・既定のキー (Ctrl+Z ・ F1〜F7 など) が優先されます。

関連ドキュメント

• ホスト API
• パネル UI (NpUi)
• ワールドロジック type の追加
• 読み込みとライフサイクル
• テストとデバッグ
• ショートカット