scene.json 형식

scene.json 은 씬 액터 · 애니메이션 클립 · 월드 로직 규칙을 담은 JSON 파일입니다. 에디터가 .npbuild 를 만들 때 넣고(내보내기 창 「씬 포함」), 서버 플러그인 NP Scene 이 읽어 실행합니다. 형식 이름은 np-scene, 판은 1 입니다.

단계	하는 일
1. 에디터	액터 · 클립 · 규칙을 월드 파일(`.npworld`)에 저장합니다. 좌표는 에디터 월드 좌표입니다.
2. 내보내기	`.npbuild` 조각마다 `scene.json` 을 씁니다. 좌표는 그 조각의 최소 모서리(origin) 기준으로 바꿉니다.
3. 서버 설치	`.npbuild` 를 설치할 때 회전 · 반전 · 위치를 적용해 서버 좌표로 바꿉니다.
4. 서버 실행	NP Scene 이 액터를 만들고 규칙을 실행합니다.

최상위

{
  "format": "np-scene",
  "version": 1,
  "origin": [120, 64, -40],
  "actors": [ … ],
  "animations": [ … ],
  "logic": [ … ],
  "variables": [ … ],
  "enums": [ … ],
  "types": [ … ]
}

키	형	늘 있음	뜻
`format`	글	예	늘 `"np-scene"`
`version`	수	예	늘 `1`
`origin`	`[x,y,z]`	예	이 조각 최소 모서리의 에디터 좌표입니다. 정보용입니다.
`actors`	배열	예	씬 액터
`animations`	배열	예	애니메이션 클립(시퀀서)
`logic`	배열	예	월드 로직 규칙
`variables`	배열	선언이 있을 때	변수 선언
`enums`	배열	있을 때	enum
`types`	배열	있을 때	데이터타입

액터 · 클립 · 규칙이 하나도 없으면 .npbuild 에 scene.json 을 넣지 않습니다.

좌표

모든 자리(pos, 경로 점, 위치 키, 고른 블록 칸)는 origin 기준입니다. 에디터 좌표에서 origin 을 뺀 값입니다.
한 조각에 들어가는 액터는 pos 의 X · Z 가 그 조각 범위 안인 것입니다. 높이는 보지 않습니다.
어느 조각에도 들지 않은 액터는 내보내기 경고가 납니다.
rot 은 [yaw, pitch, roll] 도입니다. 마인크래프트 방식입니다: yaw 0 = 남(+Z), 90 = 서(−X), pitch + = 아래.

액터

{"id": "trig_gate", "kind": "trigger", "name": "성문 앞",
 "pos": [10, 64, 5], "rot": [0, 0, 0], "size": [6, 4, 3], "shape": "box",
 "tags": ["gate"], "props": {}}

키	형	뜻
`id`	글	월드 안에서 유일한 이름. 영문 · 숫자 · `_` `.` `-`, 1~64자
`kind`	글	아래 표
`name`	글	보이는 이름
`pos`	`[x,y,z]`	자리(종류마다 뜻이 다름 — 아래 표)
`rot`	`[yaw,pitch,roll]`	방향. `trigger` 는 늘 `[0,0,0]`
`scale`	`[x,y,z]`	배율. `display` · `text` 만
`size`	`[x,y,z]`	전체 크기(블록). `trigger` · `blocker` 만
`shape`	글	`box` · `sphere`(`size` = 지름). `trigger` 만 `sphere` 가능
`tags`	글 배열	태그. 비면 `[]`
`parent`	글	붙인 부모 액터 `id`(있을 때만)
`props`	객체	종류별 속성

에디터에서 「에디터 전용」으로 둔 액터는 나가지 않습니다.

kind

`kind`	`pos` 뜻	주요 `props`
`trigger`	구역 가운데	(없음) · 상호작용 컴포넌트에서 나온 것이면 `interactable: true`
`spawn`	발	`role`(`player` · `npc` · `mob` · `custom`) · `entity`(npc · mob 일 때)
`display`	모델 가운데	`display`(`item` · `block`) · `item_model` 또는 `block` · `visible` · `glow` · `glow_color` · `billboard`(`fixed` · `vertical` · `horizontal` · `center`) · `brightness`(-1 = 주변 빛, 0~15)
`text`	글 가운데	`text` · `color` · `background`(`#aarrggbb`) · `billboard` · `visible` · `shadow` · `see_through` · `alignment`(`center` · `left` · `right`) · `line_width`
`light`	그 칸(`floor(pos)`)	`level`(0~15) · `visible`
`camera`	눈	`fov`
`path`	첫 점	`points`(`[[x,y,z], …]`) · `closed`
`sound`	소리 자리	`event` · `radius` · `mode`(`random` · `loop`) · `interval_min` · `interval_max` · `volume` · `pitch_min` · `pitch_max` · `time`(`any` · `day` · `night`) · `underground_only`
`blocker`	상자 가운데	`mode`(`barrier` · `push`) · `affects`(`players` · `all`) · `visible_in_editor`

