Forage — 채집 상호작용 엔진

지정한 블록을 지정한 도구로 우클릭하면 시전 게이지나 타이밍 미니게임이 뜨고, 성공하면 등급이 붙은 채집물이 나온다.

콘텐츠가 고정된 채집 플러그인이 아니라, 어떤 블록에든 채집 상호작용을 붙일 수 있는 엔진이다. 무엇을 채집물로 삼을지는 전부 설정에서 정한다.

• Minecraft 1.21.4
• 서버 Paper (또는 Paper 계열 포크)
• Java 21

---

채집 방식

방식	조작	등급 판정
CHANNEL	우클릭 후 게이지가 찰 때까지 유지	가중치 무작위 (도구가 승급 확률을 올림)
TIMING	왕복하는 커서를 초록 구간에서 클릭	판정이 곧 등급

CHANNEL   보스바가 차오른다. 움직이거나 시선을 돌리면 취소.

TIMING    [────────═══════◆──────────]
                     ↑ 노란 구간이 완벽 판정

CHANNEL 에 대해 하나 짚어둘 것 마인크래프트는 "우클릭을 누르고 있는 중"이라는 정보를 서버에 보내지 않는다. 그래서 실제로 버튼을 붙잡고 있을 필요는 없고, 한 번 클릭하면 시전이 시작된 뒤 이동·시선·아이템 교체 같은 유지 조건으로 그 감각을 만든다.

TIMING 에서 빗나가면 실패하지만 블록은 소모되지 않는다. 곧바로 다시 시도할 수 있으므로, 정확도가 곧 시간이 되는 구조다.

---

도구를 손에 들고 등록한다

설정 파일에 아이템을 정의하지 않는다. 원하는 아이템을 손에 들고 명령어를 치면 그 순간의 NBT가 통째로 저장된다. 리소스팩 커스텀 모델이든 다른 플러그인이 만든 아이템이든 그대로 채집 도구가 된다.

/채집 tool save sickle          손에 든 아이템을 'sickle' 도구로 등록
/채집 tool give sickle @p 1     발급 (인식용 태그가 함께 박힌다)
/채집 tool match                지금 든 아이템이 뭘로 인식되는지 진단
/채집 tool list / delete <id>

어떻게 "같은 도구"라고 판단하는가

여기가 이 플러그인의 설계 중심이다. 완전 일치로 보면 내구도가 1 닳는 순간 인식되지 않고, 재질만 보면 바닐라 아이템과 구분이 안 된다. 그래서 두 갈래로 간다.

경로	방식
발급 태그	/채집 tool give 로 나간 아이템에는 도구 id 가 박혀 있다. 태그만 읽으면 끝
속성 비교	태그가 없으면 등록된 도구와 속성을 대조한다

속성 비교 기본값은 재질 + 커스텀 모델 데이터 + 표시 이름 이고, 내구도와 인챈트는 보지 않는다. 도구별로 바꿀 수 있으며, save <id> strict 로 등록하면 NBT까지 전부 같아야 인정한다.

인식이 안 될 때는 /채집 tool match 로 바로 진단할 수 있다.

도구 보너스

tools:
  sickle:
    data: "<Base64 스냅샷>"
    bonus:
      speed: 1.3      # CHANNEL 시간 30% 단축 / TIMING 판정 구간 30% 확대
      quality: 0.15   # 상위 등급 승급 확률 +15%p

좋은 도구를 구할 이유가 생긴다.

---

노드 정의

nodes.yml.

nodes:
  crystal_vein:
    display: "<light_purple>수정 광맥"
    blocks: [ AMETHYST_CLUSTER ]
    tools: [ crystal_pick ]      # 비우면 맨손 포함 아무거나
    method: TIMING
    respawn:
      mode: REPLACE              # REMOVE | REPLACE | KEEP
      with: SMOOTH_BASALT        # 캐면 이걸로 바뀌었다가
      after: 300                 # 5분 뒤 원래대로
    drops:
      - { item: AMETHYST_SHARD, min: 2, max: 4, chance: 1.0, quality: true }

같은 블록을 여러 노드가 노려도 된다. 손에 든 도구로 갈라진다 — 풀을 낫으로 베면 약초가 나오고, 특수 낫으로 베면 다른 게 나오게 만들 수 있다. 도구를 요구하는 노드가 먼저 검사되므로, 아무거나 받는 노드가 전용 도구 노드를 가리는 일은 없다.

복구 모드

mode	동작
REMOVE	블록이 사라졌다가 돌아온다
REPLACE	다른 블록으로 바뀌었다가 돌아온다
KEEP	블록은 그대로, 재채집만 막는다 (나무 수액 등)

복구 대기 목록은 주기적으로 파일에 저장되므로 서버를 껐다 켜도 이어진다. 복구할 자리에 누가 뭔가 지어 놨다면 복구를 포기한다 — 남의 건축물을 덮어쓰는 것보다 노드 하나를 잃는 편이 낫다.

---

등급

[하품]  [상품]  [명품]  [전설]

drops 항목에 quality: true 를 준 것만 등급이 붙는다. 씨앗 같은 잡템까지 등급이 붙으면 인벤토리가 지저분해지므로 선별해서 켜는 편이 낫다.

등급이 붙으면 아이템 이름이 달라져 서로 겹쳐 쌓이지 않는다. 이게 의도한 동작이다 — 명품과 하품이 한 칸에 쌓이면 등급이 있을 이유가 없다.

quality.enabled: false 로 통째로 끌 수 있다.

---

취소 조건

config.yml 에서 개별로 켜고 끈다.

조건	기본값
이동	꺼짐
시선이 노드에서 벗어남	켜짐
손에 든 아이템 변경	켜짐
피격	켜짐
노드에서 6칸 이상 이탈	항상

이동 시 취소를 켜면 난이도가 확 올라간다. 서버 성향에 따라 갈리는 부분이라 기본값은 꺼 두었다.

---

땅 보호

채집 직전에 가짜 BlockBreakEvent 를 한 번 흘려 "이 사람이 여기서 블록을 부술 수 있는가" 를 물어본다. WorldGuard 같은 보호 플러그인이 이 물음에 답한다.

구현상 실제 이벤트가 한 번 발생하므로 블록 로그 플러그인이 이를 기록할 수 있다. 그 부작용이 곤란하면 protection.respect-block-protection: false 로 끄면 된다.

---

명령어 / 권한

명령어	권한
/채집 tool save|give|match|list|delete	forage.admin
/채집 node list	forage.admin
/채집 reload	forage.admin

/forage, /gather 로도 쓸 수 있다.

권한	기본값
forage.use	전체 허용 (채집 상호작용)
forage.admin	OP

---

알려진 한계

• 두 칸짜리 식물(키 큰 풀 등)을 REMOVE 로 캐면 위아래 중 클릭한 쪽만 사라진다. 이런 블록은 KEEP 모드를 쓰거나 아랫부분을 대상으로 잡는 편이 낫다.
• 채집 경험치는 현재 바닐라 경험치로 지급된다. 별도 채집 레벨 체계는 아직 없다.

---

빌드

./gradlew build

산출물은 build/libs/Forage-1.0.0.jar.

---

라이선스

MIT