BuzzBuild-Achievement — 설치

설치 구성

Minecraft 26.1.2, Java 25를 기준으로 준비합니다. 상세 버전은 지원 환경을 확인하세요.

위치	파일·구성
서버 plugins/	BuzzBuild-Achievement-Paper-0.1.0.jar, 호환되는 Framework Paper
게임 프로필 mods/	BuzzBuild-Achievement-Fabric-0.1.0.jar, Framework Fabric, Fabric API
게임 프로필 mods/ 선택	호환되는 mcef-modern 모드
서버 plugins/ 선택	실제 사용하는 작물·낚시·채집·가공·수집·던전·칭호 연동 플러그인

Paper JAR와 Fabric JAR는 설치 위치가 다릅니다. 클라이언트 모드가 없으면 서버에서 화면 데이터를 보내도 업적 화면을 열 수 없습니다.

최초 실행 전 준비

1. Framework의 MariaDB 연결과 메시징 서비스를 준비합니다. Achievement에 별도 DB 연결 주소를 설정하는 키는 없습니다.
2. 서버와 게임 프로필에 각 JAR를 배치합니다. 클라이언트 모드 교체는 게임을 완전히 종료한 상태에서 진행합니다.
3. 선택 연동을 준비합니다. 칭호 보상을 사용할 경우 TitleRewardApi를 제공하는 Title이 필요합니다.
4. 서버 운영자가 승인된 점검 일정에 최초 로딩을 진행합니다. 전체 /reload로 플러그인 설치를 적용하지 않습니다.

최초 로딩 시 생성되는 파일

서버의 plugins/BuzzBuild-Achievement/ 아래에 없는 기본 파일을 생성합니다. 이미 있는 파일을 새 기본값으로 일괄 덮어쓰지는 않습니다.

파일	역할
config.yml	성장 점수와 화면 등급. 과거 형식의 업적 목록도 포함
achievements.yml	현재 사용하는 업적 정의·조건·칭호 보상
integrations.yml	CustomCrops 작물·산출물과 던전→보스 연결
design.yml	웹 화면 색상
reward-examples.yml	참고용 보상 조각. 자동으로 읽어 적용하지 않음

Framework 데이터 소스가 준비되고 테이블·메시징 서비스가 있어야 정상 활성화됩니다. 조건 상태·완료·최초 달성·활동 중복 방지·칭호 지급 대기 테이블은 등록된 마이그레이션으로 준비합니다.

설정 적용 순서

1. 기존 설정과 DB를 운영 정책에 따라 백업합니다.
2. achievements.yml에서 사용할 조건과 enabled를 확인합니다. 기존 ID를 다른 의미의 업적에 재사용하지 않습니다.
3. integrations.yml의 내부 ID를 실제 연동 플러그인과 맞춥니다. 기본 dungeon-bosses는 비어 있습니다.
4. 칭호가 필요하면 기존 업적에 rewards를 추가합니다. 리로드하면 기존 완료자도 소급 지급 대상이 됩니다.
5. 관리자가 /업적 리로드를 실행하고 /업적 진단, 필요 시 /업적 보상 상태를 확인합니다.
6. 접속 중인 테스트 이용자를 /업적 추적 <닉네임>으로 지정해 활동이 들어오는지 확인하고, 이용자의 /업적 화면을 확인합니다.

리로드는 설정을 다시 읽습니다. 새 JAR 로딩이나 시작 시점에 등록되는 외부 이벤트 연동을 다시 설치하는 명령은 아닙니다. JAR 변경은 운영자의 별도 점검 절차로 적용합니다.

achievements.yml 최초 생성 때에는 config.yml의 같은 ID에 있던 reward-points만 새 기본 카탈로그로 옮깁니다. 기존 조건·목표·활성 여부 전체를 이관하지 않으므로 구형 사용자 설정은 비교가 필요합니다.

확인 범위

2026-10-05 소스의 리소스 생성, 서비스 검사, 마이그레이션 등록, 설정 로딩 순서를 확인했습니다. 설치·서버 실행은 수행하지 않았으며 게임 내 동작은 미검증입니다.