서버는 모르는 props 칸을 무시합니다.
visible: false 인 display · text · light 는 숨긴 채 시작합니다. 규칙 동작 actor_show 로 나타납니다.
blocker 의 barrier 는 상자 안 빈칸을 barrier 블록으로 채웁니다. push 는 블록 없이 안에 들어온 것을 밀어냅니다.

컴포넌트에서 나온 액터

액터 컴포넌트(트리거 볼륨 · 막는 볼륨 · 상호작용 · 소리 발생기 · 빛 · 글 표시)는 보통 씬 액터 한 줄로 나갑니다.

키	값
`id`	`<액터 id>.<컴포넌트 id>` (예: `door.interact`)
`kind`	`trigger` · `blocker` · `sound` · `light` · `text`
`parent`	주인 액터 `id`(정보용 — 블록 액터면 주인은 `actors` 에 없음)
`tags`	주인 액터 태그

서버는 새 kind 를 알 필요가 없습니다.

애니메이션

{"id": "gate_open", "name": "성문 열림", "length": 3.0, "loop": false,
 "tracks": [
   {"actor": "npc_guard", "property": "pos",
    "keys": [{"t": 0, "v": [12.5, 64, 8.5], "ease": "smooth"}, {"t": 3, "v": [14.5, 64, 8.5]}]},
   {"actor": "txt_welcome", "property": "visible", "keys": [{"t": 0, "v": true}]}
 ]}

키	뜻
`id` · `name`	클립 이름
`length`	길이(초)
`loop`	반복 여부
`tracks[].actor`	액터 `id`
`tracks[].property`	`pos` · `rot` · `scale` · `visible` · `text` · `color`
`keys[].t`	시각(초). `t` 오름차순
`keys[].v`	값 — `pos` · `rot` · `scale` = `[x,y,z]`, `visible` = 참거짓, `text` = 글, `color` = `"#aarrggbb"`
`keys[].ease`	`linear`(없으면 이것) · `step` · `smooth`. 그 키에서 다음 키까지에 씁니다.

visible · text 는 늘 계단입니다.
첫 키 전은 첫 값, 마지막 키 뒤는 마지막 값입니다.
반복하지 않는 클립은 끝나면 마지막 자세에 머뭅니다.
여러 클립이 같은 액터 · 속성을 움직이면 나중에 시작한 클립이 이깁니다. actor_show · actor_hide 는 visible 트랙보다 앞섭니다.

시퀀서 칸

클립에 아래 칸을 더할 수 있습니다. 모두 선택입니다. 옛 실행기는 무시하고 tracks 만 돌립니다.

"cuts":   [{"t": 0, "camera": "cam_a"}, {"t": 3, "camera": "cam_b", "blend": 1}, {"t": 5.5, "camera": ""}],
"events": [{"t": 2, "signal": "intro_mid"}],
"sounds": [{"t": 0.2, "event": "minecraft:block.bell.use", "volume": 1, "pitch": 1, "at": "crystal"}],
"titles": [{"t": 0.6, "title": "광장의 수정", "subtitle": "", "duration": 1.8, "fade_in": 0.3, "fade_out": 0.5}],
"fades":  [{"t": 0, "v": 1}, {"t": 0.9, "v": 0, "ease": "smooth"}],
"fade_color": "#000000"

칸	항목(* 필수)	뜻
`cuts`	`t`* · `camera`*(camera 액터, `""` = 플레이어 시점) · `blend`(초, 0)	그 시각부터 그 카메라 시점
`events`	`t`* · `signal`*	그 시각에 신호 — 동작 `signal` 과 같음
`sounds`	`t`* · `event`* · `volume`(1) · `pitch`(1) · `at`(액터)	그 시각에 소리
`titles`	`t`* · `title` · `subtitle` · `duration`(2) · `fade_in`(0.5) · `fade_out`(0.5)	그 시각에 화면 제목
`fades`	`t`* · `v`*(0~1) · `ease`	화면 덮개 불투명도
`fade_color`	`"#rrggbb"`(기본 검정)	덮개 색

