[      마인크래프트 증강 플러그인      ]

게임 버전 1.21.10이 아니고 26.2로 하셔야 합니다!!

0. 어떤 플러그인 일까?

롤에 증강이라는 시스템을 참고하여서 만든 배틀그라운드 형식의 PVP 플러그인입니다.

재미를 위해서 지인들과 다양한 맵과 다양한 상황에서 플레이를 해보며 밸런스를 조절하기도 하고 떄로는 버그를 찾아서 고치면서 완성해간 플러그인입니다!

1. 정보

테스트한 환경 : PAPERMC 26.2 (26.2-47-main@ad5d26a) , JAVA 25

빌드한 환경 : JDK 26 (Gradle toolchain)

2. 설치 방법

1. 아래 플러그인을 다운로드 받는다.

2. 마인크래프트 서버를 준비한다.

3. 준비된 서버에서 plugins/ 폴더 안에 다운로드한 플러그인을 넣는다.

3. 다운로드

최신 버전 다운로드 : https://sejinjinit.tistory.com/71

베타 버전 혹은 최신 버전 다운로드  : https://github.com/beenstrong/augmentPvp/releases

4. 게임 간단 플레이 설명서

1. 플레이할 맵에서 자기장의 중심으로 설정하고 싶은 곳에서 /aug game setcenter를 입력합니다.

2. /aug game start 를 입력하면 바로 게임을 시작할 수 있습니다.

+ 꿀팁 : /aug choose 명령어를 입력해야 할떄, shift + f를 눌러주세요.

자세한 내용은 가이드 문서를 읽어주세요.

5. 게임 설정 변경

플러그인을 유저분들 취향에 맞게 플레이할 수 있도록 대부분의 사항을 수정 할 수 있도록 되어있습니다.

!!모든 설정은 /aug reload 를 실행하거나 서버를 재시작해야지 적용됩니다!!

config.yml (게임의 기본적인 설정)

# ============================================================
#  증강 PvP (Augment Pvp) 설정
# ============================================================

# 증강 선택권(토큰)을 지급할 레벨 설정
# PvP 게임 모드에서는 보통 game.augment_grants(시간/킬 기반)로 지급하므로 기본 비활성.
level_rewards:
  enabled: false           # 경험치 레벨업 기반 증강 지급 사용 여부
  # fixed  = 지정한 레벨 목록에서만 지급
  # interval = 일정 레벨 간격마다 지급
  mode: fixed
  fixed_levels: [3, 7, 15, 20, 30, 40, 50]
  interval: 5

