BuzzBuild-NpcDialog — 문제 해결
오류는 서버 설정·진행도, 클라이언트 모드, 연결 기능을 나누어 확인합니다. 명령어와 설정을 함께 참고합니다.
증상별 확인
섹션 제목: “증상별 확인”| 문제 | 확인 방법 | 해결 방법 |
|---|---|---|
| 플러그인 활성화 실패 | 서버 로그의 서비스 없음, Invalid progress.yml 확인 | Framework 활성화 확인. 손상 진행도는 보존·백업하고 운영자에게 복구 요청 |
| 대화 ID가 list에 없음 | “대화 로드 실패”, “Duplicate dialog id”, “Unknown page”, “Invalid condition” 확인 | YAML 문법, ID 중복, start-page/goto, 조건 형식 수정 후 컴포넌트 설정 갱신 |
| “dialogs/ 에 YAML이 없습니다” | 서버의 해당 plugins 데이터 폴더에 .yml 존재 여부 확인 | 올바른 dialogs 폴더에 실제 대화 파일 작성 |
| /대화에서 아무 일도 없음 | bbnpcdialog open으로 실패 안내, 대상의 기존 세션·생존·once 완료·페이지 조건 확인 | 원인 제거 후 다시 열기. /대화는 실패 결과를 별도로 출력하지 않음 |
| open은 성공인데 창이 없음 | 클라이언트의 NpcDialog·Framework·Fabric API와 서버 버전, 클라이언트 초기화 로그 확인 | 지원 버전의 모드와 토큰 프로토콜을 양쪽에 맞추고 클라이언트 재실행 |
| 선택을 눌러도 진행하지 않음 | prevent-skip, 대사 내부 페이지, 구형 클라이언트, 서버와 페이지 토큰 일치 확인 | 타이핑·내부 페이지 완료 후 선택. 서버/클라이언트 배포본 일치 |
| 선택지가 사라짐 | 권한·completed·service 조건, 담당 콜백 등록 여부 확인 | 조건 또는 서비스 등록 수정. 종료 선택지는 조건 없이 유지 |
| 모든 선택지가 숨겨지고 다음으로 못 감 | 원본 페이지에 answers가 있는지 확인 | 무조건 표시되는 종료 선택지 추가. 서버는 advance 우회를 허용하지 않음 |
| 대화가 갑자기 닫힘 | range 이탈, 월드 변경, 텔레포트, 사망, NPC 소멸, 페이지 조건 상실, 설정 갱신 확인 | 해당 조건과 대화 의도를 점검. 정상 서버 취소를 UI 오류로 단정하지 않음 |
| NPC 우클릭이 동작하지 않음 | NPC 플러그인 활성화, 실제 Citizens ID/Mythic 내부 ID, 바인딩, use 권한, 기존 대화 확인 | ID와 연결을 수정하고 설정 갱신. 같은 ID의 config 바인딩 우선 |
| “연결 기능을 실행하지 못했습니다” | 서비스 등록·false 반환·명령 존재·플레이어 권한 확인 | 담당 서비스 계약이나 명령 수정. 미등록 서비스는 실행 거절 |
| once 대화를 다시 못 엶 | 완료 기록과 quest-mode 확인 | 관리자 reset으로 테스트 기록 초기화. 지급된 보상은 회수되지 않음 |
| Esc로 닫히지 않음 | allow-escape-close 기본 false, prevent-exit 확인 | 의도에 맞게 설정. Shift 역시 prevent-exit이면 차단 |
| F 안내와 실제 키가 다름 | confirm-key 키 매핑과 Minecraft 키 설정 확인 | 키 설정과 안내 문구를 함께 맞춤 |
| 한글 깨짐·배치 오류 | 올바른 Fabric JAR, 내장 font/textures, 해상도와 GUI 배율 확인 | 맞는 배포본 사용. 재현 해상도·배율·가상 대사로 담당자에게 보고 |
| “진행도 저장 실패” | 데이터 폴더 쓰기 권한·디스크 공간·progress.yml.tmp 확인 | 쓰기 환경 복구 및 기존 파일 보존. 실행 중 수동 진행도 편집은 피함 |
명령 액션에서 @console이 없으면 플레이어 권한으로 실행됩니다. 콘솔 명령 성공 반환이나 지연 예약 성공은 실제 거래 성공과 다릅니다.
지원하지 않거나 일부만 연결된 항목
섹션 제목: “지원하지 않거나 일부만 연결된 항목”| 항목 | 현재 구현 |
|---|---|
| 바닐라 클라이언트 대화 UI | 대체 UI 없음. Fabric 클라이언트 필요 |
| NPC 생성·좌표 배치 | 기능 없음. 기존 NPC를 연결 |
| 교환 목록·상점 가격·던전 보상 | 기능 없음. 담당 기능에서 결정·검증 |
| 별도 DB 설정·MariaDB 진행도 저장 | 없음. progress.yml 사용 |
| character-image | 현재 설정을 읽지 않음 |
| background-fog | 현재 설정을 읽지 않음. 기본 대화 화면 효과와 구분 |
| npc-focus | 현재 설정을 읽지 않음 |
| 페이지 timer | 현재 설정을 읽지 않음. 시간 자동 진행 없음 |
| 선택지 sound | 로더는 읽지만 선택별 재생 미연결 |
| 사운드 source | DTO에 보존하지만 현재 재생에서 미사용 |
| typing-speed 0으로 즉시 표시 | 서버 모델이 최소 1로 보정 |
| 지연 service 액션 | 거절 |
| 다중 액션 거래 자동 롤백 | 없음 |
| 별도 NPC 생성/관리 명령·명령 별칭 | 없음 |
확인 필요 항목
섹션 제목: “확인 필요 항목”- Citizens/MythicMobs 실제 이벤트와 설치 버전의 호환성.
- 직접 클릭 위치, 키 재설정, 사운드, 모든 해상도·GUI 배율.
- 다른 플러그인과 동시에 적용하는 상태 효과의 복구.
- 교환·상점·던전 콜백의 거래·입장·취소·중복 처리.
- 운영 서버의 실제 배포본, 외부 플러그인 버전과 로드 순서.
서버 토큰 검증은 동일 요청 재실행을 차단하지만 다른 담당 기능의 거래 트랜잭션을 대신하지 않습니다. 조건 콜백에 DB/네트워크 대기를 넣지 않습니다.
확인 범위
섹션 제목: “확인 범위”2026-10-05 소스의 실패 경로·로그·기본 리소스를 확인했습니다. 이전 빌드와 서버 단위 테스트 23개는 성공했고 실제 로컬 UI 일부만 확인했습니다. 위 확인 필요 항목의 게임 내 동작은 미검증입니다. 이 문서 작업에서 서버 시작·중지·재시작·전체 reload는 실행하지 않았습니다.