BuzzBuild-Title — 설정

설정 파일과 적용

파일	역할	적용
서버 `plugins/BuzzBuild-Title/config.yml`	저장소, 표시명, 사운드, 메시지	운영자가 `/bbtitle reload` 실행
서버 `plugins/BuzzBuild-Title/titles/<id>.yml`	개별 칭호 정의 또는 DB 미러	저장소 모드에 따라 다름
서버 `plugins/BuzzBuild-Title/titles.yml`	이전 형식 카탈로그·기본 시드	레거시 읽기 지원
클라이언트 `config/buzzbuild-profile-title-ui.json`	일반 칭호 화면 좌표·색상	화면을 다시 열 때 읽음

DB 연결 정보는 Title 설정에 넣지 않습니다. Framework가 DB 풀을 제공합니다. 아래 기본값은 배포 리소스 기준이며 기존 설정 파일을 자동 덮어쓴다는 의미가 아닙니다.

저장소와 주요 동작

titles-storage.mode: database는 DB가 칭호 정의의 기준, yaml은 파일이 기준입니다. 잘못된 모드 값은 기본 데이터베이스 모드로 처리됩니다.
titles-storage.import-yaml-when-empty: DB가 비면 전체 시드, 비어 있지 않으면 누락 ID만 가져옵니다. 이름과 달리 빈 DB에만 한정되지 않습니다. 이미 등록된 ID는 YAML 수정만으로 덮어쓰지 않습니다.
titles-storage.write-yaml-mirror: DB 모드 에디터 저장 시 파일 미러를 씁니다. 미러는 DB 전체 백업이 아닙니다.
titles.op-grant-all: OP 또는 해당 전체 보유 권한 사용자에게 시작·접속·리로드 등의 동기화 시 누락 칭호를 지급합니다.
display.title-open, display.title-close: 칭호 앞뒤에 붙일 문자열입니다. 기본값은 빈 문자열과 공백이므로 자동 [ ]가 없습니다. 문구 자체에 입력한 대괄호는 별개입니다.
chat.format: {display}, {nickname}, {message}를 치환합니다. {message}가 없으면 끝에 공백과 본문을 붙입니다. 일반 포맷 문자열은 MiniMessage로 파싱하지 않습니다.
display-refresh.delays-ticks: 표시명 재적용 지연입니다. 20틱은 정상 TPS에서 약 1초입니다. 스냅샷 지연은 send-snapshot-at-ticks에서 지정합니다.
title.id-*: 서버 검증 규칙입니다. 에디터도 소문자·숫자·밑줄 ID를 검사하므로 서버 정규식만 완화해 다른 문자를 허용한다고 보장할 수 없습니다.
force-nickname-setup, nickname.*, sounds.nickname-set은 이전 Profile에서 남은 설정·처리입니다. 현재 sendSnapshot은 강제 설정 플래그를 false로 보내고 등록 핸들러도 닉네임 설정 화면을 담당하지 않으며 실제 닉네임 관리는 별도 Nickname 플러그인을 확인하세요.

최소 설정 예시

기존 파일의 다른 항목을 유지하면서 필요한 값만 조정하는 예시입니다. YAML 모드로 변경해도 보유·장착·통계 DB는 필요합니다.

titles-storage:
  mode: database
  write-yaml-mirror: true
  import-yaml-when-empty: true
titles:
  op-grant-all: false
display:
  title-open: ""
  title-close: " "
chat:
  format: "{display}: {message}"
sounds:
  title-apply:
    key: "minecraft:item.armor.equip_leather"
    volume: 1.0
    pitch: 1.0
  title-unequip:
    key: "minecraft:block.wool.break"
    volume: 1.0
    pitch: 1.0

서버 설정 키 전체

sounds.*.key는 사운드 ID 문자열이며 ""면 비활성입니다. volume, pitch는 실수이고 MASTER 카테고리로 재생합니다. 목록 클릭·스크롤 소리는 클라이언트 코드의 별도 고정값이므로 이 사운드 키로 바뀌지 않습니다.