규칙

{"id": "r_gate_enter", "name": "성문 진입", "enabled": true,
 "trigger": {"type": "enter", "actor": "trig_gate"},
 "filter": {"once": false, "once_per_player": true, "cooldown": 10, "permission": ""},
 "conditions": [{"type": "time", "value": "day"}],
 "actions": [
   {"type": "sound", "event": "minecraft:block.bell.use", "at": "trig_gate", "audience": "player"},
   {"type": "anim_play", "anim": "gate_open"},
   {"type": "wait", "seconds": 2},
   {"type": "actor_show", "actor": "txt_welcome"}
 ]}

키	뜻
`id` · `name`	규칙 이름
`enabled`	꺼져 있으면 실행하지 않습니다.
`trigger`	트리거 노드 하나
`filter`	`once` · `once_per_player` · `cooldown`(초) · `permission`
`conditions`	조건 노드 배열 — 모두 참일 때만 동작
`actions`	동작 노드 배열 — 순서대로

노드는 type 과 그 type 의 칸으로 된 객체입니다. type 별 칸은 월드 로직 type 목록에 있습니다.

수 칸은 글로 적혀 있어도 읽습니다.
노드 안 _graph 칸은 에디터 전용입니다(로직 그래프 노드 자리 · 중단점). 서버는 무시합니다.
블록 트리거(block_break · block_place · block_interact)의 area 가 blocks 이면 cells 는 [[x,y,z], …] 이고 origin 기준입니다(4,096칸까지). area 가 없으면 zone 입니다.

audience

받는 사람을 고르는 동작(소리 · 화면 제목 · 메시지 · 전투 동작 등)은 audience 를 씁니다.

값	받는 사람
`player`	트리거한 사람(기본)
`inside`	동작의 `actor` 구역 안 모두. 없으면 규칙 트리거 구역 안 모두
`world`	월드의 모두
`radius`	`at` 액터(비면 트리거한 사람)에서 `r`(16) 블록 안

변수 · enum · 데이터타입

"variables": [{"name": "score", "type": "int", "scope": "player", "default": "0"},
              {"name": "hero", "type": "Hero", "scope": "player"}],
"enums":     [{"name": "Job", "values": ["warrior", "mage", "archer"]}],
"types":     [{"name": "Hero", "fields": [{"name": "hp", "type": "int", "default": "20"},
                                          {"name": "job", "type": "Job"}]}]

칸	키	뜻
`variables[]`	`name` · `type` · `scope` · `default`	`type` = `bool` · `int` · `float` · `string` · `player` · `actor` · `position` · enum 이름 · 데이터타입 이름. `scope` = `global` · `player`. `default` 가 없으면 형의 0 값
`enums[]`	`name` · `values`	값 목록. 처음 값 = `default` 또는 첫 값
`types[]`	`name` · `fields[]`(`name` · `type` · `default`)	칸 형 = 기본 형 · enum · 다른 데이터타입

값은 모두 글로 저장합니다. 수는 0.###, 참거짓은 true · false, 자리는 "x y z" 입니다.
데이터타입 변수는 칸마다 펼친 이름(hero.hp, hero.stats.str)으로 저장하면 됩니다.
선언하지 않은 이름은 전역 글 변수입니다. 플래그(flag · set_flag)와 같은 저장소입니다.

0.9.7 부터 variables, 0.9.11 부터 enums · types 가 더해졌습니다.

호환 규칙

np-scene 1 은 덧붙이기만 합니다. 새 기능은 새 칸 · 새 type 으로 더하고, format · version 은 바꾸지 않습니다.

경우	실행기가 할 일
모르는 최상위 칸 · 클립 칸 · `props` 칸	무시합니다.
모르는 트리거 type	그 규칙을 건너뜁니다(경고 한 번).
모르는 조건 type	그 조건을 거짓으로 봅니다(경고 한 번).
모르는 동작 type	그 동작만 건너뛰고 다음 동작을 이어갑니다(경고 한 번).
모르는 노드 칸	무시합니다.

에디터는 모르는 type · 칸을 지우지 않고 그대로 보존합니다. 다른 이벤트 플러그인이 더한 type 도 그 플러그인이 있는 서버에서 실행됩니다.