# ============================================================
#  PvP 배틀로얄 게임 설정
# ============================================================
game:
  # 월드보더/산개의 중심. /aug game setcenter 로 현재 위치로 변경 가능
  center:
    world: world
    x: 0
    z: 0
  border:
    initial_radius: 250          # 시작 시 중심 기준 반경(블록) - 맵 크기
    final_radius: 20             # 최종적으로 줄어들 반경
    # 축소는 [대기 → 일정량 축소]를 최종 반경까지 반복하는 단계식.
    # 예) wait 60, shrink 60, step 10 → 60초 대기 후 60초 동안 반경 10 축소, 최종 반경까지 반복.
    wait_seconds: 20             # 각 축소 전 대기(정지) 시간
    shrink_seconds: 15           # 한 단계 축소에 걸리는 시간
    shrink_step: 30              # 한 단계에 줄어드는 반경(블록)
  start_countdown_seconds: 0     # 시작 카운트다운(0이면 대기 없이 즉시 시작). 이 동안 이동/전투 불가
  grace_period_seconds: 15       # 시작 직후 서로 공격 불가한 평화 시간
  min_players: 2                 # 게임 시작에 필요한 최소 인원
  pvp_only_during_game: true     # true 면 게임 진행 중(평화시간 이후)에만 PvP 허용
  reset_data_on_end: true        # 게임 종료 시 모든 증강/진행도 초기화
  on_death: spectate             # 탈락 시 처리: spectate(죽은 자리 관전) / kick(서버 추방)
  infinite_durability: false     # true 면 게임 중 도구/방어구 내구도가 소모되지 않음
  # 안티 캠핑: 전투를 오래 회피하고 숨어 있는 플레이어의 위치를 전체 공개하고 발광 표시
  anti_camp:
    enabled: true                # 숨은 유저 공개 기능 사용 여부
    reveal_seconds: 45           # 전투(공격/피격) 없이 이 시간(초) 숨어 있으면 위치 공개 + 발광
    warn_seconds: 10             # 공개 몇 초 전에 당사자에게 경고(0이면 경고 없음)
    repeat_broadcast_seconds: 15 # 공개 후에도 계속 숨어 있으면 이 간격(초)으로 위치 재공개(0이면 1회만)
  # 데스매치: 보더가 최종 크기에 도달하고 일정 시간이 지나면 모든 생존자가 지속적으로 동일한 피해를 받아 승부를 강제 마무리
  deathmatch:
    enabled: true                # 데스매치 사용 여부
    delay_seconds: 30            # 최종 크기 도달 후 이 시간(초)이 지나면 데스매치 시작
    damage: 2.0                  # interval 마다 모든 생존자에게 주는 피해(1.0 = 하트 반 칸)
    interval_seconds: 1          # 피해를 주는 간격(초)
  # 바닥 아이템 정리: 게임 중 오래 떨어져 있는 드랍 아이템을 제거해 렉/잔여물을 줄임(탈락자 루팅 시간은 보장)
  item_cleanup:
    enabled: true                # 바닥 아이템 자동 정리 사용 여부
    lifetime_seconds: 60         # 이 시간(초)보다 오래 바닥에 있던 아이템을 제거
    check_seconds: 5             # 정리를 수행하는 주기(초)
  scatter:
    min_spacing: 30              # 산개 시 플레이어 간 최소 간격(블록)
    close_pair_count: 2          # 서로 가깝게 시작시킬 인원 수
    close_pair_distance: 8       # 가까운 쌍의 간격(블록)
  # 증강 지급 방식
  augment_grants:
    # 게임 시작(전투 개시) 즉시 1회 지급
    on_start:
      enabled: true             # true 면 게임 시작과 동시에 모든 생존자에게 증강 카드 지급
      rarity: prism               # roll(확률표) / silver / gold / prism — roll 이면 모든 생존자가 같은 등급을 받음
    time:
      enabled: true
      interval_seconds: 120      # 이 시간마다 생존자 전체에게 증강 카드 지급
      rarity: roll               # roll(확률표) / silver / gold / prism — roll 이면 모든 생존자가 같은 등급을 받음
    kills:
      enabled: true
      per_kills: 2               # 플레이어를 이만큼 처치할 때마다 증강 카드 지급

# 월드에 떠 있는 카드 UI 설정
cards:
  distance: 3.0            # 플레이어 앞 카드 생성 거리(블록) - 가까울수록 잘 보임
  spacing: 2.5             # 좌/중/우 카드 간격(좁으면 카드끼리 겹칠 수 있음)
  duration_seconds: 60     # 미선택 시 카드가 유지되는 시간
  restrict_movement: false # 선택 중 이동 제한 여부
  view_follow_degrees: 55  # 시야가 이 각도 이상 벗어나면 카드가 부드럽게 따라옴(0=항상 정면 고정 없이 즉시 추적)

# 등급별 등장 확률(가중치). 합이 100 이 아니어도 비율로 정규화됨
rarity_weights:
  silver: 65.0
  gold: 28.0
  prism: 7.0

# 중복 방지 정책
duplicate_policy:
  offered_augments_never_appear_again: true   # 한 번 후보로 나온 증강 재등장 금지
  selected_augments_never_appear_again: true  # 선택한 증강 재등장 금지
  allow_stackable_augments: true              # 중첩형 증강은 최대치 전까지 재등장 허용

# 게임플레이
gameplay:
  pvp: true                            # 플레이어 간 전투 허용
  explosive_mining_breaks_blocks: true # '폭발 채굴' 증강의 주변 블록 파괴 허용
  particles: true
  sounds: true
  synergy_enabled: true
  auto_save_seconds: 300               # 데이터 자동 저장 주기(초)
  # 폭발 채굴 등에서 보호할 중요 블록
  protected_blocks:
    - BEDROCK
    - CHEST
    - TRAPPED_CHEST
    - ENDER_CHEST
    - END_PORTAL
    - END_PORTAL_FRAME
    - SPAWNER
    - COMMAND_BLOCK
    - BARRIER
    - SHULKER_BOX
  # 활성화할 월드(비워두면 모든 월드에서 작동)
  enabled_worlds: []

