BuzzBuild-Achievement — 설정

설정 파일은 서버의 plugins/BuzzBuild-Achievement/에 있습니다. 변경 후 /업적 리로드로 적용합니다. 예시는 해당 파일·블록에 병합하며 기존 업적 목록 전체를 덮어쓰지 마세요.

파일별 역할

파일	실제 사용
`config.yml`	`display` 설정. 구형 `achievements`는 신규 카탈로그 최초 생성 시 같은 ID의 점수 이관에만 사용
`achievements.yml`	현재 업적 정의, 그룹, 조건, 자동 칭호 보상
`integrations.yml`	작물 수확 산출물·성숙도 및 던전 보스 매핑
`design.yml`	웹 화면의 허용된 색상 키
`reward-examples.yml`	참고용. 파일 자체는 로딩하지 않음

config.yml

키	타입	기본값	설명
`display.score-per-achievement`	정수	`10`	완료 개수당 성장 점수. 음수는 0으로 보정
`display.ranks`	객체 목록	아래 네 등급	점수순 정렬 후 최대 4개 사용. 첫 기준이 0이 아니면 기본 등급 사용
`display.ranks[].name`	문자열	아래 참조	빈 이름 제외, 최대 24자로 제한
`display.ranks[].points`	숫자	아래 참조	등급 최소 점수. 음수는 0으로 보정
`display.ranks[].icon`	정수	아래 참조, 생략 시 `8`	`8`~`11` 범위로 보정
`achievements.<id>.reward-points`	정수	기본 리소스 `0`	구형 설정의 최초 이관 대상. 이후에는 새 카탈로그에서 수정

display:
  score-per-achievement: 10
  ranks:
    - {name: '새내기 기록가', points: 0, icon: 8}
    - {name: '탐구하는 모험가', points: 50, icon: 9}
    - {name: '지식 수집가', points: 100, icon: 10}
    - {name: '박학다식', points: 200, icon: 11}

성장 점수는 현재 카탈로그에 있는 완료 업적 수로 계산합니다. 수령한 업적 점수나 서버 화폐와 별개이며, 이 값을 바꾸면 기존 완료 업적의 성장 점수도 달라집니다.

achievements.yml

다음 기본값은 키 생략 시 로더 값입니다. 배포 카탈로그는 업적마다 다른 제목·목표·활성 상태를 지정합니다.

키	타입	기본값	설명
`groups.<name>`	문자열 목록	빈 목록	여러 조건에서 참조할 내부 ID 집합
`achievements`	객체	필수	업적 ID별 정의
`achievements.<id>.category`	문자열	`기타`	화면 분류
`achievements.<id>.title`	문자열	업적 ID	표시 이름
`achievements.<id>.description`	문자열	빈 문자열	설명 문구. 판정식이 아님
`achievements.<id>.metric`	문자열	빈 문자열	직접 지표 판정. 조건이 있으면 `condition.<id>`로 대체
`achievements.<id>.target`	정수	`1`	완료 목표. 활성 업적은 1 이상 필요
`achievements.<id>.enabled`	불리언	`false`	완료 판정 활성 여부
`achievements.<id>.secret`	불리언	`false`	완료 전 제목·설명·진행 숨김
`achievements.<id>.first-only`	불리언	`false`	동일 DB에서 최초 기록자만 완료 인정
`achievements.<id>.reward-points`	정수	`0`	완료 후 수동 수령하는 업적 점수. 음수는 0으로 보정
`achievements.<id>.condition`	객체	없음	아래 이벤트 조건
`achievements.<id>.rewards`	객체	없음	아래 자동 칭호 보상

schema-version(배포값 2), source.*, sheet-id, source-condition, pending-reason, retired는 현재 로더의 판정 키가 아닙니다. 설명·출처·관리용 메타데이터이며 source.timezone을 수정해도 날짜 계산은 바뀌지 않습니다. retired: true만으로 업적을 끄지 못하므로 enabled: false를 사용합니다.

조건 키

`condition` 아래 키	타입	기본값	설명
`type`	문자열	`COUNT`	아래 유형. 대문자로 변환해 해석
`event`	문자열	빈 문자열	활성 조건에 필요한 활동 이름
`subjects`	문자열 목록	빈 목록	허용 대상 ID. 일반 조건에서 비어 있으면 전체 대상
`group`	문자열	빈 문자열	`groups.<name>`을 `subjects`와 합침
`each`	정수	`1`	1 이상. 의미는 유형별로 다름
`reset-event`	문자열	빈 문자열	실패·종료 등에 사용할 활동 이름
`where`	문자열 값 객체	빈 객체	활동 context와 모두 정확히 일치해야 통과

조건 업적 ID는 소문자 영문·숫자·_·-로 32자 이내를 권장합니다. ID 검사와 별개로 생성된 condition.<id> 지표는 소문자만 허용하므로 대문자 ID는 조건 검증에 실패합니다. 직접 metric은 [a-z0-9_.-]{1,64} 형식입니다.

