Host API

The host you receive in Register(INpEditorHost host) is the starting point for every feature. This page covers info, notifications, the world, events, settings and 3D drawing. The Add… registration points are in Registration points, and Scene · View are in Scene access and play camera.

All types are in the NP.Editor.Sdk namespace.

INpEditorHost

Member	Type	SDK	Description
`SdkVersion`	`string`	1.0	The editor’s SDK version (for example `"1.3.0"`)
`EditorVersion`	`string`	1.0	The editor version (for example `"0.9.11"`)
`PluginId`	`string`	1.0	The `id` from your `plugin.json`
`PluginDir`	`string`	1.0	The folder containing your `plugin.json` (full path)
`World`	`INpWorld`	1.0	The current world. Always points to the current world, even after a new world is opened.
`WorldChanged`	`event Action<NpWorldChange>?`	1.0	When the world changes
`Committed`	`event Action<NpCommit>?`	1.0	Each time an undo step completes
`Message(string text)`	`void`	1.0	A short notification (status bar · viewport notification · Output Log)
`Log(string text)`	`void`	1.0	One Output Log line `[<id>] <text>`
`Settings`	`INpSettings`	1.1	This plugin’s settings store
`Draw`	`INpDraw`	1.1	3D overlay drawing in the viewport
`Scene`	`INpScene`	1.3	Read scene actors — Scene access and play camera
`View`	`INpView`	1.3	Play state · camera — Scene access and play camera
`Add…`	`void`	1.0~1.2	Registration points — Registration points

World: INpWorld

Member	Type	Description
`FilePath`	`string?`	The current file path. `null` for a new, unsaved world
`Selection`	`NpBox?`	The current selection box. `null` if none
`Bounds`	`NpBox?`	The extent containing blocks. `null` for an empty world. Scans the whole world, so do not call it often.
`GetBlock(int x, int y, int z)`	`string`	The block state string. Air is `"minecraft:air"`
`IsAir(int x, int y, int z)`	`bool`	Whether the cell is air
`Blocks(NpBox? box = null)`	`IEnumerable<NpBlock>`	Every non-air cell. If `box` is given, only cells inside it. Chunks outside the box are skipped.
`CountBlocks()`	`long`	The number of non-air blocks
`Edit(string label, Action<INpEdit> build)`	`int`	Changes blocks. One call = one undo step. Returns the number of cells actually changed

INpEdit (inside Edit only)

Member	Description
`Set(int x, int y, int z, string state)`	Sets the cell to the block state string. An empty string, `"air"` or `"minecraft:air"` is air.
`Clear(int x, int y, int z)`	Sets the cell to air.

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 is the name shown in the undo history.
Locked cells are skipped. Locked cells = cells blocked by a Co-building lock, a locked actor or a cell guard (AddCellGuard). So the return value can be smaller than the number of cells you set.
If another large edit (fill, terrain and so on) is running, InvalidOperationException is thrown. If you do not handle it, the plugin is isolated.
Block state strings are not validated; they are written exactly as given. Write them precisely in the Minecraft format (namespace:id[property=value,…]). Do not omit the namespace (minecraft:). Custom blocks are np:<id>.
Do not call Edit while iterating Blocks(). Get the list first with .ToList(), then make changes.

Data types

Type	Declaration	Description
`NpCell`	`readonly record struct NpCell(int X, int Y, int Z)`	One cell (block coordinates)
`NpBlock`	`readonly record struct NpBlock(int X, int Y, int Z, string State)`	Cell + block state string
`NpBox`	`readonly record struct NpBox(NpCell Min, NpCell Max)`	Box (both ends inclusive). `SizeX` · `SizeY` · `SizeZ` · `Contains(x, y, z)`
`NpVec3`	`readonly record struct NpVec3(float X, float Y, float Z)`	3D point (one block = 1). `NpVec3.Center(NpCell)` = center of the cell
`NpWorldChange`	`sealed record NpWorldChange(NpWorldChangeReason Reason, string? Path)`	Why the world changed, and the file path
`NpWorldChangeReason`	`enum { New, Open, Replaced, ShotScenario }`	New · open · world replaced · screen verification started
`NpCommit`	`sealed record NpCommit(string Label, IReadOnlyList<NpBlockChange> Changes)`	One undo step
`NpBlockChange`	`readonly record struct NpBlockChange(int X, int Y, int Z, string Old, string New)`	The before and after state of one cell

