Minecraft 플러그인 PlaceholderAPI

🔌 PlaceholderAPI 소개

PlaceholderAPI는 중앙화된 플레이스홀더 시스템과 확장 생태계(eCloud)를 제공하는 Minecraft 플러그인입니다. 이를 통해 다른 플러그인들은 직접 연동이나 강한 의존성 없이도 수천 개의 동적 플레이스홀더(플레이어 데이터, 경제 값, 플러그인별 값 등)를 읽고 치환할 수 있습니다.

🎯 목적

이 플러그인은 하나의 확장 가능한 플레이스홀더 API를 제공해 플러그인 간 연동의 번거로움을 줄여 줍니다. 플러그인 제작자는 이름이 있는 플레이스홀더를 제공하는 확장을 공개하고, 서버 관리자는 이를 설치해 서버용 플러그인(scoreboards, chat, holograms, GUIs)이 일관된 문법으로 실시간 데이터를 표시할 수 있게 합니다.

⚙️ 기능

• 다른 플러그인이 연동할 수 있는 핵심 플레이스홀더 파싱 API.
• 확장 시스템: 개별 패키지로 배포되는 확장 또는 플러그인에 포함된 확장.
• 게임 내에서 검증된 확장을 찾고 다운로드할 수 있는 eCloud(확장 클라우드).
• 실행 중 확장을 목록화, 등록, 등록 해제, 다시 불러오기 위한 관리 명령어.
• 한 플레이어를 대상으로 플레이스홀더를 평가하거나 결과를 전체에 브로드캐스트하는 디버그/파싱 명령어로, 문제 해결에 유용합니다.
• 지원 요청 시 설치된 확장과 플러그인 상태를 공유할 수 있는 dump 명령어 같은 유틸리티.

🧩 대상

• 여러 플러그인에 걸쳐 통합된 동적 텍스트가 필요한 서버 관리자(scoreboards, tablists, holograms, GUIs).
• 강한 의존성을 강요하지 않고 플레이스홀더를 노출하거나 사용하고 싶은 플러그인 개발자.
• 많은 플러그인을 함께 사용하며 일관된 플레이스홀더 문법이 필요한 Survival, 미니게임, 네트워크 서버.

🏗️ 사용 예시

• 서버에 Vault 확장을 설치해 플레이어 잔액 같은 경제 플레이스홀더를 scoreboard와 chat 플러그인에서 사용할 수 있게 합니다.
• 관리자가 eCloud에서 플러그인 전용 확장을 다운로드해 hologram 플러그인이 실시간 목표 데이터를 표시할 수 있게 합니다.
• 개발자가 PlaceholderExpansion을 통해 플러그인 데이터를 노출해, 다른 서버가 해당 플러그인에 직접 의존하지 않고도 그 데이터를 표시할 수 있게 합니다.

⌨️ 명령어

(참고: 위 명령어들은 공식 PlaceholderAPI 명령어 참조에 문서화되어 있습니다. 개별 명령어의 권한 노드는 참조된 명령어 문서에 나와 있지 않습니다.)

⚙️ 설치

📥 설정

• 공식 PlaceholderAPI jar를 다운로드해 서버의 plugins/ 디렉터리에 넣습니다.
• 서버를 시작하거나 재시작한 뒤 콘솔에서 PlaceholderAPI가 로드되었는지 확인합니다.
• 확장은 plugins/PlaceholderAPI/expansions/에 확장 jar를 넣거나, 게임 내 eCloud 명령어를 사용해 설치합니다(검증된 확장용).

📦 의존성

• PlaceholderAPI 자체는 작동에 일반적인 플러그인 의존성이 필요하지 않습니다. 확장이 제공하는 일부 플레이스홀더는 다른 플러그인에 의존합니다(예: 경제 값을 보여주는 확장은 해당 경제 플러그인이 필요합니다). 이러한 요구 사항은 확장마다 다릅니다.

🧠 기술 노트

• PlaceholderAPI는 Spigot 기반 서버용으로 제공되며 Paper에서도 널리 사용됩니다. 플러그인 개발자가 PlaceholderExpansions를 등록할 수 있는 API를 제공합니다.
• 확장은 독립적인 jar 파일로 배포되거나 다른 플러그인에 포함될 수 있으며, 독립 확장은 보통 plugins/PlaceholderAPI/expansions/에 설치합니다.
• eCloud 기능을 사용하면 게임 내에서 검증된 확장을 찾아 다운로드할 수 있습니다. eCloud 다운로드가 작동하려면 서버에서 아웃바운드 HTTPS를 허용해야 합니다.
• 이 플러그인에는 관리자가 플레이스홀더가 올바르게 해석되는지 확인할 수 있도록 도와주는 디버그 및 파싱 명령어가 포함되어 있습니다.

🤝 이 플러그인이 유용한 경우

서버에서 동적이고 플러그인 간 데이터를 표시해야 하는 여러 플러그인(chat, tab, holograms, scoreboards, GUIs)을 사용한다면, PlaceholderAPI는 플레이스홀더 해석을 중앙화하고 각 소비자 플러그인을 수정하지 않고도 모듈형 확장을 통해 추가 플러그인 지원을 더할 수 있게 해 주기 때문에 유용합니다.