유형	판정	주요 제약
`COUNT`	누적 수량을 `each`로 나눈 정수 몫	보통 `each: 1`
`MAX`	전달된 수량의 최고값	과거 최고 진행 유지
`EACH`	각 대상이 `each` 이상이면 달성한 종류 수 증가	대상 필수, `target`을 대상 수로 자동 대체
`PER_SUBJECT`	한 대상에 누적된 최고 수량	각 대상의 수량을 합산하지 않음
`STREAK`	연속 수량, reset 이벤트에서 현재 연속 수 초기화	`reset-event` 필수, 최고 기록 유지
`DAYS`	하루 수량이 `each` 이상인 날짜 수	`Asia/Seoul` 고정, 연속 출석 조건이 아님
`SEQUENCE`	reset 직전 누적이 정확히 `each`면 진행 1	`reset-event` 필수, 일반적으로 목표 1
`INVENTORY`	한 시점의 `owned` 목록에 대상 전체가 있으면 진행 1	대상 필수, 시간차 소지품을 합치지 않음
`SESSION_EACH`	같은 `scope`에서 대상별 달성 종류 수	대상·scope 필요, 목표는 대상 수
`SESSION_BELOW`	같은 scope의 종료 시 누적이 `each` 미만이면 진행 1	`reset-event`·scope 필요

세션 유형에는 실제 활동 생산자가 동일한 scope와 시작·종료 이벤트를 보내야 합니다. 평가기가 존재한다는 이유만으로 이용권·던전별 모든 시나리오가 연동된 것은 아닙니다. 완료와 최고 진행은 실패 이벤트만으로 취소되지 않습니다.

최소 업적 예시

별도 연동 없이 기존 지표를 사용하는 신규 업적 예시입니다. example_deaths_10은 가상 ID이며 기존 achievements 아래에 병합합니다.

achievements:
  example_deaths_10:
    category: 기타
    title: 다시 일어서기
    description: 사망 횟수 10회 달성
    metric: player.deaths
    target: 10
    enabled: true
    secret: false
    first-only: false
    reward-points: 0

플러그인 설치 전 기록을 소급 수집하지 않습니다. 다만 이미 DB에 같은 지표가 누적되어 있으면 새 정의도 그 지표를 사용하며, 다음 지표 적용 때 완료될 수 있습니다. 의미를 바꾸는 조건에는 새 ID를 사용하세요.

자동 칭호 보상

`rewards` 아래 키	타입	기본값	설명
`mode`	문자열	`automatic`	이 값만 지원
`titles`	문자열 목록	블록을 쓰면 필수	칭호 ID 목록, 빈 목록은 지급 계획 없음, 중복 ID 제거

칭호 ID는 [a-zA-Z0-9_:-]{1,64} 형식이며 Title에 실제 등록되어 있어야 합니다. 다른 보상 키는 로딩 오류입니다. 아이템·화폐·명령어 실행 보상은 지원하지 않습니다. 적용 예시는 칭호 지급 절차를 참고하세요.

integrations.yml

키	타입	생략 시 값	설명
`crops.<crop-id>.min-point`	정수	`2147483647`	수확으로 인정할 최소 CustomCrops point
`crops.<crop-id>.products`	문자열 목록	`[]`	수확 수량에 포함할 ItemManager 내부 ID
`crops.<crop-id>.high-quality`	문자열 목록	`[]`	고품종 수량에 포함할 내부 ID
`dungeon-bosses.<dungeon-id>`	문자열	빈 문자열	던전 완료를 `boss.clear` 대상 ID로 변환

배포 파일은 여러 작물 매핑을 제공하며 예를 들어 potato는 min-point: 7, products: [POTATO, potato], high-quality: []입니다. dungeon-bosses의 배포 기본값은 {}입니다. 아래는 감자 매핑의 실제 형식을 보여주는 부분 예시입니다.

crops:
  potato:
    min-point: 7
    products: [POTATO, potato]
    high-quality: []
dungeon-bosses: {}

작물 ID와 수확 아이템 ID는 서로 다를 수 있습니다. 표시 이름이 아니라 이벤트와 ItemManager가 반환하는 ID를 사용합니다. high-quality와 products는 각각 검사하므로 고품종도 총수확에 넣으려면 두 목록에 모두 등록합니다.

design.yml

모든 값의 타입은 문자열이며 '#RRGGBB' 형태만 허용합니다. #가 주석이 되지 않도록 따옴표를 사용합니다.

`colors` 아래 키	배포 기본값	용도
`page`	`#E8DFF2`	전체 배경
`panel`	`#F5F0FA`	패널
`panel-alt`	`#DED0EB`	보조 패널
`cover`	`#49335F`	표지
`border`	`#AD93C6`	테두리
`text`	`#49345F`	본문
`muted`	`#81708F`	보조 글자
`accent`	`#9166B8`	강조
`accent-soft`	`#D5BFE8`	옅은 강조
`track`	`#D6C7E3`	진행 배경
`gold`	`#B18A45`	금색 강조
`complete`	`#647E69`	완료 표시
`bookmark`	`#BC678A`	북마크

colors:
  page: '#E8DFF2'
  accent: '#9166B8'

알 수 없는 키·잘못된 형식은 경고 후 무시합니다. 웹 화면이 다음 상태를 받을 때 반영되며 고정 PNG 아이콘 색상은 바뀌지 않습니다.

확인 범위

2026-10-05 기본 리소스와 설정 로더·조건 평가 코드를 대조했습니다. 예시의 게임 내 동작은 미검증입니다.