BuzzBuild-NpcDialog — 사용법

관리자는 대사와 NPC 연결을 설정하고, 기능 담당자는 메뉴 열기·이용 가능 조건을 서버 API에 등록합니다. 설치를 먼저 완료합니다.

게임에서 대화 조작

입력	동작
확인 키(기본 F), Enter, Space	타이핑 스킵 또는 완료 후 확인·다음 진행
타이핑 중 왼쪽 클릭	prevent-skip이 false일 때 전체 표시
선택지 왼쪽 클릭	해당 선택 확정
휠·위/아래 방향키	선택지 변경
Shift	prevent-exit가 false일 때 종료
Esc	allow-escape-close가 true이고 prevent-exit가 false일 때 종료

확인 키는 config의 Minecraft 키 매핑을 따릅니다. 긴 대사는 내부 페이지를 넘긴 뒤 마지막 페이지에서 선택지를 표시합니다. 한 번에 최대 3개를 보여주고 휠·방향키로 나머지를 선택합니다. 선택지가 있을 때 빈 배경 클릭은 확정하지 않습니다.

서버 응답 대기 중 확인·종료 요청을 제한합니다. 응답이 유실되면 클라이언트는 40틱 후 재시도를 허용하지만 서버 토큰은 한 번만 소비하므로 동일 요청으로 액션을 다시 실행하지 않습니다.

대화 작성·시험

dialogs/guide_intro.yml을 작성합니다.
관리자가 /bbnpcdialog reload로 설정을 적용합니다. 활성 대화가 닫힙니다.
/bbnpcdialog list에서 guide_intro가 있는지 확인합니다.
/대화 guide_intro로 표시합니다.
각 선택지의 페이지 이동과 종료를 확인합니다.

Settings:
  start-page: welcome
  effect: none
  quest-mode: repeat
Character:
  npc-type: none
  name: 안내원
Pages:
  welcome:
    lines: ['무엇을 도와드릴까요?']
    answers:
      explain:
        text: 이용 방법 안내
        goto: explanation
      exit:
        text: 대화 종료
        actions: []
  explanation:
    lines: ['휠이나 방향키로 선택하고 확인 키를 누르세요.']
    answers:
      back:
        text: 처음으로 돌아가기
        goto: welcome
      exit:
        text: 대화 종료
        actions: []

위 ID·대사는 예시입니다. 파일 ID와 페이지 ID를 구분하고, 종료 선택지에 goto를 넣지 않습니다.

기존 NPC 연결

NPC ID와 위치는 NPC 담당자가 제공한 값을 사용합니다. Citizens라면 기존 ID를 Character.npc-type: citizen과 Character.id에 지정하거나 config의 bindings.citizens에 매핑합니다. MythicMobs는 mythicmobs 타입과 내부 몹 ID 또는 bindings.mythicmobs를 사용합니다.

필요한 NPC 플러그인이 활성화됐는지 확인합니다.
설정 문서의 바인딩을 작성합니다.
설정을 다시 읽고 일반 이용 권한이 있는 계정으로 NPC를 우클릭합니다.
거리 이탈 및 NPC 소멸 시 취소되는지 테스트 환경에서 확인합니다.

NPC 연결은 실제 엔티티를 거리 기준으로 사용합니다. 관리자 명령/엔티티 없는 API open은 플레이어의 시작 위치가 기준입니다. 범위 안 이동 자체는 취소하지 않으며 range 이탈·월드 변경·텔레포트·사망·접속 종료는 서버에서 취소합니다.

조건과 once 대화

선택지 조건은 표시할 때와 선택 직전에 검사하며 10틱마다 목록 변화를 확인합니다. 조건이 바뀌면 새 토큰으로 갱신하고 현재 페이지 조건이 사라지면 취소합니다. 종료 선택지를 조건 없이 제공합니다.

quest-mode: once는 정상적인 마지막 진행·선택에서 즉시 액션과 post-actions가 성공한 경우 완료 기록을 남깁니다. Shift/Esc 또는 강제 취소는 완료로 기록하지 않습니다. “대화 종료” 선택지로 정상 종료하는 것도 once 완료가 될 수 있으므로 업무상 완료 의미를 먼저 정합니다.

