ホスト API

Register(INpEditorHost host) で受け取る host が、すべての機能の起点です。このドキュメントでは情報・通知・ワールド・イベント・設定・3D 描画を扱います。Add… の登録ポイントは登録ポイント、Scene ・ View はシーンの読み取りとプレイカメラにあります。

すべての型は NP.Editor.Sdk 名前空間にあります。

INpEditorHost

メンバー	型	SDK	説明
`SdkVersion`	`string`	1.0	エディターの SDK バージョン (例 `"1.3.0"`)
`EditorVersion`	`string`	1.0	エディターのバージョン (例 `"0.9.11"`)
`PluginId`	`string`	1.0	自分の `plugin.json` の `id`
`PluginDir`	`string`	1.0	自分の `plugin.json` があるフォルダー (フルパス)
`World`	`INpWorld`	1.0	現在のワールド。新しいワールドを開いても、常に現在のワールドを指します。
`WorldChanged`	`event Action<NpWorldChange>?`	1.0	ワールドが切り替わったとき
`Committed`	`event Action<NpCommit>?`	1.0	元に戻すの 1 ステップが完了するたび
`Message(string text)`	`void`	1.0	短い通知 (ステータスバー・ビューポート通知・出力ログ)
`Log(string text)`	`void`	1.0	出力ログ 1 行 `[<id>] <text>`
`Settings`	`INpSettings`	1.1	このプラグインの設定ストア
`Draw`	`INpDraw`	1.1	ビューポートへの 3D オーバーレイ描画
`Scene`	`INpScene`	1.3	シーンアクターの読み取り — シーンの読み取りとプレイカメラ
`View`	`INpView`	1.3	プレイ状態・カメラ — シーンの読み取りとプレイカメラ
`Add…`	`void`	1.0〜1.2	登録ポイント — 登録ポイント

ワールド: INpWorld

メンバー	型	説明
`FilePath`	`string?`	現在のファイルパス。保存していない新規ワールドなら `null`
`Selection`	`NpBox?`	現在の選択ボックス。なければ `null`
`Bounds`	`NpBox?`	ブロックがある範囲。空のワールドなら `null`。ワールド全体をスキャンするため、頻繁に呼び出さないでください。
`GetBlock(int x, int y, int z)`	`string`	ブロックステートの文字列。空気は `"minecraft:air"`
`IsAir(int x, int y, int z)`	`bool`	空気かどうか
`Blocks(NpBox? box = null)`	`IEnumerable<NpBlock>`	空気以外のすべてのマス。`box` を渡すとその中だけ。ボックス外のチャンクはスキップします。
`CountBlocks()`	`long`	空気以外のブロック数
`Edit(string label, Action<INpEdit> build)`	`int`	ブロックの変更。1 回 = 元に戻す 1 ステップ。戻り値 = 実際に変更されたマスの数

INpEdit (Edit 内でのみ)

メンバー	説明
`Set(int x, int y, int z, string state)`	そのマスをブロックステートの文字列に変更します。空文字列・`"air"` ・ `"minecraft:air"` は空気です。
`Clear(int x, int y, int z)`	そのマスを空気にします。

int n = host.World.Edit("돌 바닥", e =>
{
    for (int x = 0; x < 8; x++)
        for (int z = 0; z < 8; z++)
            e.Set(x, 0, z, "minecraft:stone");
});
host.Message($"{n}칸 바꿈 (Ctrl+Z 로 되돌리기)");

label は元に戻すの履歴に表示される名前です。
ロックされたマスはスキップします。ロックされたマス = 共同建築のロック・ロックされたアクター・セルガード (AddCellGuard) がブロックしたマスです。そのため、戻り値が書き込んだマスの数より小さくなることがあります。
他の大きな編集処理 (塗りつぶし・地形など) が実行中の場合は InvalidOperationException が発生します。処理しないとプラグインは隔離されます。
ブロックステートの文字列は検査せず、書いたとおりに入れます。Minecraft 形式 (名前空間:id[プロパティ=値,…]) で正確に書いてください。名前空間 (minecraft:) を省略しないでください。カスタムブロックは np:<id> です。
Blocks() を反復しながら Edit しないでください。先に .ToList() で受け取ってから変更します。

データ型

型	宣言	説明
`NpCell`	`readonly record struct NpCell(int X, int Y, int Z)`	マス 1 つ (ブロック座標)
`NpBlock`	`readonly record struct NpBlock(int X, int Y, int Z, string State)`	マス + ブロックステートの文字列
`NpBox`	`readonly record struct NpBox(NpCell Min, NpCell Max)`	ボックス (両端を含む)。`SizeX` ・ `SizeY` ・ `SizeZ` ・ `Contains(x, y, z)`
`NpVec3`	`readonly record struct NpVec3(float X, float Y, float Z)`	3D の点 (ブロック 1 マス = 1)。`NpVec3.Center(NpCell)` = マスの中心
`NpWorldChange`	`sealed record NpWorldChange(NpWorldChangeReason Reason, string? Path)`	ワールドが切り替わった理由とファイルパス
`NpWorldChangeReason`	`enum { New, Open, Replaced, ShotScenario }`	新規作成・開く・ワールドの置き換え・画面検証の開始
`NpCommit`	`sealed record NpCommit(string Label, IReadOnlyList<NpBlockChange> Changes)`	元に戻すの 1 ステップ
`NpBlockChange`	`readonly record struct NpBlockChange(int X, int Y, int Z, string Old, string New)`	マス 1 つの変更前・変更後のステート

