BuzzBuild-Achievement — 사용법

업적 확인과 점수 수령

필요한 클라이언트 모드를 설치한 이용자가 /업적을 실행합니다.
진행 상황과 완료 여부를 확인합니다. 숨겨진 업적은 완료 전 정보가 가려집니다.
완료했고 reward-points가 0보다 큰 업적은 화면에서 수령합니다. 이미 수령한 건은 다시 수령할 수 없습니다.
성장 점수는 수령 여부와 별개로 완료 개수에 따라 계산됩니다. 칭호도 수령 버튼과 독립적으로 자동 지급됩니다.

화면은 열려 있는 동안 100 클라이언트 틱마다 갱신을 요청합니다. 서버 활동 저장과 칭호 처리도 100 서버 틱 주기이므로 즉시 표시되지 않을 수 있습니다. 정상 20 TPS에서는 약 5초이며 지연·재시도에 따라 더 걸립니다.

CustomCrops 수확 업적

/업적 진단에서 CustomCrops: true인지 확인합니다.
integrations.yml에 작물 ID별 min-point, products, 필요 시 high-quality를 맞춥니다.
achievements.yml에 아래처럼 조건을 추가합니다. 예시 ID는 가상이며, 기존 achievements 아래에 병합합니다.
/업적 리로드 후 테스트 이용자를 추적하고 생존·모험 모드에서 해당 성숙 작물을 수확합니다.
추적 메시지의 crop.harvest, 대상 ID, 수량, 일치 조건을 확인합니다. 검증 후 추적을 끕니다.

achievements:
  example_potato_100:
    category: 농사
    title: 감자 수확 연습
    description: 감자 산출물 100개 수확
    enabled: true
    target: 100
    condition:
      type: COUNT
      event: crop.harvest
      subjects: [potato]

수확은 파괴한 블록 수가 아니라, 연결된 수확 동작에서 실제 생성된 매핑 산출물 수량을 셉니다. 원본 작물 동작이나 산출물 이벤트가 취소되면 세지 않습니다. 고품종 수량은 crop.quality로 별도 기록합니다.

씨앗 파괴 crop.seed_break는 CustomCrops point가 1일 때, 뼛가루는 crop.bonemeal 이벤트로 집계합니다. crop.inventory는 보관 인벤토리 36칸의 내부 ID 집합을 관찰하며 같은 시점에 모든 대상이 있어야 INVENTORY를 달성합니다. 상자·방어구·보조 손을 함께 검사하지 않습니다.

보스 10회: 판정 기준 선택

두 경로는 다른 의미입니다. 같은 업적에 중복 집계하도록 연결하지 말고 운영 목적에 맞는 이벤트 하나를 선택합니다.

기준	이벤트	대상 ID	인정 대상
특정 몹 직접 처치	`mythic.kill`	MythicMobs internal name	사망 이벤트의 killer가 Player인 경우 그 플레이어
던전 완료	`dungeon.complete`	던전 `getWorldName()` 값	완료 이벤트가 발생한 플레이어
던전 완료를 보스로 분류	`boss.clear`	`dungeon-bosses`에서 정한 ID	매핑된 던전 완료 이벤트의 플레이어

개인 몹 처치 10회

MythicMobs가 실제로 반환하는 내부 ID를 확인해 example_forest_boss를 바꿉니다. 아래 값은 가상입니다.

achievements:
  example_boss_kill_10:
    category: 전투
    title: 숲 보스 사냥꾼
    description: 숲 보스 직접 처치 10회
    enabled: true
    target: 10
    condition:
      type: COUNT
      event: mythic.kill
      subjects: [example_forest_boss]

파티 전체에게 직접 처치 수를 분배하지 않습니다. 생존·모험 모드만 인정하며 몹 UUID를 활동 식별자로 사용합니다. 필요하면 condition.where.world로 이벤트의 실제 월드 이름을 제한할 수 있습니다.

던전 보스 클리어 10회

