Vault

Vault는 버킷 계열 마인크래프트 서버에서 경제, 권한, 채팅 서비스를 공통된 방식으로 연결하는 추상화 라이브러리이자 플러그인이다.^[1] 서비스를 제공하는 플러그인과 이를 이용하는 플러그인 사이에 공통 API를 두어, 서로 다른 구현을 직접 처리해야 하는 부담을 줄인다.

**Vault**
최신 버전	1.7.3
지원 MC	배포 페이지의 각 릴리스 안내를 확인
Java	서버 코어와 동일
서버 코어	Bukkit, Spigot, Paper 계열
선행 플러그인	없음 (단, 서비스 제공자 플러그인이 별도로 필요)
확인일	2026-08-06

역할

Vault 자체는 화폐를 만들거나 플레이어 권한을 저장하지 않는다. 실제 경제·권한·채팅 기능은 별도의 제공자 플러그인이 담당하고 Vault는 등록된 제공자를 다른 플러그인에 전달한다.^[1] 따라서 Vault만 설치하면 잔액이나 권한 기능이 생기는 것이 아니며, 이용하려는 서비스에 맞는 제공자 플러그인이 함께 필요하다.

경제 API에는 잔액 조회, 입금, 출금과 같은 공통 동작이 있고, 권한 API에는 권한 확인과 기본 그룹 조회 같은 동작이 있다.^[2] 구체적인 화폐 단위, 소수점 처리, 그룹 기능은 연결된 제공자에 따라 달라질 수 있다.

설치와 확인

서버 관리자는 다음 순서로 구성한다.

서버 구현과 마인크래프트 판에 맞는 Vault.jar를 plugins 폴더에 넣는다.
경제·권한·채팅 가운데 필요한 서비스를 제공하는 플러그인을 설치한다.
Vault를 이용하는 상점, 채팅, 보상 등의 플러그인을 설치하고 서버를 다시 시작한다.
서버 로그에서 Vault와 서비스 제공자, 이용 플러그인이 정상적으로 연결되었는지 확인한다.

Vault를 지원하는 플러그인은 대개 서버가 시작될 때 등록된 서비스를 자동으로 찾는다.^[3] 의존 플러그인이 Vault를 찾지 못했다면 JAR 존재 여부뿐 아니라 실제 서비스 제공자가 설치되어 시작 시점에 등록되었는지도 확인해야 한다.

Vault 프로젝트는 새 커넥터를 중앙 저장소에 추가하지 않으며, 각 서비스 구현이 자체 커넥터를 제공하는 방식을 사용한다.^[1] 특정 경제·권한 플러그인의 Vault 연동 여부는 해당 플러그인의 현재 기능에 따라 결정된다.

개발자 API

플러그인 개발자는 VaultAPI를 Maven의 provided 또는 Gradle의 compileOnly 의존성으로 추가하고, 런타임에는 서버에 설치된 Vault를 사용한다.^[2] plugin.yml의 depend 또는 softdepend 선택은 Vault 없이는 플러그인이 동작할 수 있는지에 따라 정한다.

경제 제공자를 얻는 기본 흐름은 다음과 같다.

RegisteredServiceProvider<Economy> registration =
    getServer().getServicesManager().getRegistration(Economy.class);
if (registration != null) {
    Economy economy = registration.getProvider();
}

Economy 대신 Permission이나 Chat 서비스를 같은 방식으로 조회할 수 있다.^[2] 제공자가 등록되지 않았을 수 있으므로 조회 결과가 null인 경우를 처리해야 하며, 경제 작업은 반환되는 EconomyResponse의 성공 여부도 확인해야 한다.

구성 예시

Vault는 연결 계층이므로 항상 제공자 + 이용자와 함께 구성한다.

역할	예	설명
연결 계층	Vault	이것만으로는 아무 기능도 생기지 않는다
권한 제공자	LuckPerms	권한과 그룹을 실제로 저장한다
경제 제공자	EssentialsX 등	잔액을 실제로 저장한다
이용 플러그인	상점, 보상, 채팅 플러그인	Vault를 통해 위 기능을 사용한다

서버 시작 로그에서 연결 상태를 확인할 수 있다. 제공자가 등록되면 Vault가 어떤 플러그인을 경제·권한·채팅 제공자로 인식했는지 기록한다.

자주 나는 오류

증상	원인	해결
`Vault not found`	Vault 미설치 또는 적재 실패	Missing dependency 문서를 참고해 적재 여부부터 확인한다
잔액 관련 기능이 동작하지 않음	경제 제공자가 없음	Vault만 설치한 상태다. 경제 플러그인을 함께 설치한다
권한 관련 기능이 동작하지 않음	권한 제공자가 없음	LuckPerms 등을 설치한다
제공자가 등록되지 않음	제공자 플러그인이 Vault보다 먼저 적재되지 못함	`/reload` 대신 서버를 완전히 재시작한다
개발 중 조회 결과가 `null`	서비스가 아직 등록되지 않음	플러그인 활성화 시점이 아니라 이후 시점에 조회하거나 `null` 처리를 둔다

Vault를 설치했는데 기능이 없다는 문의가 가장 흔하다. Vault는 기능을 제공하지 않고 연결만 하므로, 제공자 플러그인이 반드시 함께 있어야 한다.

같이 보기

각주

↑ ^1.0 ^1.1 ^1.2 MilkBowl/Vault, GitHub. 2026년 8월 5일 확인.
↑ ^2.0 ^2.1 ^2.2 MilkBowl/VaultAPI, GitHub. 2026년 8월 5일 확인.
↑ Vault, SpigotMC. 2026년 8월 5일 확인.

[vault-repo-1] 1.0 ^1.1 ^1.2 MilkBowl/Vault, GitHub. 2026년 8월 5일 확인.

[vault-api-2] 2.0 ^2.1 ^2.2 MilkBowl/VaultAPI, GitHub. 2026년 8월 5일 확인.

[3] Vault, SpigotMC. 2026년 8월 5일 확인.

[1]

[2]

[3]