Events

Event	When	Value passed	What to do
`WorldChanged`	New · open · world replaced · screen verification started	`NpWorldChange`	Clear your state (previews · selection · drawings · check results).
`Committed`	Each time an undo step completes (including user edits)	`NpCommit`	Logging and statistics only. Keep it light.

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

Changes in Committed builds block names when read. If there are many cells, look only at Count instead of reading each one.
If a handler throws, the plugin is isolated.
Host events are unhooked automatically when the plugin is unloaded. -= does nothing. To stop handling, filter with a flag inside the handler.

Notifications and logs

Member	Where it appears	When to use
`Message(text)`	Status bar · viewport notification · Output Log	To tell the user a result
`Log(text)`	Output Log (`[<id>] …`)	Debug records · detailed results

Settings: INpSettings (SDK 1.1)

Each plugin has one key–value (string) store. Every Set is written to the file immediately. Values persist across editor restarts and plugin reloads.

Member	Type	Description
`Keys`	`IReadOnlyCollection<string>`	List of stored keys
`Get(string key)`	`string?`	The value. `null` if missing
`Get(string key, string fallback)`	`string`	The value. `fallback` if missing
`GetInt(string key, int fallback = 0)`	`int`	Read as an integer. `fallback` if it cannot be read
`GetDouble(string key, double fallback = 0)`	`double`	Read as a floating-point number
`GetBool(string key, bool fallback = false)`	`bool`	Read as `"true"` / `"false"`
`Set(string key, string? value)`	`void`	Store. `null` deletes. An empty key throws.
`SetInt` · `SetDouble` · `SetBool`	`void`	Typed store
`Changed`	`event Action<string>?`	When a value changes or is deleted (key name)

_height = host.Settings.GetInt("height", 12);
// save as soon as the panel number field changes
.Number("높이", _height, 4, 64, 1, v => { _height = (int)v; host.Settings.SetInt("height", _height); })

Item	Value
File	`%APPDATA%\NPEditor\plugin_settings\<id>.json`
Format	`{"format":"np-plugin-settings","version":1,"values":{…}}`
Same value	Setting the same value again does not write.
Corrupt file	Starts with empty settings and keeps the old file as `<id>.json.bad`.
Large data	Do not store it here. Every `Set` rewrites the whole file. Keep data of several MB in your own files under `PluginDir`.

3D drawing: INpDraw (SDK 1.1)

Draws lines, boxes and text over the viewport. It does not affect blocks, selection or clicks. Coordinates are world coordinates (one block = 1). Colors are "#rrggbb".

Member	Description
`Count`	Number of items currently drawn
`Line(NpVec3 a, NpVec3 b, string color = "#ffcc33")`	Line
`Box(NpVec3 min, NpVec3 max, string color = "#ffcc33", bool filled = false, float alpha = 0.25f)`	Box edge lines. If `filled`, translucent faces are drawn too.
`Cell(NpCell c, string color = "#ffcc33", bool filled = false)`	Box around one block cell (slightly larger)
`Text(NpVec3 at, string text, string color = "#ffffff", float size = 1f)`	Text that always faces the camera. `size` = scale relative to block height
`Clear()`	Clears everything

void Redraw()
{
    host.Draw.Clear();                                   // when redrawing, clear and draw everything
    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}");
}

Limit	Value
Maximum count	20,000 per plugin. Anything beyond is ignored.
Text length	Up to 200 characters
`size`	0.1 – 20
`alpha`	0 – 1
`min` · `max` of `Box`	Drawn correctly even if swapped.
When the plugin is disabled	Cleared automatically.