messages.*는 문자열입니다. & 색상 코드는 전송 경로에 따라 처리되며, 해당 메시지에 전달된 %id%, %player% 등의 변수만 치환됩니다. 접속·퇴장 접미사를 비우면 이 플러그인의 대체를 건너뛰므로 서버의 원래 메시지까지 숨긴다는 뜻은 아닙니다.

키	타입	배포 기본값	설명
`titles-storage.mode`	문자열	`database`	카탈로그 기준 저장소
`titles-storage.write-yaml-mirror`	불리언	`true`	DB 저장 후 YAML 미러 작성
`titles-storage.import-yaml-when-empty`	불리언	`true`	전체 또는 누락 ID 시드 가져오기
`titles.op-grant-all`	불리언	`true`	OP·전체 보유 권한에 미보유 칭호 지급
`force-nickname-setup`	불리언	`true`	레거시 강제 설정 값; 현재 스냅샷은 false 고정
`nickname.min-length`	정수	`2`	레거시 검증 최소 길이
`nickname.max-length`	정수	`16`	레거시 검증 최대 길이
`nickname.alnum-hangul-underscore-only`	불리언	`true`	레거시 허용 문자 검사
`title.id-min-length`	정수	`2`	서버 ID 최소 길이
`title.id-max-length`	정수	`32`	서버 ID 최대 길이
`title.id-pattern`	문자열	`"^[a-z0-9_]+$"`	서버 ID 정규식
`title-editor.defaults.kind`	문자열	`complete`	신규 에디터 종류
`title-editor.defaults.grade`	문자열	`legendary`	신규 에디터 등급
`display.title-open`	문자열	`""`	칭호 앞 구분 문자열
`display.title-close`	문자열	`" "`	칭호 뒤 구분 문자열
`display-refresh.send-snapshot-at-ticks`	정수	`40`	접속 후 스냅샷 전송 지연
`chat.format`	문자열	`"{display}: {message}"`	공개 채팅 치환 포맷
`title-grade-ui.default-marker`	문자열	`"◆"`	기본 등급 마커
`title-grade-ui.grades.normal.color`	문자열	`"#9A9A9A"`	등급 글자·표시 색상
`title-grade-ui.grades.normal.marker`	문자열	`"◆"`	글리프 미사용 시 문자
`title-grade-ui.grades.normal.nexo`	문자열	`""`	등급용 Nexo 글리프 ID
`title-grade-ui.grades.uncommon.color`	문자열	`"#55C96A"`	등급 글자·표시 색상
`title-grade-ui.grades.uncommon.marker`	문자열	`"◆"`	글리프 미사용 시 문자
`title-grade-ui.grades.uncommon.nexo`	문자열	`""`	등급용 Nexo 글리프 ID
`title-grade-ui.grades.rare.color`	문자열	`"#5BA8E8"`	등급 글자·표시 색상
`title-grade-ui.grades.rare.marker`	문자열	`"◆"`	글리프 미사용 시 문자
`title-grade-ui.grades.rare.nexo`	문자열	`""`	등급용 Nexo 글리프 ID
`title-grade-ui.grades.epic.color`	문자열	`"#C070E0"`	등급 글자·표시 색상
`title-grade-ui.grades.epic.marker`	문자열	`"◆"`	글리프 미사용 시 문자
`title-grade-ui.grades.epic.nexo`	문자열	`""`	등급용 Nexo 글리프 ID
`title-grade-ui.grades.legendary.color`	문자열	`"#E8A84A"`	등급 글자·표시 색상
`title-grade-ui.grades.legendary.marker`	문자열	`"◆"`	글리프 미사용 시 문자
`title-grade-ui.grades.legendary.nexo`	문자열	`""`	등급용 Nexo 글리프 ID
`sounds.nickname-set.key`	문자열	`""`	재생할 사운드 ID
`sounds.nickname-set.volume`	실수	`1.0`	재생 음량
`sounds.nickname-set.pitch`	실수	`1.0`	재생 높낮이
`sounds.title-apply.key`	문자열	`"minecraft:item.armor.equip_leather"`	재생할 사운드 ID
`sounds.title-apply.volume`	실수	`1.0`	재생 음량
`sounds.title-apply.pitch`	실수	`1.0`	재생 높낮이
`sounds.title-unequip.key`	문자열	`"minecraft:block.wool.break"`	재생할 사운드 ID
`sounds.title-unequip.volume`	실수	`1.0`	재생 음량
`sounds.title-unequip.pitch`	실수	`1.0`	재생 높낮이
`sounds.open-titles.key`	문자열	`""`	재생할 사운드 ID
`sounds.open-titles.volume`	실수	`1.0`	재생 음량
`sounds.open-titles.pitch`	실수	`1.0`	재생 높낮이
`sounds.open-stats.key`	문자열	`""`	재생할 사운드 ID
`sounds.open-stats.volume`	실수	`1.0`	재생 음량
`sounds.open-stats.pitch`	실수	`1.0`	재생 높낮이
`sounds.error.key`	문자열	`""`	재생할 사운드 ID
`sounds.error.volume`	실수	`0.5`	재생 음량
`sounds.error.pitch`	실수	`0.7`	재생 높낮이
`messages.join-suffix`	문자열	`"님이 접속했습니다."`	해당 결과·안내 메시지
`messages.quit-suffix`	문자열	`"님이 퇴장했습니다."`	해당 결과·안내 메시지
`messages.death-fallback-suffix`	문자열	`"님이 사망했습니다."`	해당 결과·안내 메시지
`messages.no-permission`	문자열	`"&c권한이 없습니다."`	해당 결과·안내 메시지
`messages.players-only`	문자열	`"&c플레이어만 사용 가능합니다."`	해당 결과·안내 메시지
`messages.player-offline`	문자열	`"&c온라인 플레이어가 아닙니다."`	해당 결과·안내 메시지
`messages.not-a-number`	문자열	`"&c숫자가 아닙니다."`	해당 결과·안내 메시지
`messages.admin-usage`	문자열	`"&e/bbtitle <title\|grant\|revoke\|stat\|reload>"`	해당 결과·안내 메시지
`messages.admin-unknown-sub`	문자열	`"&c알 수 없는 하위 명령입니다. &e/bbtitle <title\|grant\|revoke\|stat\|reload>"`	해당 결과·안내 메시지
`messages.admin-title-editor-usage`	문자열	`"&e/bbtitle title editor [titleId]"`	해당 결과·안내 메시지
`messages.admin-title-editor-opened`	문자열	`"&a칭호 에디터를 열었습니다."`	해당 결과·안내 메시지
`messages.admin-title-editor-opened-id`	문자열	`"&a칭호 에디터를 열었습니다. &7(%id%)"`	해당 결과·안내 메시지
`messages.admin-nick-usage`	문자열	`"&e/bbnickname set <player> <닉네임>"`	해당 결과·안내 메시지
`messages.admin-nick-ok`	문자열	`"&a%player% → %nick%"`	해당 결과·안내 메시지
`messages.admin-grant-usage`	문자열	`"&e/bbtitle grant <player> <titleId>"`	해당 결과·안내 메시지
`messages.admin-revoke-usage`	문자열	`"&e/bbtitle revoke <player> <titleId>"`	해당 결과·안내 메시지
`messages.admin-stat-usage`	문자열	`"&e/bbtitle stat <player> <key> <delta>"`	해당 결과·안내 메시지
`messages.reload-ok`	문자열	`"&a칭호 설정을 다시 불러왔습니다."`	해당 결과·안내 메시지
`messages.nickname-invalid`	문자열	`"닉네임은 %min%~%max%자, 한글/영문/숫자/_ 만 가능합니다."`	해당 결과·안내 메시지
`messages.nickname-db-required`	문자열	`"닉네임 저장 불가 — Framework DB가 꺼져 있거나 연결되지 않았습니다."`	해당 결과·안내 메시지
`messages.nickname-save-fail`	문자열	`"닉네임 저장에 실패했습니다. (DB 확인)"`	해당 결과·안내 메시지
`messages.nickname-set`	문자열	`"닉네임이 설정되었습니다."`	해당 결과·안내 메시지
`messages.title-id-invalid`	문자열	`"칭호 ID는 영문 소문자/숫자/_ %min%~%max%자여야 합니다."`	해당 결과·안내 메시지
`messages.title-display-empty`	문자열	`"칭호 목록과 채팅에 사용할 표시 이름을 입력하세요."`	해당 결과·안내 메시지
`messages.title-save-db-fail`	문자열	`"칭호 저장 실패 (DB)"`	해당 결과·안내 메시지
`messages.title-save-yaml-fail`	문자열	`"칭호 YAML 저장 실패"`	해당 결과·안내 메시지
`messages.title-saved`	문자열	`"칭호 저장: %id% (%kind%/%grade%)"`	해당 결과·안내 메시지
`messages.title-unknown`	문자열	`"알 수 없는 칭호: %id%"`	해당 결과·안내 메시지
`messages.title-grant-fail`	문자열	`"칭호 지급 실패 (DB)"`	해당 결과·안내 메시지
`messages.title-granted`	문자열	`"칭호 지급: %id%"`	해당 결과·안내 메시지
`messages.title-revoke-equip-fail`	문자열	`"칭호 회수 후 장착 갱신 실패 (DB)"`	해당 결과·안내 메시지
`messages.title-revoked`	문자열	`"칭호 회수: %id%"`	해당 결과·안내 메시지
`messages.title-complete-xor`	문자열	`"완성형과 앞/뒤 조합은 함께 장착할 수 없습니다."`	해당 결과·안내 메시지
`messages.title-apply-fail`	문자열	`"칭호 적용 실패 (DB)"`	해당 결과·안내 메시지
`messages.title-applied`	문자열	`"칭호를 적용했습니다."`	해당 결과·안내 메시지
`messages.title-not-owned`	문자열	`"보유하지 않은 칭호입니다: %id%"`	해당 결과·안내 메시지
`messages.title-kind-mismatch`	문자열	`"칭호 종류가 맞지 않습니다: %id% (기대=%kind%)"`	해당 결과·안내 메시지
`messages.title-unequip-fail`	문자열	`"칭호 해제 실패 (DB)"`	해당 결과·안내 메시지
`messages.title-unequipped`	문자열	`"칭호를 해제했습니다."`	해당 결과·안내 메시지
`messages.stat-updated`	문자열	`"%key%=%value%"`	해당 결과·안내 메시지
`display-refresh.delays-ticks`	정수 목록	`[1, 20, 40, 100]`	표시명 재적용 시점