반복 테스트는 /bbnpcdialog reset ExamplePlayer guide_intro를 사용합니다. completed 조건을 사용하려면 참조 대화가 실제로 once 완료 기록을 남겨야 합니다.

교환·상점·던전 서비스 연결

YAML의 service 키만 작성하면 기능이 생기지 않습니다. 각 담당 서버 플러그인이 조건과 액션을 등록해야 합니다.

Pages:
  menu:
    lines: ['이용할 기능을 선택하세요.']
    answers:
      exchange:
        text: 교환 메뉴
        conditions: ['service:exchange:ready']
        actions: ['service:exchange:open']
      shop:
        text: 상점 메뉴
        conditions: ['service:shop:ready']
        actions: ['service:shop:open']
      dungeon:
        text: 던전 메뉴
        conditions: ['service:dungeon:ready']
        actions: ['service:dungeon:open']
      exit:
        text: 대화 종료
        actions: []

페이지 menu를 start-page로 지정한 대화에 넣는 예제입니다. ready가 등록되지 않았거나 false이면 해당 선택지를 숨깁니다. 메뉴를 여는 선택지와 페이지에는 goto를 넣지 않아 대화창을 먼저 닫은 뒤 다음 기능을 엽니다.

담당 플러그인의 API 이용

shared의 buzzbuild-npcdialog-common-0.1.0.jar를 compileOnly로 참조하고 plugin.yml에 depend 또는 softdepend: [BuzzBuild-NpcDialog]를 선언합니다. API를 자기 JAR에 포함하지 않습니다.

NpcDialogApi api =
    getServer().getServicesManager().load(NpcDialogApi.class);

if (api != null) {
    // shopService는 담당 기능이 구현하는 서비스의 예시 변수입니다.
    api.registerCondition("shop:ready",
        playerId -> shopService.canOpenCached(playerId));
    api.registerAction("shop:open",
        (playerId, argument) ->
            shopService.openValidated(playerId, argument));
}

기존 Framework FeatureRegistry의 find("npcdialog", NpcDialogApi.class)로도 서비스를 찾을 수 있습니다. 실제 NPC 이벤트를 직접 처리하는 담당자는 엔티티 UUID를 전달합니다.

api.openDialog(player.getUniqueId(), "guide_intro", npcEntity.getUniqueId());

모든 API 호출과 콜백은 Paper 메인 스레드에서 실행합니다.
조건은 캐시·메모리를 사용하고 DB/네트워크 대기를 하지 않습니다.
실제 거래·입장·보상의 재검증, 자원 차감, 중복 방어, 롤백과 비동기 DB 작업은 담당 기능에서 처리합니다.
콜백은 실패 시 false를 반환합니다. 동일 키 등록은 거절하며 플러그인 종료 시 자기 키만 unregister합니다.
NpcDialog 서비스가 다시 만들어지면 새 서비스에 등록합니다.
closeDialog(UUID)로 서버에서 취소할 수 있으며 prevent-exit도 우회합니다.

원본 프로젝트의 examples/java/.../NpcFeatureBridge.java는 컴파일 검증되는 참고 예제이며 자동 배포되지 않습니다.

기존 명령으로 메뉴 열기

현재 BuzzBuild-DungeonMenu의 플레이어 명령 던전메뉴를 연결하는 예제도 있습니다.

answers:
  open:
    text: 던전 메뉴 열기
    conditions: ['permission:buzzbuild.dungeonmenu.use']
    actions: ['던전메뉴']
  exit:
    text: 대화 종료
    actions: []

DungeonMenu가 설치되어 실제 명령과 권한을 제공해야 합니다. 이는 메뉴만 여는 예제이며 던전 입장·보상을 승인하지 않습니다. 설치한 DungeonMenu 버전의 명령 계약은 담당자에게 확인합니다.

확인 범위

2026-10-05 소스와 컴파일 검증 예제를 확인했습니다. 이전 로컬 시연에서 대화 표시·스크롤 선택 변경을 확인했습니다. 조건·중복·거리·종료는 서버 단위 테스트로 확인한 범위가 있으며 실제 NPC·직접 클릭·거래/입장 연결의 게임 내 동작은 미검증입니다.