kit.yml (게임 시작시 지급될 아이템 설정)

# ============================================================
#  게임 시작 시 지급되는 기본 킷 (철 풀세트 + 철검)
#  material 은 Bukkit Material 이름을 사용합니다.
# ============================================================

# 방어구 슬롯
armor:
  helmet: IRON_HELMET
  chestplate: IRON_CHESTPLATE
  leggings: IRON_LEGGINGS
  boots: IRON_BOOTS

# 주 손에 드는 아이템
mainhand: IRON_SWORD

# 인벤토리에 추가로 지급할 아이템 목록
items:
  - material: IRON_PICKAXE
    amount: 1
  - material: IRON_AXE
    amount: 1
  - material: COOKED_BEEF
    amount: 16
  - material: OAK_PLANKS
    amount: 32
  - material: BOW
    amount: 1
  - material: ARROW
    amount: 32

message.yml (게임 내 메시지 관련)

# 모든 메시지는 MiniMessage 형식을 지원합니다. {key} 형태의 플레이스홀더가 치환됩니다.
prefix: "<gradient:#7efff5:#c77dff>[증강PVP]</gradient> "

token:
  granted: "<yellow>증강 선택권 <white><amount></white>개를 획득했습니다! <gray>(보유: <total>)"

card:
  opened: "<gray>앞에 나타난 <white>3개의 증강 카드</white> 중 하나를 <yellow>우클릭</yellow>하여 선택하세요."
  already_open: "<red>이미 선택 중인 카드가 있습니다."
  no_token: "<red>사용 가능한 증강 선택권이 없습니다."
  no_candidates: "<red>등장 가능한 증강이 없습니다. 관리자에게 문의하세요."
  spawn_failed: "<red>카드를 생성하지 못했습니다. 주변 공간을 확인하세요."
  not_owner: "<red>당신의 카드가 아닙니다."
  select_failed: "<red>증강을 적용하지 못했습니다."
  selected: "<gray>[<rarity>] <white><name></white> <gray>증강을 선택했습니다!"
  token_remaining: "<gray>남은 선택권: <yellow><amount></yellow>개 - <white>/augment choose</white> 로 다시 선택하세요."
  closed: "<gray>증강 카드가 닫혔습니다. 선택권은 유지됩니다. <white>/augment choose"
  world_disabled: "<red>이 월드에서는 증강 시스템이 비활성화되어 있습니다."
  deferred_combat: "<yellow>⚔ 전투 중이라 증강 카드를 열지 않았습니다. 선택권 <white><amount>개</white> 대기 중 — <white>/aug choose</white> 로 안전할 때 선택하세요."
  queued: "<aqua>◆ 새 증강권이 도착했습니다. 현재 선택을 끝내면 다음 증강이 뜹니다. 선택권 <white><amount>개</white> 대기 중."
  pending_actionbar: "<gold>◆ 증강 선택권 <white><amount>개</white> <gray>대기 <dark_gray>| <white>/aug choose"

admin:
  token_given: "<green><player></green> 님에게 선택권 <white><amount></white>개를 지급했습니다. <gray>(보유: <total>)"
  give_success: "<green>증강 <white><id></white> 을(를) <player> 님에게 지급했습니다."
  give_failed: "<red>증강 <id> 지급 실패(이미 최대 중첩이거나 불가)."
  remove_success: "<green>증강 <white><id></white> 을(를) <player> 님에게서 제거했습니다."
  remove_none: "<red>해당 플레이어는 증강 <id> 을(를) 보유하고 있지 않습니다."
  reset_success: "<green><player></green> 님의 증강 데이터를 초기화했습니다."
  reset_all_success: "<green>전체 플레이어 데이터를 초기화했습니다. <gray>(삭제된 저장 파일: <white><count></white>개)"
  reloaded: "<green>설정을 다시 불러왔습니다."

