BuzzBuild-Esc — 설정

서버 설정은 plugins/BuzzBuild-Esc/config.yml, 메뉴는 plugins/BuzzBuild-Esc/menus/에 저장합니다. 이 경로들은 서버 폴더 기준입니다. 클라이언트 단독 메뉴를 편집하는 별도 설정 파일은 없습니다.

config.yml: 레이아웃·동기화·명령

표의 기본값은 배포되는 기본 리소스 기준입니다. 설정이 없거나 잘못된 경우의 코드 대체값은 별도로 표시합니다.

키	타입	기본값	설명
`layout.columns`	정수	`4`	그룹 열 수. 서버에서 1~8로 제한
`layout.min-rows`	정수	`6`	열의 최소 항목 행 수. 서버에서 1~12로 제한
`sync.on-join`	불리언	`true`	접속 이벤트에서 메뉴 전송 예약 여부
`sync.join-delay-ticks`	정수	`20`	접속 후 전송 지연. 최소 1서버 틱
`sync.debounce-ticks`	정수	`20`	강제 전송이 아닌 전송의 플레이어별 최소 간격. 최소 0
`commands.default-mode`	문자열	`op`	접두사가 없는 명령의 실행 모드: `player`, `console`, `op`

commands.default-mode의 코드상 누락·잘못된 모드 대체값은 player입니다. 기본 리소스에는 명시적으로 op가 들어 있으므로 초기 설치는 op로 동작합니다.

sync.on-join: false는 접속 이벤트의 서버 푸시만 끕니다. 클라이언트의 sync 요청, 운영자의 동기화, 리로드 갱신은 막지 않습니다. 클라이언트 재요청 간격 40틱·초기 재시도 기간 600틱 및 서버 요청 제한 20틱은 코드 상수이며 설정 키가 없습니다. 강제 전송인 운영 명령과 재요청 응답은 sync.debounce-ticks를 우회합니다. 재요청 응답은 별도로 플레이어당 20서버 틱에 한 번으로 제한됩니다.

config.yml: 메시지

키	타입	기본값	설명
`messages.prefix`	문자열	`'<gray>[</gray><light_purple>ESC</light_purple><gray>]</gray> '`	운영 명령 응답 접두사. 끝 공백 포함
`messages.no-permission`	문자열	`'<red>권한이 없습니다.</red>'`	내부 명령 권한 검사 실패 응답
`messages.reloaded`	문자열	`'<green>메뉴를 다시 읽고 접속자에게 갱신했습니다.</green>'`	리로드 완료 응답
`messages.synced`	문자열	`'<green>온라인 플레이어에게 ESC 메뉴를 보냈습니다.</green>'`	동기화 완료 응답
`messages.disconnect`	문자열	`'접속 종료'`	ESC 접속 종료 버튼 문구

운영 명령 응답은 MiniMessage로 처리합니다. messages.disconnect와 메뉴 항목·그룹 이름은 클라이언트에서 일반 텍스트로 그립니다. 접속 종료 문구가 비어 있으면 화면에서는 접속 종료를 사용합니다. 명령 등록 단계에서 거절되면 messages.no-permission까지 도달하지 않을 수 있습니다.

config.yml: 사운드

키	타입	기본값	설명
`sounds.enabled`	불리언	`true`	메뉴 효과음 전체 사용
`sounds.hover.enabled`	불리언	`false`	새 버튼 위로 마우스가 진입할 때 효과음
`sounds.hover.key`	문자열	`'minecraft:ui.button.click'`	호버 사운드 ID
`sounds.hover.volume`	실수	`0.18`	호버 음량
`sounds.hover.pitch`	실수	`1.45`	호버 피치
`sounds.click.enabled`	불리언	`true`	클릭 효과음
`sounds.click.key`	문자열	`'minecraft:ui.button.click'`	클릭 사운드 ID
`sounds.click.volume`	실수	`0.45`	클릭 음량
`sounds.click.pitch`	실수	`1.0`	클릭 피치

개별 효과음은 전체·개별 활성화가 모두 참이고 사운드 키가 비어 있지 않아야 켜집니다. 사운드는 클라이언트의 MASTER 분류로 재생합니다. 형식이 잘못된 ID는 버튼 클릭 소리로 대체하지만, 형식만 맞고 실제 리소스가 없는 ID까지 검증하지는 않습니다. 음량·피치에는 별도 범위 제한 코드가 없습니다.

