BuzzBuild-Camera — 설정

설정 파일

위치	형식	역할·적용
서버 `plugins/BuzzBuild-Camera/config.yml`	YAML	기본 연출·세션·청크·메시지. `/카메라 리로드`
서버 `plugins/BuzzBuild-Camera/sequences/*.yml`	YAML	시퀀스 정의. 같은 리로드 명령
클라이언트 `config/buzzbuild-camera.properties`	Java properties	진단 액션바. 다음 클라이언트 실행 시 읽기

경로는 서버·게임 인스턴스 기준입니다. 시퀀스는 해당 폴더 바로 아래의 .yml 파일만 읽으며, .yaml이나 하위 폴더는 읽지 않습니다. 영구 플레이어 데이터나 DB 연결 설정은 없습니다.

config.yml: view

아래 기본값은 배포 리소스 기준입니다. 틱은 정상 20 TPS에서 20틱 = 1초입니다.

키	타입	기본값	설명
`view.default-hold-ticks`	정수	`40`	목표 시점 유지. 음수는 무기한 유지로 처리되며 표준 표기는 `-1`
`view.default-transition-ticks`	정수	`40`	목표까지 이동 시간
`view.default-return-ticks`	정수	`24`	플레이어로 복귀. 명령 중지에도 사용
`view.default-chunk-view-radius`	정수	`12`	클라이언트 청크 창 힌트, 2~64로 제한
`view.max-hold-ticks`	정수	`12000`	유한 유지 시간 상한. 음수 유지에는 미적용. 유효 상한 최소 1
`view.max-transition-ticks`	정수	`200`	서버 이동 시간 상한, 유효 상한 최소 1
`view.max-return-ticks`	정수	`200`	서버 복귀 시간 상한, 유효 상한 최소 1
`view.require-client-mod`	불리언	`true`	대상이 `buzz:payload` 채널을 듣는지 검사

이동·복귀에 0 이하를 주면 서버 기본값으로 대체한 뒤 최소 1틱과 상한을 적용합니다. 클라이언트는 이동·복귀를 다시 1~200틱으로 제한하므로 서버 상한을 200보다 높여도 그 시간대로 연출되지 않습니다. 유한 유지 시간은 최소 1틱입니다. pitch는 −90~90도입니다.

require-client-mod: false는 채널 검사만 생략합니다. 바닐라 클라이언트에 연출 기능을 제공하지 않으며, true여도 Framework 채널 존재만으로 Camera 모드까지 설치되었다고 보장하지 않습니다.

config.yml: session

키	타입	기본값	설명
`session.release-on-world-change`	불리언	`true`	월드 변경 이벤트에서 중지
`session.release-on-death`	불리언	`true`	사망 이벤트에서 중지
`session.release-on-teleport`	불리언	`true`	텔레포트 이벤트에서 중지

퇴장은 설정과 무관하게 세션을 정리합니다. 서버 월드 변경 해제를 꺼도 클라이언트 차원 키 불일치 검사는 남습니다. 텔레포트 리스너는 취소된 이벤트를 무시하도록 선언되어 있지 않아, 실제 이동이 취소되어도 연출이 중지될 수 있습니다.

config.yml: chunks

반경·송신 거리는 청크 단위입니다.