범위와 등급 보충

ID 길이는 기본 2~~32자이며 코드의 최대 길이 상한은 64입니다. 잘못된 ID 정규식은 ^[a-z0-9_]+$로 되돌아갑니다. 닉네임 길이 기본값은 2~~16, 최대 상한은 32입니다. 지연 틱의 음수는 0으로 보정합니다.

title-editor.defaults.kind는 새 에디터의 종류, grade는 새 에디터의 등급입니다. title-grade-ui.default-marker는 기본 마커입니다. 등급별 color·marker·nexo는 목록 표시를 조정합니다. 이는 게임 권한이나 획득 조건이 아닙니다.

개별 칭호 YAML

id: dawn_companion
kind: complete
grade: legendary
display: "<gold>여명의 동행자</gold>"
description: "예시 이벤트에서 지급하는 칭호"
image-height: 24
image-gap: 4

이미지 칭호라면 실제 등록한 Nexo ID를 icon: "example_badge"처럼 추가합니다. example_badge는 가상값이며 기본 제공을 뜻하지 않습니다.

키	타입	누락 시 동작/기본값	의미
`id`	문자열	파일명에서 확장자 제거	내부 식별자; 소문자로 정규화
`kind`	문자열	`complete`	`complete`, `prefix`, `suffix`
`grade`	문자열	`normal`	`normal`, `uncommon`, `rare`, `epic`, `legendary`
`display`	문자열	`""`	ID와 별개인 표시 이름; MiniMessage 지원
`description`	문자열	`""`	설명·획득 조건 안내 문구
`icon`	문자열	없음	Nexo 글리프 ID; 있으면 이미지 모드
`image-height`	정수	`24`	높이, 8~64
`image-gap`	정수	`4`	닉네임과 위치 관계, -48~48; 음수는 아래로