MythicDungeons 완료 이벤트와 유효한 인스턴스 UUID가 제공되는 버전인지 확인합니다.
integrations.yml에 던전→보스 ID를 등록합니다. 아래 ID는 모두 가상입니다.
achievements.yml에 boss.clear 조건을 등록합니다.
/업적 리로드 후 던전을 완료하고 추적으로 이벤트와 대상 ID를 확인합니다.

integrations.yml에 병합:

dungeon-bosses:
  example_forest_dungeon: example_forest_boss

achievements.yml에 병합:

achievements:
  example_boss_clear_10:
    category: 전투
    title: 숲 던전 정복자
    description: 숲 던전 완료 10회
    enabled: true
    target: 10
    condition:
      type: COUNT
      event: boss.clear
      subjects: [example_forest_boss]

이 경로는 던전 완료를 보스 클리어로 간주합니다. Achievement가 보스의 사망을 별도로 검사하지 않으므로, 보스를 잡아야 던전이 완료되도록 던전 자체를 구성해야 합니다. 인스턴스가 없으면 기록하지 않습니다. 같은 플레이어의 같은 회차는 활동 영수증으로 중복 처리를 방지합니다. 파티원별 인정은 각자의 완료 이벤트 발생 여부에 달려 있습니다.

완료자에게 자동 칭호 지급

Title에서 사용할 칭호를 먼저 등록하고 내부 ID를 확인합니다.
기존 업적의 조건과 목표를 유지한 채 아래 rewards만 추가합니다. example_farmer는 가상 칭호 ID입니다.
/업적 리로드를 실행합니다. 신규 완료자와 DB에 이미 완료 기록이 있는 이용자 모두 지급 대상입니다. 오프라인 완료자도 등록됩니다.
/업적 보상 상태에서 지급·미지급을 확인합니다. 필요 시 /업적 보상 동기화로 누락 건을 다시 대조합니다.
지급된 칭호는 Title 화면에서 확인·장착합니다. 자동 지급이 기존 장착 칭호를 바꾸지는 않습니다.

기존 achievements.a001 아래에 추가할 블록:

rewards:
  mode: automatic
  titles:
    - example_farmer

reward-examples.yml을 수정하는 것만으로는 적용되지 않습니다. 업적 ID·칭호 ID 조합에 대한 지급 기록을 남기며 실패 시 재시도합니다. 이미 지급된 칭호를 나중에 회수하더라도 같은 보상 기록을 재실행해 다시 주는 방식은 아닙니다.

지급을 중단하려면 rewards를 제거하거나 titles: []로 바꾸고 리로드합니다. 이미 지급한 칭호를 회수하지 않으며 처리 중인 지급은 완료될 수 있습니다. enabled: false만으로 기존 완료자의 칭호 지급을 중단하지 못합니다.

운영 시 확인할 이벤트

생산 경로	이벤트 또는 지표	집계 기준
바닐라 광석 파괴	`mine.ore`	광석 블록 1개, 심층암 접두사 제거·소문자 대상
낚시	`fish.catch`	Fish의 내부 fish ID·수량, context `rarity`
채집	`gather.minigame_success`, `gather.minigame_failure`	Gather 결과 이벤트로 연속 성공·실패 조건 구성
가공	`process.complete`, `process.output`	레시피 실행 수와 실제 생산 아이템 수량을 구분
가공 결과	`process.great`, `process.normal`	개별 실행의 대성공·일반 결과
가공 비용	`process.paid`	cents 단위 금액. 필요한 경우 `COUNT`의 `each`로 환산
수집	`collect.group`	완료한 그룹 ID
기본 지표	`player.deaths`, `play.total_seconds`, `play.session_seconds`, `player.level`	사망 횟수, 누적·연속 접속 초, 최고 레벨

이 표의 이벤트는 소스에서 생산·수신 경로를 확인한 항목입니다. 전체 카탈로그가 모두 연결되었다는 의미는 아닙니다. 비활성 업적의 pending-reason을 먼저 확인하세요.

확인 범위

2026-10-05 이벤트 어댑터, 조건 평가, 완료 저장, 칭호 송신 및 Title 수신 코드를 확인했습니다. 실제 서버의 내부 ID와 외부 플러그인 버전은 확인하지 않았으며 게임 내 동작은 미검증입니다.