game:
  need_players: "<red>게임을 시작하려면 최소 <white><min></white>명이 필요합니다. <gray>(현재 <count>명)"
  already_running: "<red>이미 게임이 진행 중입니다."
  no_world: "<red>센터 월드를 찾을 수 없습니다. <white>/aug game setcenter</white> 로 설정하세요."
  starting: "<green>게임이 <white><seconds>초</white> 후 시작됩니다! 모두 산개됩니다."
  test_start: "<light_purple>테스트 모드로 시작합니다. <gray>인원과 무관하게 진행되며 최후의 1인이 남아도 종료되지 않습니다. <white>/aug game stop</white> 으로 종료하세요."
  begin: "<green><bold>게임 시작!</bold> <gray>평화시간 <white><grace>초</white> 동안 서로 공격할 수 없습니다."
  pvp_on: "<red><bold>전투 개시!</bold> <gray>이제 서로 공격할 수 있습니다."
  border_shrink: "<gold>⚠ 월드보더가 축소됩니다! <gray>반경 <white><radius></white> 까지 (<white><duration>초</white> 동안)"
  border_final: "<red>◆ 월드보더가 최종 크기에 도달했습니다!"
  deathmatch_start: "<dark_red><bold>☠ 데스매치!</bold> <gray>이제부터 모든 생존자가 <white>지속 피해</white>를 받습니다. 마지막까지 살아남으세요!"
  grant_start: "<aqua>◆ 게임 시작! 모든 생존자에게 증강 카드가 지급되었습니다!"
  grant_time: "<aqua>◆ 모든 생존자에게 증강 카드가 지급되었습니다!"
  grant_kill: "<aqua><white><player></white> 님 <white><kills>킬</white> 달성! 증강 카드를 획득했습니다."
  hider_revealed: "<red>⚠ <white><player></white> 님이 너무 오래 숨어 있습니다! <gray>위치 <white><x>, <y>, <z></white> <dark_gray>(<world>) — 발광 표시됨"
  eliminated: "<gray>☠ <white><victim></white> 님이 탈락했습니다. <dark_gray>(남은 생존자: <white><count></white>명)"
  eliminated_kick: "<red>탈락하셨습니다."
  eliminated_by: "<gray>☠ <white><victim></white> 님이 <red><killer></red> 님에게 처치되었습니다. <dark_gray>(남은 생존자: <white><count></white>명)"
  winner: "<gold><bold>🏆 <winner> 님이 최후의 1인으로 승리했습니다!</bold>"
  draw: "<gray>생존자가 없어 무승부로 종료되었습니다."
  force_end: "<red>관리자가 게임을 강제 종료했습니다."
  ended: "<gray>게임이 종료되었습니다. 모두 야생 모드로 돌아갑니다."
  not_running: "<red>진행 중인 게임이 없습니다."
  skip: "<gold>[스킵] <white><phase></white> 단계를 건너뛰고 다음 단계로 넘어갑니다."
  skip_none: "<red>더 이상 건너뛸 단계가 없습니다. <gray>(이미 최종 구역)"
  center_set: "<green>센터를 <white><x>, <z></white> <gray>(<world>)로 설정했습니다."
  spectator_join: "<gray>진행 중인 게임에 접속하여 <white>관전 모드</white>로 전환됩니다."

error:
  no_permission: "<red>권한이 없습니다."
  players_only: "<red>플레이어만 사용할 수 있는 명령어입니다."
  player_not_found: "<red>플레이어 <player> 을(를) 찾을 수 없습니다(온라인 상태여야 합니다)."
  not_a_number: "<red><value> 은(는) 올바른 숫자가 아닙니다."
  augment_not_found: "<red>증강 ID <id> 을(를) 찾을 수 없습니다."

자세한 내용은 가이드 문서를 읽어주세요.

게임 내 증강 목록과 시너지 효과는 다음 문서들을 통해서 확인하실 수 있습니다.

https://github.com/beenstrong/augmentPvp/blob/main/docs/AUGMENT_LIST.md

https://github.com/beenstrong/augmentPvp/blob/main/docs/SYNERGY_LIST.md