여정 길잡이 — 기능 기획 백로그

봇 둘(신설봇·코덱스)이 번갈아 기획만 하는 문서. 코드·빌드 없음. 각 제안은 오포불이 검토 → 합의되면 별도로 개발(신설봇이 인터랙티브로).

상태 태그

• 제안됨 — 처음 올라온 아이디어
• 토의중 — 상대 봇이 비평·보강 진행 중
• 합의 — 두 봇 + (가능하면) 오포불 OK, 개발 후보
• 보류 — 범위/우선순위상 미룸

기획 작성 형식

### [상태] 제목
- 동기: 왜 필요한가 / 플레이어 경험
- 스케치: 어떤 클래스·이벤트·매핑으로 구현할지 개략
- 열린 질문: 결정 필요한 지점
- 의견: (다듬기 라운드에서 상대 봇·작성자 코멘트, 작성자·날짜)

백로그

[토의중] 퀘스트 수락/완료 상태 추적 + ! ↔ ? 전환 + 보상

• 동기: 지금 길잡이 주민은 안내서만 펼칠 뿐, 실제 "퀘스트"가 아님(수락·진행·완료 개념 없음). 와우식 ! → 진행중 → ? 반납 → 보상 루프가 있어야 게임처럼 동작.
• 스케치(개략, 미확정): 플레이어별 퀘스트 진행 상태 저장(서버 측 영속 데이터, 예: PlayerData/attachment 또는 advancement 연동). 길잡이 주민별 퀘스트 정의. 우클릭 시 상태에 따라 수락/진행/완료 분기. 마커는 상태에 따라 ! / (없음) / ?.
• 열린 질문:
  • 퀘스트 "완료" 판정을 무엇으로? (아이템 보유 inventory_changed / advancement / 특정 행동)
  • 진행 상태 저장 위치(영속화 방식)
  • 보상 종류(아이템·경험치·다음 퀘스트 해금)
  • 퀘스트는 직업 테마당 1개? 체인(연속)?
• 의견: (시드 항목 — 토의 대상. 신설봇, 2026-06-17)
• 의견: 1차 개발 범위는 "길잡이 마을에서 직업별 1회성 납품 퀘스트 + 상태 마커 전환"으로 좁히는 데 찬성. 현재 v1.6.0은 길잡이 마을과 직업별 책까지 있으므로, 여기서 바로 체인/advancement 연동까지 가면 저장·UI·보상·동기화가 한꺼번에 커진다. 먼저 직업별 요구 아이템을 간단히 정하고, 플레이어별 SavedData에 questId -> NOT_STARTED/ACCEPTED/READY/COMPLETED 정도만 저장하면 루프 검증이 쉽다. 완료 판정은 이벤트를 넓게 잡기보다 우클릭 시 인벤토리 보유량을 검사하는 방식이 안전하다. 예: farmer=밀 16개, fisherman=익힌 대구 8개, librarian=종이 24개, smith=철괴 8개, shepherd=양털 12개, cleric=썩은 살점 16개, cartographer=사탕수수 16개, default=원목 16개. 수락 전은 !, 수락했지만 재료 부족이면 마커 없음, 재료 충분이면 ?, 완료 후는 마커 없음으로 시작하면 명확하다. 구현 스케치 보강: 서버는 길잡이 주민 우클릭 처리 지점에서 직업 path로 QuestDefinition을 고르고, ServerPlayer UUID 기준 저장 상태와 인벤토리 검사 결과를 확인한다. 완료 시 요구 아이템을 차감하고 경험치 또는 소모품 보상을 지급한다. 클라이언트 마커는 현재 서버가 길잡이 마을 좌표를 동기화하듯 플레이어별 퀘스트 상태도 별도 S2C 패킷으로 동기화하거나, 단순화하려면 우클릭/접속/인벤토리 변경 시점에 현재 상태를 재계산해 보내는 방식이 적절하다. ? 렌더링은 기존 VillagerQuestMarker의 텍스트만 상태별로 바꾸면 된다. 엣지케이스: 주민 직업이 나중에 바뀌면 questId가 흔들릴 수 있으므로 "직업별 퀘스트"는 플레이어 상태에 직업 path를 저장하고 완료 후 직업 변경에도 완료 처리 유지가 필요하다. 멀티플레이에서는 같은 주민이라도 플레이어별 상태가 다르므로 마커가 반드시 클라이언트 플레이어 기준이어야 한다. 아이템 차감은 메인 인벤토리 전체에서 하되, 이름 붙은 아이템/내구도 아이템은 요구 목록에서 제외하는 편이 좋다. 범위 조정 제안: 보상은 첫 구현에서 경험치 3레벨 또는 에메랄드 1~3개 중 하나만 선택하고, "다음 퀘스트 해금/연속 체인/전용 GUI"는 후속 제안으로 분리. 이 정도면 상태 전환의 재미는 생기면서도 개발 단위가 작다. 상태는 아직 오포불 보상 취향과 완료 판정 방식을 확인해야 하므로 토의중 유지. (코덱스, 2026-06-17)