config.yml: 테마

모든 키는 색상 문자열입니다. YAML 주석으로 해석되지 않도록 '#RRGGBB' 또는 '#AARRGGBB'처럼 따옴표로 감싸세요. 8자리는 알파가 앞에 옵니다. 6자리 색상은 코드의 대체색 알파를 유지하며, 잘못된 문자열은 대체색을 사용합니다.

키	기본값	적용 위치
`theme.overlay`	`'#A8000000'`	화면 전체 덮개
`theme.panel.top`	`'#120A1F'`	패널 내부 위쪽
`theme.panel.bottom`	`'#120A1F'`	패널 내부 아래쪽
`theme.header.top`	`'#5B2699'`	그룹 제목 배경 위쪽
`theme.header.bottom`	`'#1B0D3B'`	그룹 제목 배경 아래쪽
`theme.button.top`	`'#563CB0'`	항목 버튼 위쪽
`theme.button.bottom`	`'#563CB0'`	항목 버튼 아래쪽
`theme.button.hover-top`	`'#8D80E0'`	호버 버튼 위쪽
`theme.button.hover-bottom`	`'#8D80E0'`	호버 버튼 아래쪽
`theme.border`	`'#D7C9FF'`	패널·접속 종료 버튼 기본 테두리
`theme.text`	`'#F5EEFF'`	본문·제목 글자
`theme.muted`	`'#D9D0F3'`	보조 글자·기본 표시점
`theme.disconnect.top`	`'#5A141C'`	접속 종료 버튼 위쪽
`theme.disconnect.bottom`	`'#200710'`	접속 종료 버튼 아래쪽
`theme.disconnect.hover-top`	`'#B51414'`	접속 종료 호버 위쪽
`theme.disconnect.hover-bottom`	`'#6E1028'`	접속 종료 호버 아래쪽
`theme.disconnect.hover-border`	`'#D7C9FF'`	접속 종료 호버 테두리
`theme.panel-background`	`'#1B1524'`	패널 바탕
`theme.border-soft`	`'#BFA8FF'`	항목 버튼 테두리
`theme.accent`	`'#E2CBFF'`	호버 표시점

기본 파일에는 없지만 코드가 읽는 이전 형식의 대체 키도 있습니다. 신규 설정은 위 표의 중첩 키를 사용하세요. theme.panel 같은 문자열 값과 theme.panel.top 같은 하위 구조를 같은 YAML 위치에 동시에 둘 수는 없습니다.

대체 키	타입	기본 파일 값	코드 대체값·용도
`theme.panel`	문자열	없음	`#E50A0716`, 패널 대체 RGB
`theme.panel.inner-top`	문자열	없음	패널 RGB에 알파 `E4`를 적용한 값. `theme.panel.top`의 대체값
`theme.panel.inner-bottom`	문자열	없음	패널 RGB에 알파 `E4`를 적용한 값. `theme.panel.bottom`의 대체값
`theme.header`	문자열	없음	`#F5441538`, 제목 위·아래 대체값
`theme.button`	문자열	없음	`#C720183C`, 버튼 위·아래 대체값
`theme.button-hover`	문자열	없음	`#EE452A70`, 호버 위·아래 대체값
`theme.disconnect`	문자열	없음	`#F05A141C`, 접속 종료 위·아래 대체값
`theme.disconnect-hover`	문자열	없음	`#FF852532`, 접속 종료 호버 위·아래 대체값

메뉴 YAML 구조

menus/의 .yml·.yaml 파일을 읽습니다. main ID를 우선 선택하고, 없으면 다른 메뉴 하나를 선택합니다. 파일 열거 순서와 대체 메뉴 선택 순서를 보장하지 않으므로 주 메뉴는 id: main으로 두세요. 중복 메뉴 ID는 나중에 읽힌 정의로 덮고 경고합니다.

아래에서 G는 그룹 키, I는 항목 키를 뜻합니다. 기본값은 로더의 생략 시 대체값입니다.