키	타입	기본값	설명·보정 범위
`chunks.keep-loaded`	불리언	`true`	각 샷 주변 플러그인 청크 티켓 유지
`chunks.ticket-radius`	정수	`4`	티켓 반경 0~16. 스트리밍 설정이 켜져 있으면 최대 16으로 제한한 stream 반경과 큰 값 사용
`chunks.expand-send-view-distance`	불리언	`true`	세션 중 송신 거리를 임시 확장
`chunks.min-send-view-distance`	정수	`12`	확장 하한 2~32
`chunks.max-send-view-distance`	정수	`32`	확장 상한 2~32. 보정된 하한보다 작으면 하한 사용
`chunks.send-view-distance-margin`	정수	`2`	플레이어↔샷 청크 거리와 반경에 추가하는 여유, 최소 0
`chunks.stream.enabled`	불리언	`true`	별도 청크 패킷 전송. 브리지 실패 시 티켓·송신 거리 경로만 남음
`chunks.stream.radius`	정수	`12`	스트리밍 기본 반경, 2~32
`chunks.stream.dynamic-top-down`	불리언	`true`	지형 대비 높이·pitch 등을 이용해 반경 계산
`chunks.stream.max-dynamic-radius`	정수	`48`	동적 계산 반경 상한, 8~64
`chunks.stream.frustum`	불리언	`true`	yaw/pitch 방향의 레이 격자로 청크 후보 추가
`chunks.stream.scene-distance-blocks`	정수	`640`	레이 탐색 거리(블록), 64~2048. 실제 화면 표시 보장 거리가 아님
`chunks.stream.horizontal-fov`	실수	`110.0`	레이 격자 가로 각도, 30~140도
`chunks.stream.vertical-fov`	실수	`80.0`	레이 격자 세로 각도, 30~120도
`chunks.stream.samples-x`	정수	`9`	가로 샘플 수, 3~21
`chunks.stream.samples-y`	정수	`7`	세로 샘플 수, 3~15
`chunks.stream.step-blocks`	정수	`8`	레이 샘플 간격(블록), 4~32
`chunks.stream.padding-chunks`	정수	`2`	샘플 주변 추가 반경, 0~6
`chunks.stream.chunks-per-tick`	정수	`32`	플레이어당 틱의 성공 전송 청크 수 한도, 1~192
`chunks.stream.refresh-ticks`	정수	`80`	전송 큐 갱신 간격, 10~400틱. 큐가 비지 않으면 갱신을 20틱 미룸

horizontal-fov·vertical-fov는 패킷 전송 후보 계산용이며 게임 화면 FOV를 변경하지 않습니다. 티켓 반경·동적 계산 반경·클라이언트 창 반경은 서로 다른 제한입니다. 반경과 샷 수가 커지면 청크 처리량도 커집니다.

config.yml: messages

모든 messages.*는 문자열(MiniMessage)입니다. prefix는 /카메라 응답 앞에 붙고, <id>·<ids>·<player>는 해당 응답에서 치환됩니다. /시점변경의 메시지는 코드에 고정되어 이 설정을 사용하지 않습니다.

키	타입	기본값	설명
`messages.prefix`	문자열	`"<aqua>[BB-Camera]</aqua> "`	응답 접두어
`messages.help-header`	문자열	`"<yellow>/카메라 <gray>시네마틱 시퀀스"`	도움말 제목
`messages.help-play`	문자열	`"<white>/카메라 재생 <시퀀스id> [닉] <gray>— YAML 시퀀스"`	재생 도움말
`messages.help-view`	문자열	`"<white>/카메라 시점 [x y z] [yaw pitch] [닉] <gray>— 한 점. 좌표 없으면 현재 눈 위치"`	시점 도움말
`messages.help-stop`	문자열	`"<white>/카메라 중지 [닉] <gray>— 연출 취소 (별칭: 종료)"`	중지 도움말
`messages.help-list`	문자열	`"<white>/카메라 목록 <gray>— 로드된 시퀀스 id"`	목록 도움말
`messages.help-reload`	문자열	`"<white>/카메라 리로드 <gray>— 이 파일 + sequences/"`	리로드 도움말
`messages.unknown`	문자열	`"<red>알 수 없는 명령입니다. <gray>/카메라 도움말"`	알 수 없는 하위 명령
`messages.usage-play`	문자열	`"<yellow>/카메라 재생 <시퀀스id> [닉]"`	재생 문법 오류
`messages.usage-view`	문자열	`"<yellow>/카메라 시점 [x y z] [yaw pitch] [닉] <gray>— 콘솔은 좌표와 닉이 필요합니다"`	시점 문법 오류
`messages.player-only`	문자열	`"<red>플레이어만 사용할 수 있습니다. 콘솔은 닉네임을 지정하세요."`	대상 닉 없는 콘솔 실행
`messages.no-permission`	문자열	`"<red>권한이 없습니다."`	권한 부족
`messages.reloaded`	문자열	`"<green>설정과 시퀀스를 다시 불러왔습니다."`	리로드 완료
`messages.player-not-found`	문자열	`"<red>플레이어를 찾을 수 없습니다."`	온라인 닉 검색 실패
`messages.other-denied`	문자열	`"<red>다른 플레이어에게 카메라를 보낼 수 없습니다."`	닉 지정 실행 권한 부족
`messages.client-required`	문자열	`"<red>Camera 클라이언트 모드가 필요합니다."`	서비스 송신 실패 안내
`messages.sequence-missing`	문자열	`"<red>시퀀스가 없습니다. <white><id>"`	없는 시퀀스 ID
`messages.list`	문자열	`"<gray>시퀀스: <white><ids>"`	시퀀스 목록
`messages.list-empty`	문자열	`"<gray>로드된 시퀀스가 없습니다. sequences/ 를 확인하세요."`	빈 시퀀스 목록
`messages.sent-play`	문자열	`"<gray>시퀀스를 요청했습니다. <white><id></white> → <player>"`	재생 요청 송신
`messages.sent-view`	문자열	`"<gray>한 점 시점을 요청했습니다. → <player>"`	시점 요청 송신
`messages.sent-stop`	문자열	`"<gray>카메라 중지를 요청했습니다. → <player>"`	중지 요청 송신
`messages.bad-number`	문자열	`"<red>좌표 또는 각도가 올바르지 않습니다."`	잘못된 좌표·각도