イベント

イベント	タイミング	渡される値	やること
`WorldChanged`	新規作成・開く・ワールドの置き換え・画面検証の開始	`NpWorldChange`	自分の状態 (プレビュー・選択・描画・検査結果) をクリアします。
`Committed`	元に戻すの 1 ステップが完了するたび (ユーザーの編集を含む)	`NpCommit`	記録・統計のみ。軽い処理にします。

host.WorldChanged += c =>
{
    _towers.Clear();
    host.Draw.Clear();
};
host.Committed += c => _edits += c.Changes.Count;   // 軽く

Committed の Changes は、読み取るときにブロック名を生成します。マスが多い場合は Count だけを見て、1 つずつ読まないでください。
ハンドラーで例外が発生すると、そのプラグインは隔離されます。
ホストイベントはプラグインのアンロード時に自動で解除されます。-= は何もしません。処理を止めたい場合は、ハンドラー内でフラグを使って除外します。

通知とログ

メンバー	表示される場所	使う場面
`Message(text)`	ステータスバー・ビューポート通知・出力ログ	ユーザーに結果を知らせるとき
`Log(text)`	出力ログ (`[<id>] …`)	デバッグ記録・詳細な結果

設定: INpSettings (SDK 1.1)

プラグインごとにキー・値 (文字列) のストアが 1 つあります。Set するたびにすぐファイルに書き込みます。エディターを再起動しても、プラグインを再読み込みしても残ります。

メンバー	型	説明
`Keys`	`IReadOnlyCollection<string>`	保存されたキーの一覧
`Get(string key)`	`string?`	値。なければ `null`
`Get(string key, string fallback)`	`string`	値。なければ `fallback`
`GetInt(string key, int fallback = 0)`	`int`	整数として読み取り。読み取れなければ `fallback`
`GetDouble(string key, double fallback = 0)`	`double`	実数として読み取り
`GetBool(string key, bool fallback = false)`	`bool`	`"true"` / `"false"` として読み取り
`Set(string key, string? value)`	`void`	保存。`null` なら削除します。空のキーは例外です。
`SetInt` ・ `SetDouble` ・ `SetBool`	`void`	型ごとの保存
`Changed`	`event Action<string>?`	値が変更または削除されたとき (キー名)

_height = host.Settings.GetInt("height", 12);
// パネルの数値欄が変わったらすぐ保存
.Number("높이", _height, 4, 64, 1, v => { _height = (int)v; host.Settings.SetInt("height", _height); })

項目	値
ファイル	`%APPDATA%\NPEditor\plugin_settings\<id>.json`
形式	`{"format":"np-plugin-settings","version":1,"values":{…}}`
同じ値	もう一度 `Set` しても書き込みません。
壊れたファイル	空の設定で開始し、古いファイルは `<id>.json.bad` として残します。
大きなデータ	入れないでください。`Set` のたびにファイル全体を書き直します。数 MB のデータは `PluginDir` の下に独自のファイルとして置きます。

3D 描画: INpDraw (SDK 1.1)

ビューポート上に線・ボックス・文字を重ねて描きます。ブロック・選択・クリックには影響しません。座標はワールド座標 (ブロック 1 マス = 1) です。色は "#rrggbb" です。

メンバー	説明
`Count`	現在描画している数
`Line(NpVec3 a, NpVec3 b, string color = "#ffcc33")`	線
`Box(NpVec3 min, NpVec3 max, string color = "#ffcc33", bool filled = false, float alpha = 0.25f)`	ボックスの辺の線。`filled` なら半透明の面も描きます。
`Cell(NpCell c, string color = "#ffcc33", bool filled = false)`	ブロック 1 マスのボックス (少し大きめ)
`Text(NpVec3 at, string text, string color = "#ffffff", float size = 1f)`	常にカメラの方を向く文字。`size` = ブロックの高さを基準とした倍率
`Clear()`	すべて消去

void Redraw()
{
    host.Draw.Clear();                                   // 描き直すときは消去してからすべて描く
    if (host.World.Selection is not { } b) return;
    host.Draw.Box(new NpVec3(b.Min.X, b.Min.Y, b.Min.Z),
                  new NpVec3(b.Max.X + 1, b.Max.Y + 1, b.Max.Z + 1), "#ffcc33", filled: true, alpha: 0.1f);
    host.Draw.Text(new NpVec3(b.Min.X, b.Max.Y + 2, b.Min.Z), $"{b.SizeX}×{b.SizeY}×{b.SizeZ}");
}

制限	値
最大数	プラグインごとに 20,000 個。超えた分は無視します。
文字の長さ	200 文字まで
`size`	0.1 〜 20
`alpha`	0 〜 1
`Box` の `min` ・ `max`	順序が逆でも合わせて描きます。
プラグインを無効にしたとき	自動で消去されます。