키	타입	생략 시 값	설명
`id`	문자열	확장자를 뺀 파일명	메뉴 ID. 기본 파일은 `main`
`title`	문자열	`메뉴`	메뉴 메타데이터. 현재 화면 상단 제목으로 별도 표시하지 않음
`groups`	매핑	없음	없으면 경고하고 빈 메뉴 로드
`groups.G.id`	문자열	그룹 키	그룹 ID
`groups.G.title`	문자열	그룹 키	화면 그룹 제목
`groups.G.order`	정수	활성 그룹 순번	오름차순. 같으면 제목순
`groups.G.enabled`	불리언	`true`	`false`면 그룹 제외
`groups.G.items`	매핑	없음	없으면 항목 없는 그룹
`groups.G.items.I.id`	문자열	항목 키	그룹 안의 항목 ID
`groups.G.items.I.name`	문자열	항목 키	버튼 문구
`groups.G.items.I.order`	정수	활성 항목 순번	오름차순. 같으면 문구순
`groups.G.items.I.enabled`	불리언	`true`	`false`면 항목 제외
`groups.G.items.I.kind`	문자열	`command`	`native`만 네이티브 처리, 그 외는 `command`로 정규화
`groups.G.items.I.native`	문자열	빈 문자열	`native` 종류일 때 필수. 비어 있으면 해당 항목 제외
`groups.G.items.I.commands`	문자열 목록	빈 목록	순서대로 실행할 명령
`groups.G.items.I.command`	문자열	빈 문자열	비어 있지 않으면 `commands` 뒤에 추가
`groups.G.items.I.unlock-id`	문자열	빈 문자열	읽어서 보관하지만 해금 판정에는 사용하지 않음

ID는 정규화되며 그룹·항목 중복에는 _2 등의 접미사가 붙습니다. 새 ID에는 [a-z0-9][a-z0-9_-]{0,63} 형식을 사용하세요. 전송 항목 ID는 그룹ID.항목ID입니다. 항목별 permission 키나 플레이어별 표시 조건은 구현되어 있지 않습니다.

native 값

값	동작
`options`	전체 설정
`video`	비디오 설정
`sound`	소리 설정
`controls`	조작키 설정
`resourcepacks`	리소스팩 선택. 선택이 바뀌면 리소스팩 재로드
`shaders`	Iris 화면 열기 시도. 실패하면 비디오 설정

알 수 없는 비어 있지 않은 native 값은 전체 설정으로 이동합니다.

기본 서버 메뉴의 command 항목

아래 문자열은 배포 리소스에 들어 있는 값입니다. 해당 명령의 존재·권한·호환성을 ESC가 자동 확인하지는 않습니다.

그룹	버튼	기본 명령
캐릭터	아바타	`op:아바타 %player%`
캐릭터	우편함	`op:우편함 %player%`
캐릭터	탈 것 선택	`player:탈것`
캐릭터	칭호	`op:칭호 %player%`
캐릭터	파티	`op:파티`
컨텐츠	수집	`op:수집 %player%`
컨텐츠	업적	`op:업적 %player%`
컨텐츠	에코	`op:에코`
시스템	내 땅	`op:내땅 %player%`
시스템	치지직 연결	`op:후원 %player%`
시스템	쿠폰 입력	`op:쿠폰입력 %player%`
시스템	가이드	`op:가이드 %player%`

마지막 설정 그룹에는 위의 native 여섯 항목이 순서대로 포함됩니다. 실행 모드와 OP 처리의 제한은 명령어·권한을 확인하세요.

최소 설정 예시

기존 config.yml에서 아래 항목만 변경하고 메시지·테마 등 나머지는 기본 파일 값을 유지하는 예시입니다. 기본 배포값과 달리 명령 실행 모드를 player로 명시합니다.

layout:
  columns: 1
  min-rows: 2
sync:
  on-join: true
  join-delay-ticks: 20
  debounce-ticks: 20
commands:
  default-mode: player

menus/main.yml 전체를 간단한 설정 메뉴로 구성하는 예시입니다. 추가 플러그인 명령이 필요하지 않습니다.

id: main
title: 메뉴
groups:
  settings:
    title: 설정
    order: 1
    enabled: true
    items:
      options:
        name: 전체 설정
        order: 1
        kind: native
        native: options
      sound:
        name: 소리 설정
        order: 2
        kind: native
        native: sound

변경 후 /이스크 리로드로 다시 읽어 적용합니다. 설치·적용 절차를 참고하세요.

확인 범위

2026-10-05 기준 기본 리소스와 설정 읽기·정규화·전송·렌더링 코드를 대조했습니다. 게임 내 동작은 미검증입니다. GUI 크기별 배치와 실제 사운드·Iris 호환성은 별도 확인이 필요합니다.