시퀀스 YAML

키	타입	생략 시 값	설명
`id`	문자열	확장자를 뺀 파일명	앞뒤 공백 제거·소문자화. 중복 ID는 나중에 로드된 값이 덮어씀
`world`	문자열	`""`	비면 대상의 현재 차원 키. 예: `minecraft:overworld`
`return-ticks`	정수	`view.default-return-ticks`	마지막 샷 뒤 복귀 시간
`default-transition-ticks`	정수	`view.default-transition-ticks`	샷 이동 기본값
`default-hold-ticks`	정수	`view.default-hold-ticks`	샷 유지 기본값
`default-chunk-view-radius`	정수	`view.default-chunk-view-radius`	샷의 클라이언트 청크 힌트 기본값
`shots`	목록 또는 이름별 매핑	없음	유효 샷이 없으면 해당 시퀀스를 등록하지 않음
`shots[].id`	문자열	`shot-1` 등 입력 순번	매핑 형식은 매핑 키가 기본 ID
`shots[].x`, `shots[].y`, `shots[].z`	숫자	필수	절대 좌표. 목록에서 누락된 샷은 건너뜀
`shots[].yaw`	숫자	`0`	수평 방향(도)
`shots[].pitch`	숫자	`0`	수직 방향(도), −90~90
`shots[].hold-ticks`	정수	시퀀스의 유지 기본값	`-1`이면 중지까지 유지, 뒤의 샷으로 자동 진행하지 않음
`shots[].transition-ticks`	정수	시퀀스의 이동 기본값	목표 샷으로 이동 시간
`shots[].chunk-view-radius`	정수	시퀀스의 청크 기본값	송신 시 2~64 제한, 0 이하는 전역 기본값 사용

샷별 값 → 시퀀스 기본값 → 전역 기본값 순으로 결정됩니다. 동봉 intro.yml은 return-ticks: 24, 이동·유지 기본값 40, 청크 기본값 12를 명시하므로 전역 기본값만 바꾸면 이 값들은 바뀌지 않습니다.

world는 월드 간 이동 지시가 아닙니다. 클라이언트 현재 차원과 다르면 연출을 해제합니다. 서버 청크 처리는 대상 플레이어의 현재 월드 기준입니다.

최소 설정 예시

기본 생성된 config.yml에서 다음 부분만 변경하는 예시입니다. 나머지 기본 키와 메시지는 유지하세요.

view:
  default-hold-ticks: 40
  default-transition-ticks: 40
  default-return-ticks: 24
  default-chunk-view-radius: 12
  require-client-mod: true

sequences/example.yml의 최소 한 샷 예시입니다. 좌표는 가상값이므로 장면에 맞게 바꾸세요.

id: example
world: ""
shots:
  - x: 10.0
    y: 80.0
    z: 20.0
    yaw: 180.0
    pitch: 25.0

클라이언트 설정

키	타입	기본값	설명
`debug`	불리언 문자열	`false`	요청 수신 시 시점·시퀀스·중지 정보를 진단 액션바로 표시

config/buzzbuild-camera.properties는 YAML이 아닌 properties 형식입니다.

debug=false

확인 범위

2026-10-05 기본 리소스와 서버·클라이언트 읽기 코드를 대조했습니다. 게임 내 동작은 미검증입니다.