BuzzBuild-NpcDialog — 설정

서버의 plugins/BuzzBuild-NpcDialog/config.yml과 dialogs/*.yml을 수정합니다. UTF-8 YAML을 사용하며 들여쓰기는 공백으로 작성합니다. 적용은 설치 문서를 따릅니다.

공통 config.yml

다음은 배포 기본 리소스의 값입니다.

키	타입	기본값	설명
`confirm-key`	문자열	`key.swapOffhand`	Minecraft 키 매핑 이름. 실제 지정된 키를 확인 입력에 사용
`allow-escape-close`	불리언	`false`	Esc 종료 허용. prevent-exit가 true이면 종료 불가
`hint-typing`	문자열	`( 클릭 / F 로 스킵 )`	페이지에 별도 값이 없을 때 타이핑 안내
`hint-steady`	문자열	`( 마우스 휠로 선택 후 F키로 확인 )`	페이지에 별도 값이 없을 때 완료 안내
`bindings.citizens`	ID→대화 ID 맵	`{}`	Citizens NPC ID 연결
`bindings.mythicmobs`	내부 ID→대화 ID 맵	`{}`	MythicMobs 내부 몹 ID 연결

confirm-key: "key.swapOffhand"
allow-escape-close: false
hint-typing: "( 클릭 / F 로 스킵 )"
hint-steady: "( 마우스 휠로 선택 후 F키로 확인 )"
bindings:
  citizens: {}
  mythicmobs: {}

안내 문구는 자동 키 이름 변환을 하지 않습니다. 키를 변경하면 문구도 수정합니다. config 바인딩은 같은 ID의 대화 YAML 바인딩을 덮어씁니다. 알려지지 않은 대화 ID는 연결하지 않고 로그에 경고합니다.

대화 ID와 파일

파일명 guide_intro.yml의 기본 ID는 guide_intro입니다. 최상위 id 문자열로 재정의할 수 있습니다. ID 조회는 대소문자를 구분하지 않고 중복 ID는 로드 실패로 처리합니다.

아래 표의 “기본값”은 키가 없을 때의 코드 기본값입니다. 자동 생성 샘플은 range: 8, effect: slowness, effect-lv: 100, start-page: '1a' 등을 명시하므로 표와 다를 수 있습니다.

Settings

키	타입	생략 시 기본값	설명
`Settings.start-page`	문자열	첫 작성 페이지	시작 페이지. 명시한 페이지는 존재해야 함
`Settings.typing-speed`	정수	`1`	글자당 틱. 모델에서 최소 1로 보정
`Settings.range`	실수	`5.0`	거리 유지 범위. 양수·유한값 필수
`Settings.effect`	문자열	`none`	상태 효과. slow/slowness 또는 Minecraft 효과 키
`Settings.effect-lv`	정수	`1`	효과 레벨. 내부 증폭값은 max(0, 레벨−1)
`Settings.prevent-exit`	불리언	`false`	자발적 종료 요청 차단
`Settings.prevent-skip`	불리언	`false`	타이핑 건너뛰기 및 서버의 조기 진행 차단
`Settings.character-name`	불리언	`true`	이름표 표시
`Settings.quest-mode`	문자열	`repeat`	once이면 정상 종료 시 완료 기록, 나머지는 반복 동작

typing-speed: 0으로 즉시 표시를 설정할 수 없습니다. 서버 모델에서 1로 보정합니다. effect가 잘못된 이름이면 적용하지 않습니다. 대화 효과는 최대 30분 지속값으로 적용하며 종료 시 이 모듈이 적용한 효과인지 확인하고 이전 효과 복구를 시도합니다.

Character

키	타입	기본값	설명
`Character.npc-type`	문자열	`none`	citizen/citizens, mythicmobs/mythic 바인딩 지원
`Character.id`	문자열 또는 문자열화 가능한 값	빈 문자열	기존 Citizens ID 또는 Mythic 내부 ID
`Character.name`	문자열	대화 ID	화면 이름표의 표시 이름

NPC 위치를 정하는 키는 없습니다. NPC 생성·배치는 해당 NPC 시스템에서 수행합니다.

Pages와 answers

Pages는 페이지 ID→페이지 맵이며 최소 한 페이지가 필요합니다.

키	타입	생략 시 기본값	설명
`Pages.<page>.lines`	문자열 목록	`[]`	본문 대사
`typing-info-line`	문자열	config hint-typing	해당 페이지 타이핑 안내
`steady-info-line`	문자열	config hint-steady	해당 페이지 완료 안내
`goto`	문자열	빈 문자열	확인/선택 후 다음 페이지
`conditions`	문자열 또는 문자열 목록	`[]`	현재 페이지 이용 조건
`branches`	조건·goto 맵 목록	`[]`	진입 시 최초로 만족하는 자동 분기
`pre-actions`	문자열 또는 문자열 목록	`[]`	페이지 진입 액션. 조건 갱신만 할 때 재실행하지 않음
`post-actions`	문자열 또는 문자열 목록	`[]`	정상 진행·선택의 액션 성공 후 실행
`exit-actions`	문자열 또는 문자열 목록	`[]`	자발적 종료 요청 시 실행. 강제 취소에서는 실행하지 않음
`answers`	선택지 ID→맵	빈 맵	작성 순서의 선택지

페이지 안내·goto·조건·액션 키는 Pages.<page> 아래에 작성합니다. 선택지는 Pages.<page>.answers.<answer> 아래에 작성합니다.

선택지 키	타입	기본값	설명
`text`	문자열	빈 문자열	선택지 표시 문구
`goto`	문자열	빈 문자열	페이지 goto보다 우선
`conditions`	문자열 또는 문자열 목록	`[]`	표시 및 선택 직전 조건
`actions`	문자열 또는 문자열 목록	`[]`	선택 액션
`reply`	문자열 목록	`[]`	액션 성공 후 채팅 메시지. 본문 대사가 아님
`sound`	사운드 맵	없음	로더는 읽지만 현재 선택지별 재생은 연결되지 않음

액션은 빈 목록 []을 권장하며 기존 빈 맵 {}도 빈 액션으로 처리합니다.

Sounds

Sounds.typing과 Sounds.selection은 다음 구조를 공유합니다.

키	타입	맵에 키가 없을 때	설명
`id`	문자열	빈 문자열	사운드 식별자. 비어 있으면 재생하지 않음
`source`	문자열	`MASTER`	로더는 보존하지만 현재 재생 코드에서 사용하지 않음
`volume`	실수	`1.0`	음량
`pitch`	실수	`1.0`	피치

맵 자체를 생략하면 무음 DTO(id 빈 문자열, source MASTER, volume 0, pitch 1)를 사용합니다. 샘플은 typing에 note_block.hat/0.25/1.4, selection에 ui.button.click/0.4/1.1을 명시합니다.

조건과 분기

지원 표현은 permission:<권한>, completed:<대화ID>, service:<namespace>:<key>이며 !로 부정할 수 있습니다. 목록은 AND입니다. 없는 서비스나 예외는 부정 조건이어도 거절합니다. completed는 once 완료 기록이며 repeat 대화는 완료 기록을 남기지 않습니다.

branches:
  - conditions: ['completed:guide_intro']
    goto: returning

서비스 키는 소문자 영문·숫자·밑줄·점·하이픈으로 된 namespace:key 형식입니다. 다른 대화의 페이지는 other.yml:page 형태로 이동합니다. 자동 분기 순환 또는 64회 이상 연쇄는 취소합니다. 선택지 goto가 없으면 페이지 goto를 사용하므로 종료 선택지를 둔 페이지에는 페이지 goto를 넣지 않습니다.

액션 문법

형식	동작
`service:shop:open`	등록된 shop:open 콜백 호출
`service:shop:open example_catalog`	서버 YAML의 가상 카탈로그 ID를 콜백 인자로 전달
`명령`	플레이어 권한으로 명령 실행
`명령 @console`	콘솔 권한으로 명령 실행
`명령 @delay.2`	2초 후 명령 실행. 실행 직전 상태 재검사
`%player_name%`, `{player}`, `%player%`	명령 안에서 대상 플레이어 이름으로 치환

지연 service 액션은 지원하지 않습니다. 지연 명령의 예약 성공이나 명령 반환값은 실제 거래·보상 성공을 보장하지 않습니다. 거래는 담당 기능의 단일 콜백에서 서버 재검증·중복 방어·롤백·비동기 DB 처리를 수행합니다. 액션 여러 개의 자동 롤백은 없습니다.

reply는 %player_name% 치환과 #rrggbb 색상 표기를 지원합니다. 본문 lines에 같은 색상 문자열을 적용하는 구현은 없습니다.

최소 대화 예시

가상 안내 대화이며 NPC 배치·거래·보상을 지정하지 않습니다. dialogs/guide_intro.yml에 작성합니다.

Settings:
  start-page: welcome
  effect: none
  quest-mode: repeat
Character:
  npc-type: none
  name: 안내원
Pages:
  welcome:
    lines:
      - '안녕하세요.'
    answers:
      exit:
        text: 대화 종료
        actions: []

진행도와 미지원 설정

progress.yml은 players.<UUID> 아래 완료 대화 ID 목록을 저장하는 자동 관리 파일입니다. 저장은 직렬 비동기·임시 파일 교체 방식입니다. 실행 중 수동 수정 대신 reset 명령을 사용합니다. 이 모듈에 별도 DB 접속 설정은 없습니다.

샘플의 character-image, background-fog, npc-focus, 페이지 timer는 현재 읽지 않으며 해당 기능을 켜지 않습니다. 레거시 nodes 형식은 로더 호환용으로 지원하지만 새 문서는 Pages 형식을 사용합니다.

확인 범위

2026-10-05 기본 리소스·로더·모델·세션·액션·클라이언트 코드를 대조했습니다. 샘플 대화 표시만 이전 시연에서 확인했으며 모든 설정 조합·사운드·효과 복구의 게임 내 동작은 미검증입니다.