BuzzBuild-Achievement — 문제 해결

화면·시작 문제

문제	확인 방법	해결 방법
플러그인이 비활성화됨	`Framework MariaDB가 필요합니다.` 로그, Framework 데이터 소스·테이블·메시징 서비스	Framework 구성을 정상화하고 운영자의 점검 일정에 다시 로딩
`/업적` 화면 응답 없음	요청 후 80 서버 틱의 경고, 클라이언트 모드 목록·로그	Achievement Fabric과 Framework Fabric, Fabric API 및 버전 확인. 모드 교체 후 게임 완전 재실행
웹 화면 초기화 실패	MCEF 초기화·클라이언트 로그	`mcef-modern` 호환성·구성 요소 다운로드 상태 확인. 소스에는 기본 화면 전환과 180초 초기화 제한이 있음
정보 불러오기 실패	서버 DB 조회 로그	Framework DB 연결·권한·마이그레이션 상태 확인
변경이 바로 보이지 않음	진단의 저장 대기와 화면 갱신 주기	정상 상태에서 다음 저장·갱신을 기다린 뒤 재확인. 반복 실패는 로그로 구분

조건이 올라가지 않을 때

/업적 진단으로 활성 여부, 조건 수와 저장 대기를 확인합니다.
achievements.yml의 실제 metric·condition을 확인합니다. config.yml의 구형 업적 목록이나 설명만 수정한 것은 아닌지 확인합니다.
이벤트 조건이면 /업적 추적 <접속중인 닉네임>으로 활동과 일치 조건 ID를 확인합니다. 직접 지표는 이 추적에 나오지 않을 수 있습니다.
subjects·group·where의 ID와 대소문자를 대조합니다. 화면 이름과 내부 ID는 다를 수 있습니다.
해당 외부 플러그인의 로딩·API 호환성과 활동 성공 여부를 확인합니다.

문제	확인·해결
작물을 수확해도 0	CustomCrops 연결 여부, 실제 point와 `min-point`, ItemManager ID와 `products`, 취소된 이벤트 확인
고품종 집계가 없음	`high-quality` 목록 확인. 일반 수확 목록만 등록해도 고품종이 자동 분류되지는 않음
소지품 조건 불충족	보관 인벤토리 36칸에 대상 전체가 동시에 있는지 확인. 상자나 과거 소지 기록은 합산하지 않음
보스 클리어가 없음	개인 처치인지 던전 완료인지 구분. `boss.clear`는 `dungeon-bosses` 매핑 및 인스턴스 UUID 필요
파티원 일부만 인정	`mythic.kill`은 Player killer만 인정. 던전 완료는 플레이어별 완료 이벤트 확인
가공 생산량·대성공만 누락	`getOutputCounts`, `getGreatResults`가 있는 Process 버전인지 확인
최초 업적이 완료되지 않음	`first-only`의 기존 최초 기록자 확인. 동일 DB에서 다른 이용자가 먼저 기록하면 완료되지 않음
준비 중 업적	`enabled: false`와 `pending-reason` 확인. 정책·대상·생산 이벤트가 갖춰지기 전에는 켜지 않음
재시작 직전 활동 누락	활동·지표는 메모리 대기 후 DB에 기록. 비정상 종료 전 미저장 활동까지 복구를 보장하지 않음

CustomCrops·Mythic 연동 등은 생존·모험 모드로 테스트합니다. 모든 지표에 동일한 게임모드 제한이 있는 것은 아닙니다.

리로드 오류

증상	확인·해결
`achievements.yml 구문 오류` / `integrations.yml 구문 오류`	YAML 들여쓰기·목록·따옴표 수정 후 `/업적 리로드`
`metric/target 오류`	지표 형식과 1 이상 목표 확인
대상 목록이 비어 있음	`EACH`, `INVENTORY`, `SESSION_EACH`의 `subjects` 또는 그룹 채우기
`reset-event가 필요합니다`	`STREAK`, `SEQUENCE`, `SESSION_BELOW`에 실제 발생하는 종료·실패 이벤트 지정
지원하지 않는 보상 필드	`rewards`는 `mode`, `titles`만 사용
색상 무시 경고	허용 키와 따옴표로 감싼 6자리 HEX 확인
첫 등급 점수 경고	가장 낮은 등급의 `points`를 0으로 수정

리로드 실패 메시지의 “기존 조건 유지”는 모든 설정의 원자적 복원을 뜻하지 않습니다. 현재 로더는 색상·점수·등급을 조건 검증보다 먼저 바꿉니다. 오류를 수정한 뒤 성공 메시지와 화면을 함께 확인하세요.

칭호 지급 오류

먼저 /업적 보상 상태를 확인합니다. 미지급 수에는 설정에서 제거되어 중지된 건도 포함됩니다.

상태·오류	의미	조치
등록된 지급 내역 없음	설정·완료 기록에 따라 아직 대상이 없을 수 있음	실제 `achievements.yml`의 보상과 완료 여부 확인
`UNKNOWN_TITLE`	Title 카탈로그에 ID 없음	칭호 등록 또는 ID 수정 후 리로드
`SERVICE_UNAVAILABLE`	칭호 보상 서비스 없음	Title 활성화와 `TitleRewardApi` 제공 여부 확인
`API_MISMATCH`	호출 메서드·응답 계약 불일치	Achievement와 호환되는 Title 배포본 확인
`DELIVERY_FAILED`	저장·호출 실패 또는 대기 시간 초과	DB·Title 로그 확인. 원인 복구 후 자동 재시도 관찰
`보상 DB 조회 실패`	상태 조회 자체 실패	Framework DB 연결과 테이블 상태 확인

실패 건은 DB에 남기고 5초부터 최대 300초 간격으로 재시도합니다. 한 번 조회하는 대기 건은 최대 50개이며 즉시 모든 지급이 끝나는 것은 아닙니다. 시작·설정 적용·보상 동기화 시 기존 완료자를 대조합니다. 지급 기록을 임의 삭제하는 것은 복구 절차가 아닙니다.

미지원 및 추가 확인 사항

자동 아이템·화폐·임의 명령어 보상은 지원하지 않습니다. reward-points는 별도 업적 점수입니다.
Google Sheets 자동 가져오기, 설치 전 활동 이력의 자동 복원, 관리자 진행 초기화 명령은 없습니다.
전체 전투 동안 에코 미장착 유지, 실제 솔로 전투 여부, 이용권 세션별 조건 등은 판정기만으로 완성되지 않습니다. 해당 업적의 생산 이벤트·정책이 추가로 필요합니다.
활동 record의 중복 방지와 직접 지표 add·peak는 다릅니다. 모든 외부 호출이 자동 중복 제거되는 것은 아닙니다.
외부 플러그인의 실제 설치 버전, 서버 고유 ID, MCEF 화면, 여러 서버가 동일 DB를 사용할 때의 운영 결과는 별도 검증이 필요합니다.
Folia와 다른 Minecraft 버전의 호환성을 확인하지 않았습니다.

확인 범위

2026-10-05 오류 메시지, 재시도·저장·설정 처리 분기를 확인했습니다. 서버 시작·중지·재시작·전체 reload를 수행하지 않았으며 게임 내 동작은 미검증입니다.