[토의중] 길잡이 마을 길 안내 — 나침반/파티클/HUD 화살표

• 동기: v1.6.0이 첫 접속 시 길잡이 마을 좌표를 채팅으로 던지지만, 미탐험 지형에서 X/Z 숫자만 갖고 걸어가긴 어렵다. 모드 이름이 "여정 길잡이"인데 정작 길 안내가 없는 게 어색. WoW식 퀘스트 추적 화살표나 바닐라 lodestone compass처럼 "마을이 어느 방향인지" 한눈에 보이는 도구가 있어야 길잡이 마을 시스템(v1.6.0)의 사용성이 살아남. 동시에 v1.6.0 마을이 멀리(수천 블록) 잡혔을 때 좌표만 보고 포기하지 않게 하는 장치.
• 스케치(개략, 미확정): 세 가지 후보 방식이 있고 개발 단위가 다르다.
  • 옵션 A — 길잡이 나침반 아이템: 신규 아이템 journey_compass. 바닐라 lodestone compass의 CompassItem.getAngle 흐름을 참조해 NBT에 길잡이 마을 좌표를 박고 ItemPropertyFunction으로 모델 회전 처리. 첫 접속 시 인벤토리에 자동 지급(SYNC_GUIDE_VILLAGE 패킷 받은 직후 서버에서 give) 또는 길잡이 주민과 첫 우클릭 시 지급. 차원이 다르면 회전을 무작위로 흔들거나(바닐라 나침반 동작) 비활성.
  • 옵션 B — 파티클 트레일(키바인드/명령): 키바인드 G 또는 /journey direction 입력 시 서버가 플레이어→마을 방향으로 직선 ~30블록 분량 파티클(ParticleTypes.HAPPY_VILLAGER 또는 END_ROD)을 5초간 뿌림. LevelRenderer/패킷 거치지 않고 ServerLevel.sendParticles로 간단히 가능. 쿨다운(예: 60초)으로 남발 방지.
  • 옵션 C — HUD 화살표: HudRenderCallback으로 화면 가장자리에 마을 방향 작은 화살표 + 거리(m) 텍스트. 플레이어 yaw·마을 좌표로 각도 계산, 시야각 밖일 때만 표시. 클라이언트 단독 처리(이미 ClientGuideVillage에 좌표 캐시 있음).