에디터 저장은 읽을 수 있는 표시 이름을 요구합니다. 기존 파일에서는 이미지가 있으면 빈 이름의 정의도 읽지만, 다음 에디터 저장 때는 이름이 필요합니다. description에 조건을 적는 것만으로 자동 지급되지 않습니다. 이미지 높이·위치는 에디터에서 범위를 검증하고 레코드 생성 시 범위로 보정합니다.

클라이언트 레이아웃 JSON

일반 칭호 목록용 설정이며 MCEF 에디터의 CSS 설정은 아닙니다. layoutVersion 기본값은 3이고 이전 버전 파일은 기본 레이아웃으로 다시 저장됩니다. comboVisible은 최소 3으로 보정됩니다.

{
  "layoutVersion": 3,
  "offsetX": 0,
  "offsetY": 0,
  "completeOffsetY": 0
}

나머지 키는 생략하면 코드 기본값을 사용합니다. 모든 아래 키는 정수입니다. 좌표와 크기는 화면 기준 픽셀, color·line·disabled·colorSelect은 ARGB 정수입니다. 표의 16진수 색상 표기는 설명용이며 JSON에는 16진수 리터럴을 쓸 수 없으므로 부호 있는 10진수 정수로 입력합니다.

키	기본값	역할
`layoutVersion`	`3`	레이아웃 스키마 버전
`panel`	`256`	전체 패널 크기·표시 행 수·위치·선택 색상
`completeVisible`	`3`	전체 패널 크기·표시 행 수·위치·선택 색상
`comboVisible`	`3`	전체 패널 크기·표시 행 수·위치·선택 색상
`offsetX`	`0`	전체 패널 크기·표시 행 수·위치·선택 색상
`offsetY`	`0`	전체 패널 크기·표시 행 수·위치·선택 색상
`completeOffsetY`	`0`	전체 패널 크기·표시 행 수·위치·선택 색상
`labels.completeX`	`56`	구역 제목 좌표·색상
`labels.completeY`	`20`	구역 제목 좌표·색상
`labels.prefixX`	`54`	구역 제목 좌표·색상
`labels.suffixX`	`145`	구역 제목 좌표·색상
`labels.comboY`	`78`	구역 제목 좌표·색상
`labels.condX`	`44`	구역 제목 좌표·색상
`labels.condY`	`146`	구역 제목 좌표·색상
`labels.previewX`	`44`	구역 제목 좌표·색상
`labels.previewY`	`190`	구역 제목 좌표·색상
`labels.color`	`0xFFD4C4F0`	구역 제목 좌표·색상
`complete.y`	`33`	완성형 목록 좌표·폭·높이·선택 영역
`complete.h`	`42`	완성형 목록 좌표·폭·높이·선택 영역
`complete.markX`	`44`	완성형 목록 좌표·폭·높이·선택 영역
`complete.markW`	`12`	완성형 목록 좌표·폭·높이·선택 영역
`complete.textX`	`56`	완성형 목록 좌표·폭·높이·선택 영역
`complete.textW`	`130`	완성형 목록 좌표·폭·높이·선택 영역
`complete.vX`	`192`	완성형 목록 좌표·폭·높이·선택 영역
`complete.vW`	`8`	완성형 목록 좌표·폭·높이·선택 영역
`complete.hitX`	`41`	완성형 목록 좌표·폭·높이·선택 영역
`complete.hitW`	`174`	완성형 목록 좌표·폭·높이·선택 영역
`prefix.y`	`91`	접두 목록 좌표·폭·높이·선택 영역
`prefix.h`	`48`	접두 목록 좌표·폭·높이·선택 영역
`prefix.markX`	`44`	접두 목록 좌표·폭·높이·선택 영역
`prefix.markW`	`10`	접두 목록 좌표·폭·높이·선택 영역
`prefix.textX`	`54`	접두 목록 좌표·폭·높이·선택 영역
`prefix.textW`	`50`	접두 목록 좌표·폭·높이·선택 영역
`prefix.vX`	`108`	접두 목록 좌표·폭·높이·선택 영역
`prefix.vW`	`8`	접두 목록 좌표·폭·높이·선택 영역
`prefix.hitX`	`41`	접두 목록 좌표·폭·높이·선택 영역
`prefix.hitW`	`83`	접두 목록 좌표·폭·높이·선택 영역
`suffix.y`	`91`	접미 목록 좌표·폭·높이·선택 영역
`suffix.h`	`48`	접미 목록 좌표·폭·높이·선택 영역
`suffix.markX`	`135`	접미 목록 좌표·폭·높이·선택 영역
`suffix.markW`	`10`	접미 목록 좌표·폭·높이·선택 영역
`suffix.textX`	`145`	접미 목록 좌표·폭·높이·선택 영역
`suffix.textW`	`50`	접미 목록 좌표·폭·높이·선택 영역
`suffix.vX`	`199`	접미 목록 좌표·폭·높이·선택 영역
`suffix.vW`	`8`	접미 목록 좌표·폭·높이·선택 영역
`suffix.hitX`	`132`	접미 목록 좌표·폭·높이·선택 영역
`suffix.hitW`	`83`	접미 목록 좌표·폭·높이·선택 영역
`condition.x`	`44`	설명 영역 위치·크기
`condition.y`	`168`	설명 영역 위치·크기
`condition.w`	`168`	설명 영역 위치·크기
`condition.h`	`28`	설명 영역 위치·크기
`preview.x`	`44`	미리보기 위치·크기
`preview.y`	`205`	미리보기 위치·크기
`preview.w`	`168`	미리보기 위치·크기
`preview.h`	`18`	미리보기 위치·크기
`buttons.applyX`	`57`	장착·해제 버튼 위치·크기
`buttons.applyY`	`234`	장착·해제 버튼 위치·크기
`buttons.unequipX`	`150`	장착·해제 버튼 위치·크기
`buttons.unequipY`	`234`	장착·해제 버튼 위치·크기
`buttons.w`	`49`	장착·해제 버튼 위치·크기
`buttons.h`	`17`	장착·해제 버튼 위치·크기
`scroll.w`	`3`	스크롤 여백·너비·색상
`scroll.padTop`	`2`	스크롤 여백·너비·색상
`scroll.padBottom`	`2`	스크롤 여백·너비·색상
`scroll.padRight`	`1`	스크롤 여백·너비·색상
`scroll.color`	`0xFF706CAA`	스크롤 여백·너비·색상
`scroll.line`	`0xFF2B275B`	스크롤 여백·너비·색상
`scroll.disabled`	`0xFF424150`	스크롤 여백·너비·색상
`colorSelect`	`0xFF8EF137`	전체 패널 크기·표시 행 수·위치·선택 색상

확인 범위

2026-10-05 기본 리소스와 설정 로더·카탈로그 읽기 코드를 대조했습니다. 게임 내 동작은 미검증입니다. 실제 서버 설정값이나 DB 접속 정보는 포함하지 않았습니다.

설정 리로드는 클라이언트 스냅샷을 보내지만 모든 온라인 사용자의 Bukkit 탭 표시명을 즉시 재설정하는 경로는 아닙니다. 탭 구분자가 남으면 재접속 또는 칭호 재적용 후 확인하세요.