호스트 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	되돌리기 한 단계가 끝날 때마다
`Message(string text)`	`void`	1.0	짧은 알림(상태줄 · 뷰포트 알림 · 출력 로그)
`Log(string text)`	`void`	1.0	출력 로그 한 줄 `[<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단계. 반환 = 실제로 바뀐 칸 수

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 이 납니다. 처리하지 않으면 플러그인이 격리됩니다.
블록 상태 글은 검사하지 않고 쓴 그대로 넣습니다. 마인크래프트 형식(네임스페이스:id[속성=값,…])으로 정확히 씁니다. 네임스페이스(minecraft:)를 빼지 않습니다. 커스텀 블록은 np:<id> 입니다.
Blocks() 를 돌면서 Edit 하지 않습니다. 먼저 .ToList() 로 받은 뒤 바꿉니다.

자료형

형식	선언	설명
`NpCell`	`readonly record struct NpCell(int X, int Y, int Z)`	칸 하나(블록 좌표)
`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). `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)`	되돌리기 한 단계
`NpBlockChange`	`readonly record struct NpBlockChange(int X, int Y, int Z, string Old, string New)`	칸 하나의 이전 · 이후 상태

이벤트

이벤트	언제	넘겨주는 값	할 일
`WorldChanged`	새로 만들기 · 열기 · 월드 교체 · 화면 검증 시작	`NpWorldChange`	내 상태(미리보기 · 선택 · 그림 · 검사 결과)를 비웁니다.
`Committed`	되돌리기 한 단계가 끝날 때마다(사용자 편집 포함)	`NpCommit`	기록 · 통계만. 가볍게 합니다.

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

Committed 의 Changes 는 읽을 때 블록 이름을 만듭니다. 칸이 많으면 Count 만 보고 하나씩 읽지 않습니다.
처리기에서 예외가 나면 그 플러그인이 격리됩니다.
호스트 이벤트는 플러그인을 내릴 때 자동으로 풀립니다. -= 는 아무 일도 하지 않습니다. 처리를 멈추려면 처리기 안에서 플래그로 거릅니다.

알림과 로그

멤버	보이는 곳	쓰는 때
`Message(text)`	상태줄 · 뷰포트 알림 · 출력 로그	사용자에게 결과를 알릴 때
`Log(text)`	출력 로그(`[<id>] …`)	디버그 기록 · 자세한 결과

설정: INpSettings (SDK 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)입니다. 색은 "#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)`	블록 한 칸 상자(살짝 크게)
`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`	순서가 바뀌어도 맞춰 그립니다.
플러그인을 끌 때	자동으로 지워집니다.