BuzzBuild-Achievement — 개요

BuzzBuild-Achievement는 서버 활동을 업적 조건으로 집계하고 이용자별 진행 상황과 완료 기록을 저장하는 Paper 플러그인입니다. Fabric 클라이언트 모드가 업적 화면을 표시합니다.

핵심 기능

기능	구현 범위
조건 집계	누적 수량, 최대값, 종류별 달성, 연속 성공·실패, 날짜별 달성, 동시 소지품 확인 등
진행 저장	Framework의 MariaDB에 지표, 조건 상태, 완료 기록, 최초 달성자 저장
업적 화면	`/업적`으로 진행·완료·보상 확인. `mcef-modern` 설치 시 웹 화면, 없으면 기본 화면
숨겨진 업적	완료 전 제목·설명·진행 수치를 숨김
최초 달성	`first-only` 업적은 DB에 기록된 최초 달성자에게만 완료 인정
점수	완료 개수 기반 성장 점수와 버튼으로 수령하는 업적 점수를 별도 관리
자동 칭호	지정한 칭호 ID를 완료자에게 자동 지급하고 기존 완료자도 소급 처리
운영 진단	설정 리로드, 활동 추적, 저장 대기와 칭호 지급 상태 조회

업적 설명만 수정해도 조건이 바뀌는 방식은 아닙니다. 실제 판정은 achievements.yml의 metric 또는 condition으로 결정합니다. Google Sheets를 실시간으로 읽거나 동기화하는 기능은 없습니다.

다음은 현재 소스에 지정된 빌드·메타데이터 기준이며 다른 버전의 호환성을 보장하지 않습니다.

항목	확인한 값
플러그인 버전	`0.1.0`
Minecraft	`26.1.2`
Java	컴파일·툴체인 `25`, Fabric 요구 `>=25`
서버	Paper API `26.1.2.build.69-stable`, `api-version: '26.1.2'`
클라이언트	Fabric, `environment: client`
Fabric Loader	빌드 `0.19.3`, 메타데이터 `>=0.19.3`
Fabric API	빌드 `0.155.2+26.1.2`, 메타데이터 필수 의존
CustomCrops	컴파일 참조 `3.6.52`; 다른 버전 API 호환성은 별도 확인 필요

Folia, Forge, NeoForge 지원은 확인되지 않았습니다.

구분	구성 요소	역할
서버 필수	BuzzBuild-Framework	준비된 MariaDB 데이터 소스, 테이블 등록, 메시징 서비스
화면 필수	Achievement Fabric, Framework Fabric, Fabric API	서버 상태 수신 및 화면 표시
화면 선택	`mcef-modern`	웹 화면. 초기화 실패 시 기본 화면으로 전환하는 코드 존재
선택	CustomCrops	작물 수확 수량·고품종·뼛가루·소지품 집계
선택	MythicMobs, MythicDungeons	개인 몹 처치, 던전 완료 및 보스 클리어 매핑
선택	Fish, Gather, Process, Collect	낚시·채집·가공·수집 이벤트
선택	Echo, EchoCompass, Prison	메타데이터의 선택 의존성. 관련 지표는 생산 플러그인의 API 호출도 필요
칭호 지급 시 필요	BuzzBuild-Title	`TitleRewardApi.grantTitleOnce` 서비스를 제공하는 버전

선택 의존성이 없어도 해당 연동 외의 기능은 사용할 수 있지만, 그 플러그인이 보내야 할 활동은 집계되지 않습니다. enabled: true는 의존성이 설치되었다는 뜻이 아닙니다.

2026-10-05에 Gradle, 서버·클라이언트 메타데이터, 명령어, 기본 리소스, 조건 평가·저장·연동 코드를 확인했습니다. 게임 내 동작은 미검증입니다.