플레이어 거래소 (고정 가격 즉시 구매) 플러그인 — 서버 관리자 설명서
플레이어가 손에 든 아이템을 고정 가격으로 등록하면, 다른 플레이어가 GUI에서 즉시 구매(buyout)할 수 있는 전역 거래소를 제공합니다. 입찰식 경매가 아닌 고정 가격 즉시 구매 방식입니다.
| 항목 | 내용 |
|---|---|
| 서버 | Spigot / Paper 1.20.1 ~ 1.21.x |
| 자바 | Java 17 이상 권장 |
| 필수 플러그인 | DPP-Core 5.4.0 이상 |
| 경제 플러그인 | EssentialsX 또는 Vault (둘 중 하나) |
거래 화폐는 DPP-Core의
MoneyAPI를 통해 처리됩니다. EssentialsX 또는 Vault 중 코어가 자동으로 감지·선택하므로plugin.yml에 별도로 명시할 필요가 없습니다.
⚠️ 경제 플러그인이 없으면 판매 등록·구매·수익 수령이 동작하지 않습니다 (안내 메시지 출력).
DPP-Core플러그인을 먼저plugins/폴더에 설치합니다.- 경제 플러그인(EssentialsX 또는 Vault + 경제 구현체)을 설치합니다.
DP-PlayerMarket-1.0.0-SNAPSHOT.jar를plugins/폴더에 넣습니다.- 서버를 재시작합니다.
plugins/DP-PlayerMarket/config.yml이 생성되면 원하는 값으로 수정 후/market reload또는 서버 재시작으로 적용합니다.
판매자: 팔 아이템을 손에 들고 → /market sell 1000 → 카테고리 선택 → 등록 완료
구매자: /market → 카테고리/검색/정렬로 탐색 → 아이템 클릭 → 구매 확인 → 확정
정산: 판매가에서 수수료(판매자 부담) 차감 후 판매자 회수함에 수익 적립
수령: /market claim → 회수함에서 수익(돈) + 구매/반환 아이템 수령
| 명령어 | 설명 | 권한 |
|---|---|---|
/market |
거래소 GUI 열기 | dpmarket.use |
/market sell <가격> |
손에 든 아이템 판매 등록 (→ 카테고리 선택) | dpmarket.use |
/market search <키워드> |
아이템 검색 | dpmarket.use |
/market claim |
회수함 열기 (수익 + 아이템 수령) | dpmarket.use |
/market remove |
내 매물 관리/회수 GUI | dpmarket.use |
/market filter |
(관리자) 아이템 등록 차단 필터 관리 GUI | dpmarket.admin |
/market reload |
설정 재로드 | dpmarket.admin |
별칭(aliases): /market = /pm = /dpmarket
| 권한 | 기본값 | 설명 |
|---|---|---|
dpmarket.use |
true (모두) |
거래소 기본 사용 |
dpmarket.admin |
op |
관리자 기능 (reload, filter) |
dpmarket.slot.<숫자> |
없음 | 판매 슬롯 <숫자>개 부여 (예: dpmarket.slot.15) |
dpmarket.slot.unlimited |
false |
무제한 판매 슬롯 |
- 플레이어가 동시에 등록할 수 있는 매물 수는 권한으로 결정됩니다.
dpmarket.slot.<n>을 여러 개 보유하면 가장 큰 숫자가 적용됩니다.dpmarket.slot.unlimited보유 시 무제한입니다.- 슬롯 권한이 전혀 없으면 config의
Market.default-slots값이 적용됩니다. - 슬롯은 매물 등록 시 점유되고, 판매 · 회수 · 만료 시 즉시 해제됩니다.
권한 그룹 플러그인(LuckPerms 등)에서 그룹별로
dpmarket.slot.30같은 권한을 부여해 등급제 슬롯을 운영할 수 있습니다.
Settings:
prefix: "&f[ &eDP-PlayerMarket &f] " # 메시지 접두사 (색상코드 & 지원)
Lang: en_US # 언어 (en_US / ko_KR)
Market:
tax: 5 # 판매자 부담 수수료 (%)
default-slots: 5 # 슬롯 권한이 없을 때 기본 판매 슬롯 수
listing-expire-days: 7 # 매물 만료일 (0 = 만료 없음)
min-price: 1 # 최소 등록 가격
max-price: 0 # 최대 등록 가격 (0 = 무제한)
expire-check-period-minutes: 60 # 만료 검사 주기 (분)
categories: # 판매자가 등록 시 고르는 카테고리 목록
- 무기
- 방어구
- 도구
- 블록
- 재료
- 기타| 키 | 설명 |
|---|---|
Settings.prefix |
모든 메시지 앞에 붙는 접두사. & 색상코드 사용 가능 |
Settings.Lang |
사용 언어. lang/ 폴더의 파일명과 일치 (en_US, ko_KR) |
Market.tax |
판매자가 부담하는 수수료(%). 구매자는 표시 가격 그대로 지불하고, 판매자는 수수료를 뺀 금액을 수령 |
Market.default-slots |
슬롯 권한이 없는 플레이어의 기본 판매 슬롯 수 |
Market.listing-expire-days |
매물 자동 만료 기간(일). 0이면 만료되지 않음 |
Market.min-price / max-price |
등록 가능한 가격 범위. max-price가 0이면 상한 없음 |
Market.expire-check-period-minutes |
만료 검사 스케줄러 실행 주기(분). 서버 활성화 시 1회 + 주기적으로 실행 |
Market.categories |
거래소 카테고리 목록. 자유롭게 추가/수정 가능 (한글·영문 모두 가능) |
⚠️ 카테고리 변경 주의: 이미 등록된 매물의 카테고리명을 config에서 삭제/변경하면, 해당 매물은 카테고리 필터에서 보이지 않을 수 있습니다(전체 보기에서는 계속 노출). 운영 중에는 카테고리 추가만 권장합니다.
설정 변경 후 /market reload 로 즉시 반영됩니다.
/market sell <가격> — 손에 든 아이템(스택 전체)을 등록합니다.
- 가격이
min-price~max-price범위를 벗어나면 거부됩니다. - 남은 슬롯이 없으면 거부됩니다.
- 카테고리 선택 GUI에서 예상 수수료와 실수령액을 미리 확인할 수 있습니다.
- 카테고리를 클릭하면 등록이 확정되고, 손에 든 아이템이 회수되며 슬롯이 점유됩니다.
/market — 전역 거래소 GUI. 하단 도구 줄에서 다음을 제어합니다.
| 버튼 | 기능 |
|---|---|
| 🪣 카테고리 | 클릭할 때마다 카테고리 필터 순환 (전체 → 무기 → … → 전체) |
| ⚙ 정렬 | 정렬 기준 순환 (최신순 → 가격순 → 판매량순) |
| 🪧 검색 | 채팅 입력으로 키워드 검색 시작 |
| 📦 회수함 | 회수함 바로 열기 |
| ◀ ▶ | 페이지 이동 |
- 정렬 기준
- 최신순: 최근 등록된 매물 우선
- 가격순: 저렴한 매물 우선
- 판매량순: 해당 아이템 종류(Material)의 누적 판매량이 많은 순
- 매물 아이템을 클릭하면 구매 확인 GUI가 열립니다.
/market search <키워드>명령으로 검색하거나, 거래소 GUI의 검색 버튼을 눌러 채팅으로 키워드를 입력할 수 있습니다.- 채팅 검색 중
cancel을 입력하면 취소됩니다. - 아이템 표시 이름, 아이템 종류, 카테고리명을 대상으로 검색합니다.
매물 클릭 → 구매 확인 GUI(아이템 정보 + 가격) → [확인] / [취소]
- 오클릭으로 인한 고가 아이템 오구매를 막기 위한 확인 절차입니다.
- 구매 직전 재검증: 이미 팔렸거나 회수된 매물이면 실패 처리합니다(동시 구매 경합 방지).
- 잔액이 부족하면 거부됩니다.
- 구매한 아이템은 인벤토리로 바로 들어오지 않고 회수함으로 이동됩니다.
/market claim으로 수령하세요.
/market claim — 한 곳에서 수익과 아이템을 수령합니다.
- 💰 수익(돈): 가운데 버튼 클릭 시 일괄 수령 (오프라인 중 적립된 수익도 접속 후 수령).
- 📦 아이템: 클릭하여 인벤토리로 회수. 인벤토리에 충분한 빈 공간이 없으면 회수되지 않고 안내 메시지가 출력됩니다(분할 회수 방지).
회수함에 아이템이 쌓이는 경우:
- 구매한 아이템 (항상 회수함 경유)
- 매물 만료 시 반환된 아이템
- 판매 취소 시 인벤토리가 가득 차 회수하지 못한 아이템
/market remove — 내 매물 목록 GUI에서 클릭하여 회수합니다.
- 회수 시 인벤토리 공간이 없으면 회수함으로 이동됩니다.
Market.listing-expire-days기간이 지난 매물은 자동으로 판매자 회수함으로 이동하고 슬롯이 즉시 해제됩니다.- 검사 시점: 서버 활성화 시 1회 +
expire-check-period-minutes주기. listing-expire-days: 0이면 만료되지 않습니다.
- 구매자는 표시 가격 그대로 지불합니다.
- 판매자는
tax(%)를 뺀 실수령액을 회수함 수익으로 받습니다. - 예: 판매가
1000,tax: 5→ 판매자 실수령950.
특정 아이템을 플레이어가 거래소에 등록하지 못하도록 막는 관리자 기능입니다.
/market filter(권한dpmarket.admin) → 필터 관리 GUI가 열립니다.- 하단의
아이템 추가버튼 클릭 → 편집 가능한 등록 창이 열립니다. - 차단할 아이템을 창에 직접 넣고 인벤토리를 닫으면 등록됩니다.
- 넣은 원본 아이템은 그대로 돌려받습니다(템플릿으로 복제 저장).
- 등록된 아이템의 기본 매칭 옵션은 모두 일치입니다.
- 관리 GUI에서 등록된 아이템을 클릭해 옵션을 편집합니다.
- 좌클릭: 매칭 옵션 순환 변경
- 우클릭: 해당 필터 삭제
| 옵션 | 차단 기준 |
|---|---|
| 모두 일치 | 아이템 종류 + 이름 + 로어 + 인챈트 등 메타까지 완전히 동일한 아이템만 차단 |
| 이름 일치 | 표시 이름이 동일한 아이템 차단 |
| 로어 일치 | 로어(설명) 목록이 동일한 아이템 차단 |
| 타입 일치 | 아이템 종류(Material)만 같으면 차단 → 해당 종류 전체 차단 |
예) 다이아몬드 검 전체를 막고 싶으면 다이아몬드 검을 등록한 뒤 옵션을 타입 일치로 설정합니다. 특정 이름의 전용 아이템만 막고 싶으면 이름 일치 또는 모두 일치를 사용합니다.
- 필터에 걸리는 아이템은
/market sell시 등록이 거부됩니다(등록 확정 시점에도 재검증). - 이미 등록된 매물에는 소급 적용되지 않습니다.
단일 서버, 파일 기반(useDB = false)으로 저장됩니다.
plugins/DP-PlayerMarket/
├── config.yml # 설정
├── stats.yml # 아이템 종류별 누적 판매량 (판매량순 정렬용)
├── lang/
│ ├── en_US.yml # 영어 메시지
│ └── ko_KR.yml # 한국어 메시지
└── data/
├── listings/ # 매물 (매물 ID별 .yml)
├── claims/ # 회수함 (플레이어 UUID별 .yml)
└── filters/ # 등록 차단 필터 (필터 ID별 .yml)
데이터는 서버 종료 시 저장됩니다. 운영 중 파일을 직접 편집한 경우
/market reload로는 매물/회수함/필터 데이터가 다시 로드되지 않으니 서버 재시작을 권장합니다(reload는 config 재로드 용도).
Settings.Lang값을en_US또는ko_KR로 변경한 뒤/market reload합니다.lang/폴더의 yml을 편집해 메시지 문구를 자유롭게 수정할 수 있습니다(&색상코드 지원).- 새 언어를 추가하려면
lang/<코드>.yml파일을 만들고Settings.Lang을 해당 코드로 지정합니다.
Q. 구매했는데 아이템이 인벤토리에 없습니다.
구매 아이템은 항상 회수함으로 들어갑니다. /market claim 에서 수령하세요.
Q. 회수함에서 아이템 클릭이 안 됩니다 / 회수가 안 됩니다. 인벤토리에 빈 공간이 부족하면 회수되지 않습니다. 공간을 비우고 다시 시도하세요.
Q. 판매 등록이 "등록할 수 없는 아이템"이라며 거부됩니다.
관리자가 /market filter 로 해당 아이템을 차단 필터에 등록한 경우입니다.
Q. 슬롯이 부족하다고 나옵니다.
현재 등록 중인 매물 수가 권한 슬롯 한도에 도달한 것입니다. 매물을 판매/회수하거나 더 높은 dpmarket.slot.<n> 권한을 부여하세요.
Q. 가격에 소수점을 넣을 수 있나요? 네. 가격은 소수(double)로 처리됩니다. 표시는 천 단위 구분 + 소수점 둘째 자리까지 포맷됩니다.
Q. 수수료는 어디로 가나요? 수수료는 판매자 수익에서 차감되어 **소멸(sink)**됩니다. 별도 재분배는 하지 않습니다.
- 제작: DEAD_POOLIO_
- 의존 라이브러리: DPP-Core (
com.darksoldier1404.dppc)