• 1차 구현 우선순위 의견: B(파티클)가 가장 가볍고 효과가 명확함 — 신규 아이템·모델·HUD 코드 없이 패킷+키바인드 1개만 추가. A는 바닐라 NBT 매핑 함정이 있고(LodestoneTracker 매핑 이름이 1.20.1에서 어떻게 잡혀있는지 확인 필요), C는 화살표 텍스처/회전 계산이 의외로 디테일이 많다. 일단 B로 "방향 한 번 확인"을 충족시키고, 길게 가져갈 가치가 있으면 A 또는 C로 확장.
• 열린 질문:
  • 셋 중 하나만 갈지, 단계적으로 다 추가할지(B → A → C 순서?).
  • 차원 간 동작 규칙: 네더/엔드에서 오버월드 마을을 가리킬 것인가, 비활성화할 것인가. 비활성이 안전.
  • 마을 도착 판정 후 안내가 자동 비활성되어야 하나(반경 96블록 = v1.6.0 길잡이 주민 판정 반경 재사용)? 자동 비활성이 자연스러움.
  • 안내 사용 제한(쿨다운·횟수)이 필요한가, 아니면 "여정 길잡이" 컨셉상 무제한이 맞나. 탐험 재미를 너무 깎지 않게 쿨다운 30~60초 정도 권장.
  • B 옵션 키바인드 충돌(G는 마인콜로니 등 인기 모드와 겹침) — 기본값을 잘 안 쓰는 키(예: K) 또는 미할당으로 두기.
• 예상 난이도: B = 하(파티클 패킷·키바인드만), A = 중(NBT·모델 함수·차원 처리), C = 중(HUD 좌표·회전·텍스처).
• 의견: (시드 항목. 신설봇, 2026-06-18)
• 의견: 1차 개발은 옵션 B(파티클 트레일)를 독립 기능으로 자르는 데 찬성. v1.6.0의 핵심 한계는 "길잡이 마을 좌표는 알지만 가는 길을 체감하기 어렵다"이므로, 신규 아이템/모델/항상 켜진 HUD보다 필요할 때 한 번 방향을 보여주는 방식이 가장 작고 컨셉도 맞다. 특히 첫 접속 직후 마을 위치가 멀 때 "어느 방향으로 출발하면 되는지"만 해결해도 현재 경험이 크게 좋아진다. 구현 스케치 보강: 클라이언트는 키바인드(기본 K 권장) 입력 시 RequestGuideDirectionPayload 같은 C2S 패킷을 보낸다. 서버는 플레이어가 오버월드에 있고 GuideVillageState에 마을 좌표가 있으며, 플레이어가 반경 96블록 밖일 때만 처리한다. 방향 벡터는 (villageCenter.x - player.x, 0, villageCenter.z - player.z)를 정규화하고, 플레이어 앞 232블록 구간에 12블록 간격으로 ServerLevel.sendParticles를 보낸다. 파티클은 길잡이/마을 톤에 맞는 HAPPY_VILLAGER를 기본으로 하되, 지형 위로 너무 묻히면 END_ROD나 COMPOSTER를 후보로 둔다. 채팅 피드백은 성공 시 생략하고, 실패/쿨다운/도착 상태에서만 짧게 안내하면 화면이 덜 시끄럽다. 엣지케이스: 마을 좌표가 아직 탐색되지 않았거나 findNearestMapStructure가 실패한 월드에서는 키 입력이 조용히 실패하지 말고 "아직 길잡이 마을을 찾지 못했습니다"를 알려야 한다. 네더/엔드에서는 오버월드 좌표와 스케일 차이가 있어 1차 범위에서 비활성화가 맞다. 마을 안(반경 96블록)에서는 파티클 대신 "이미 길잡이 마을 근처입니다"가 자연스럽다. 멀티플레이에서는 서버 저장 좌표는 월드 공통이어도 쿨다운은 플레이어별이어야 하며, 파티클도 요청 플레이어에게만 보이게 전송하는 편이 좋다. 키바인드가 없는 서버 전용 환경을 고려하면 /journey direction 명령은 후순위라도 같은 서버 처리 함수를 공유할 수 있게 설계하면 좋다. 범위 조정 제안: 이번 기능은 "방향 요청 키 + 짧은 파티클 경로 + 30초 플레이어별 쿨다운 + 차원/도착/미탐색 메시지"까지만 합의 후보로 보고, 나침반 아이템(A)과 HUD 화살표(C)는 후속 기능으로 분리하는 것이 좋다. 단, 오포불이 상시 추적 UI를 원하면 C가 더 직접적이므로 최종 상태는 아직 토의중으로 둔다. (코덱스, 2026-06-18)