NBT-API

NBT-API 소개

NBT-API는 플러그인 개발자가 아이템, 타일(블록 엔티티), 엔티티에 커스텀 NBT 태그를 쉽게 추가하고 수정할 수 있게 해 주는 라이브러리 플러그인입니다. NBT는 마인크래프트가 아이템의 이름·인챈트·내구도, 상자 안의 내용물, 몹의 상태 같은 세부 데이터를 저장하는 형식입니다. 원래 Bukkit 계열 서버에서 이 데이터를 직접 다루려면 버전마다 달라지는 서버 내부 코드(NMS)를 건드려야 했는데, NBT-API는 그 과정을 감싸 주어 NMS 없이도 NBT를 다룰 수 있게 해 줍니다.

수정한 NBT는 파일이나 다른 NBT에 저장할 수 있고, 문자열 형태로 바꿔 yaml·json·SQL·Redis 같은 저장소에 보관할 수도 있습니다. 예를 들어 특별한 아이템의 정보를 데이터베이스에 저장했다가 다시 불러오는 기능을 만들 때 유용합니다.

일반 서버 운영자 입장에서 NBT-API는 직접 쓰는 기능이 있는 플러그인이라기보다, 다른 플러그인이 동작하기 위해 함께 설치하는 "기반 부품"에 가깝습니다. 설치하려는 플러그인이 NBT-API를 필요로 한다고 안내하면 이 플러그인을 함께 넣어 주면 됩니다.

NBT-API 정보

항목	내용
종류	마인크래프트 플러그인 (개발용 라이브러리)
제작자	tr7zw
지원 버전	1.7.9 ~ 26.3
지원 플랫폼	Bukkit, Folia, Paper, Purpur, Spigot
카테고리	라이브러리
다운로드	약 34만 회
최초 공개	2022-08-21
최근 업데이트	2026-09-17
라이선스	MIT
배포처	Modrinth

주요 특징

• NMS 없는 NBT 접근 - 서버 내부 코드를 직접 쓰지 않고 NBT를 읽고 씁니다.
• 세 가지 대상 지원 - 아이템, 블록 엔티티(타일), 엔티티의 NBT를 다룰 수 있습니다.
• 다양한 저장 방식 - 파일, 다른 NBT, 문자열로 저장해 yaml·json·SQL·Redis에 보관할 수 있습니다.
• 넓은 버전 범위 - 1.7.9부터 26.3까지 폭넓은 버전을 지원합니다.
• 개발 자료 제공 - Maven으로 불러와 기본 사용법과 머리(스컬) 다루기 같은 예제를 참고할 수 있습니다.

서버 설정과 사용 방법

서버 운영자라면 할 일은 간단합니다. NBT-API를 필요로 하는 플러그인을 설치할 때, 서버 버전에 맞는 NBT-API 파일을 plugins 폴더에 함께 넣으면 됩니다. 별도로 조작하는 명령어나 화면이 있는 플러그인이 아니므로, 설치 후 서버가 정상적으로 켜지고 의존하는 플러그인이 오류 없이 로드되는지 확인하는 것으로 충분합니다.

개발자라면 Maven으로 API를 가져온 뒤 기본 사용법 문서와 코드 예제를 참고해 시작할 수 있습니다. 서버 운영자용·개발자용 위키가 따로 정리되어 있으므로, 플러그인에 NBT-API를 포함시킬지(shade) 의존성으로 요구할지 같은 결정도 문서에서 확인하는 것이 좋습니다. 이 플러그인은 bStats로 익명 통계를 수집합니다.

라이브러리 플러그인을 관리하는 요령

라이브러리 플러그인은 눈에 띄는 기능이 없어 업데이트를 잊기 쉽습니다. 하지만 일반적으로 마인크래프트 버전이 올라갈 때 가장 먼저 업데이트가 필요한 것이 이런 기반 플러그인입니다. 서버 버전을 올릴 계획이라면 NBT-API가 새 버전을 지원하는지 먼저 확인하고, 이 라이브러리에 의존하는 플러그인들도 함께 점검하세요. 하나의 라이브러리를 여러 플러그인이 공유하는 구조이므로, 서로 다른 버전의 같은 라이브러리를 중복으로 넣지 않도록 주의하는 것도 중요합니다.

서버가 켜질 때 "NBT-API를 찾을 수 없다"는 식의 오류가 보인다면 대부분 파일이 누락되었거나 버전이 맞지 않는 경우입니다. 로그에서 어떤 플러그인이 의존성을 요구했는지 확인하면 원인을 빠르게 찾을 수 있습니다.

이런 분께 추천합니다

NBT-API는 직접 찾아 설치하기보다 다른 플러그인의 요구로 만나게 되는 경우가 많습니다. 그만큼 서버 운영자와 개발자 모두에게 한 번쯤은 필요한 라이브러리입니다. 특히 아래와 같은 경우라면 설치를 고려해 보세요.

• 설치하려는 플러그인이 NBT-API를 필수로 요구하는 서버 운영자
• 아이템에 커스텀 데이터를 붙이는 플러그인을 만드는 개발자
• 여러 버전을 지원하는 플러그인을 NMS 없이 개발하고 싶은 분
• NBT 데이터를 데이터베이스에 저장·불러오는 기능이 필요한 분

다운로드 및 설치 방법

1. Paper·Spigot·Purpur·Bukkit·Folia 중 하나로 서버를 준비합니다.
2. 페이지의 Modrinth에서 다운로드 버튼으로 이동해 서버 버전에 맞는 NBT-API 파일을 받습니다.
3. .jar 파일을 서버의 plugins 폴더에 넣습니다.
4. 서버를 재시작하고 의존하는 플러그인이 정상적으로 로드되는지 로그로 확인합니다.

플러그인은 서버 전용입니다. 단독으로 설치해도 게임 안에서 눈에 보이는 변화는 거의 없으며, 이를 사용하는 다른 플러그인과 함께 의미가 생깁니다.

자주 묻는 질문

NBT-API만 설치하면 무엇이 달라지나요?

단독으로는 눈에 띄는 기능이 없습니다. 이 라이브러리를 사용하는 플러그인이 동작하도록 돕는 역할입니다.

어떤 버전을 받아야 하나요?

서버의 마인크래프트 버전에 맞는 파일을 받아야 합니다. 지원 범위는 1.7.9부터 26.3까지입니다.

Folia 서버에서도 쓸 수 있나요?

네. 지원 플랫폼 목록에 Folia가 포함되어 있습니다.

개발에 사용하려면 어떻게 시작하나요?

Maven으로 API를 가져온 뒤 기본 사용법과 코드 예제 문서를 참고하면 됩니다.

NMS를 쓰지 않으면 어떤 점이 좋은가요?

일반적으로 NMS 코드는 마인크래프트 버전마다 바뀌어 업데이트 때마다 수정이 필요합니다. NBT-API를 거치면 이런 버전 차이를 라이브러리가 흡수해 주므로 유지 보수 부담이 줄어듭니다.

마무리

NBT-API는 눈에 잘 띄지 않지만 많은 플러그인을 떠받치는 중요한 라이브러리입니다. 개발자에게는 NMS 없이 NBT를 다루는 편리한 도구가 되고, 운영자에게는 의존 플러그인을 돌리기 위한 필수 부품이 됩니다. 서버 버전에 맞는 파일을 설치해 두고 업데이트도 잊지 마세요.