PotalMap - Valheim Portal Map-Teleport Mod

한국어 설명 보기 | English Description

📸 ScreenShot~!

🗺️ Portal Browser & Colored Access Modes

(스크린샷 준비 중 / Screenshots coming soon)

🇰🇷 한국어 (Korean)

개요

PotalMap은 발헤임의 포탈 이용 방식을 "맵 클릭 텔레포트"로 바꿔주는 모드입니다. 포탈에 들어가면 자동으로 큰 지도가 열리고, 원하는 포탈을 지도에서 클릭(핀 또는 좌측 목록)하면 그 자리에서 바로 이동합니다. 여러 포탈을 순서대로 통과하며 헤맬 필요 없이, 한 번에 원하는 목적지를 골라 이동할 수 있습니다. 포탈마다 공개/개인/길드 3가지 접근 모드를 지정해 누가 이용할 수 있는지도 제한할 수 있습니다.

BepInEx/config/com.korcaptain.potalmap.cfg

🌐 English

Overview

PotalMap turns portal use in Valheim into map-click teleportation. Enter a portal and the large map opens automatically — click any portal pin (or pick one from the list on the left) to teleport straight there, instead of stepping through multiple linked portals one at a time. Each portal can also be restricted to one of three access modes: Public, Private, or Guild.

BepInEx/config/com.korcaptain.potalmap.cfg

Changelog / 변경 로그

[0.1.58] - 2026-08-11

Files Modified / 수정 파일

PortalTracking.cs · PortalZdoFields.cs

[0.1.57] - 2026-08-11

Files Modified / 수정 파일

PortalTracking.cs · PortalZdoFields.cs

[0.1.56] - 2026-08-11

Files Modified / 수정 파일

MapInteraction.cs

[0.1.55] - 2026-08-11

Files Modified / 수정 파일

PortalAccessEvaluator.cs · PortalTracking.cs

[0.1.54] - 2026-08-11

Files Modified / 수정 파일

PortalBrowserPanel.cs · PortalFavorites.cs · UiRowFactory.cs

[0.1.53] - 2026-08-11

Files Modified / 수정 파일

PortalTeleporter.cs · PortalTracking.cs

[0.1.52] - 2026-08-11

Files Modified / 수정 파일

PortalMode.cs

[0.1.51] - 2026-08-11

Files Modified / 수정 파일

MapInteraction.cs · PortalHoverHints.cs

• ✅fix1 : [MapInteraction.cs] Entering a portal while the inventory happened to already be open would force the large map on top of it and leave the game stuck — nothing responded, not even Escape. Root cause: vanilla Minimap.Update()'s own Escape-closes-map handling is gated behind !InventoryGui.IsVisible(), so with both open at once it never ran. Now closes the inventory before opening the portal map (matching Captain_TargetPortal's same code path), plus an Escape-key safety net while our map session is active that force-closes both regardless of how the stuck state might occur
• ✅improve1 : [PortalHoverHints.cs] Colored the portal hover hint text for visual consistency with the browser panel/minimap pins per user request — the E in the mode-cycle key hint is now yellow+bold (matching vanilla's own $KEY_Use hint styling), and the [PotalMap] Public/Private/Guild mode label is now colored via the shared PortalMode.GetColor() palette (yellow/blue/red) instead of plain text
• ✅fix1 : [MapInteraction.cs] 인벤토리가 열린 채로 포탈에 들어가면 그 위에 큰 지도가 강제로 뜨면서 아무 것도(ESC 포함) 안 먹히고 멈추던 문제 — 원인: 바닐라 Minimap.Update()의 ESC-지도닫기 로직 자체가 !InventoryGui.IsVisible() 조건으로 막혀있어서 인벤토리가 열려있으면 통째로 안 돌았음. 이제 포탈 진입 시 인벤토리를 먼저 닫고(Captain_TargetPortal의 동일 지점 참고) 지도를 열며, 혹시 모를 다른 경로 대비 우리 포탈맵 세션 중엔 ESC로 인벤토리+지도를 강제로 둘 다 닫는 안전망도 추가
• ✅improve1 : [PortalHoverHints.cs] 사용자 요청으로 포탈 호버 힌트 텍스트 색상을 좌측 패널·미니맵 핀과 통일 — 모드 순환 힌트의 E를 노란색+굵게(바닐라 자체 $KEY_Use 힌트 스타일과 동일)로, [PotalMap] 공개/개인/길드 모드 표시를 평문 대신 공유 팔레트 PortalMode.GetColor()(노랑/파랑/빨강)로 색칠

[0.1.50] - 2026-08-11

Files Modified / 수정 파일

PortalFullSync.cs · PortalTracking.cs

• ✅fix1 : [PortalTracking.cs] Cross-checked against Captain_TargetPortal and found portal owner attribution used nview.IsOwner() — Valheim's transient, proximity-based ZDO simulation ownership — instead of vanilla's permanent Piece.IsCreator()/GetCreator() (ZDOVars.s_creator, set once at the moment a piece is actually placed). This meant simply walking near someone else's pre-existing portal could silently make your client its recorded "owner". Switched the auto-init check to Piece.IsCreator(); unclaimed portals still fall back to the existing lazy EnsureOwnerInitialized() on first Shift+E attempt
• ✅fix2 : [PortalFullSync.cs] The v0.1.47 join-time full sync silently did nothing — it hooked ZNet.OnNewConnection, which fires before ZDOMan.AddPeer creates the peer's ZDOPeer tracking entry that ZDOMan.ForceSendZDO(peerID, id) looks up internally (no entry = silent no-op, confirmed by reading ZDOMan.cs). Captain_TargetPortal's equivalent (SendKnownPortalsOnConnect) correctly hooks ZDOMan.AddPeer instead, further corroborated by its separate ZDODataBuffer.cs which exists specifically to buffer ZDOData packets across this same early-connection gap. Switched the hook to ZDOMan.AddPeer — this is the first time this feature has actually been able to fire
• ✅fix1 : [PortalTracking.cs] Captain_TargetPortal과 대조 분석하다가 포탈 소유자 판정이 nview.IsOwner()(발헤임이 근접도에 따라 다른 클라이언트로 넘기는 일시적 ZDO 시뮬레이션 소유권)를 쓰고 있던 걸 발견 — 바닐라의 영구 필드 Piece.IsCreator()/GetCreator()(ZDOVars.s_creator, 실제로 그 자리에 배치되는 순간 딱 한 번 기록됨)를 썼어야 했음. 이 버그 때문에 남이 지은 기존 포탈 근처를 걸어가기만 해도 내 클라이언트가 그 포탈의 "소유자"로 조용히 기록될 수 있었음. 자동 초기화 조건을 Piece.IsCreator()로 교체 — 주인이 끝내 안 잡히는 포탈은 기존처럼 Shift+E 최초 시도 시 EnsureOwnerInitialized()가 안전망 역할
• ✅fix2 : [PortalFullSync.cs] v0.1.47의 접속 시점 전체 동기화가 사실 조용히 아무 효과가 없었음 — ZNet.OnNewConnection을 후킹했는데, 이건 ZDOMan.ForceSendZDO(peerID, id)가 내부적으로 찾는 ZDOPeer 추적 항목을 ZDOMan.AddPeer가 만들기 전에 실행됨(항목이 없으면 조용히 아무 것도 안 함, ZDOMan.cs 직접 확인). Captain_TargetPortal의 동일 기능(SendKnownPortalsOnConnect)은 정확히 ZDOMan.AddPeer를 후킹하고, 같은 프로젝트의 ZDODataBuffer.cs가 바로 이 접속 초반 간극 동안의 ZDOData를 버퍼링하는 용도로 따로 존재하는 것도 방증. 후킹 대상을 ZDOMan.AddPeer로 교체 — 이번이 이 기능이 실제로 처음 제대로 작동하는 것

[0.1.49] - 2026-08-10

Files Modified / 수정 파일

PortalTagValidation.cs(new 신규)

• ✅new1 : [PortalTagValidation.cs] Naming a portal the same as an existing one made them indistinguishable in the browser panel/pins. Added a Harmony prefix on TeleportWorld.SetText (fires before the rename RPC is even sent) that checks all known portals for a case-insensitive tag match and, if found, blocks the submission and shows a center-screen message asking for a different name (localized to Korean/English by game language, matching the existing hover-hint convention)
• ✅new1 : [PortalTagValidation.cs] 포탈 이름을 기존 포탈과 똑같이 지으면 좌측 목록/핀에서 구분이 안 되던 문제 — 이름 변경 RPC가 나가기 전 단계(TeleportWorld.SetText)에 Harmony prefix를 추가해서, 이미 알고 있는 모든 포탈 중 대소문자 무시하고 같은 이름이 있으면 제출 자체를 막고 화면 중앙에 다른 이름을 입력하라는 안내 메시지를 띄움(기존 호버 힌트와 동일하게 게임 언어에 따라 한/영 전환)

[0.1.48] - 2026-08-10

Files Modified / 수정 파일

PortalFullSync.cs

• ✅fix1 : [PortalFullSync.cs] The join-time full sync from v0.1.47 didn't cover portals created (or changed) while another player was already connected far away — same root cause, different trigger. Added a second server-side postfix on ZDOMan.AddPortal (fires whenever a portal ZDO is registered or updated) that immediately broadcasts it to every currently connected peer via ZDOMan.ForceSendZDO(id), so new/changed portals now reach everyone right away instead of waiting on proximity-based sync or a future reconnect
• ✅fix1 : [PortalFullSync.cs] v0.1.47의 접속 시점 동기화는 이미 접속 중인 다른 플레이어가 멀리서 포탈을 새로 만들거나 정보를 바꾸는 경우는 포함하지 않았음(같은 원인, 다른 트리거) — 포탈 ZDO가 등록/갱신될 때마다 호출되는 ZDOMan.AddPortal에 서버 쪽 postfix를 하나 더 추가해서, ZDOMan.ForceSendZDO(id)로 그 즉시 현재 접속 중인 모두에게 브로드캐스트하도록 함 — 이제 새 포탈이나 변경사항이 거리 동기화나 재접속을 기다리지 않고 바로 전파됨

[0.1.47] - 2026-08-10

Files Modified / 수정 파일

PortalFullSync.cs(new 신규)

• ✅fix1 : [PortalFullSync.cs] Portals placed before installing PotalMap (or any portal a client had never physically been near, even Public ones set by other players) never showed a pin — root cause: vanilla ZDOMan only syncs ZDOs to a client by proximity priority (ZDOMan.CreateSyncList/ServerSortSendZDOS), so a client's ZDOMan.GetPortals() genuinely didn't know a distant portal existed, regardless of its access mode. Added a server-side Harmony postfix on ZNet.OnNewConnection that force-pushes every known portal ZDO to a newly connected peer via vanilla's own ZDOMan.ForceSendZDO(peerID, id) API — the existing 2s self-heal loop then pins them normally once received. This only takes effect if PotalMap is installed on the server (client-only installs still rely on natural exploration-based sync)
• ✅fix1 : [PortalFullSync.cs] PotalMap 설치 전부터 있던 포탈(또는 한 번도 가까이 가본 적 없는 포탈, 다른 유저가 공개로 설정해둔 것도 포함)이 핀으로 안 뜨던 문제 — 원인: 바닐라 ZDOMan은 거리 우선순위로만 ZDO를 클라이언트에 동기화하므로(ZDOMan.CreateSyncList/ServerSortSendZDOS), 접근 모드와 무관하게 클라이언트의 ZDOMan.GetPortals()가 먼 포탈의 존재 자체를 몰랐던 것. 새 피어가 접속하면 서버가 알고 있는 모든 포탈 ZDO를 바닐라 API ZDOMan.ForceSendZDO(peerID, id)로 강제 전송하는 Harmony postfix(ZNet.OnNewConnection)를 서버 쪽에 추가 — 수신 후엔 기존 2초 자기복구 루프가 알아서 핀을 그려준다. 이 기능은 PotalMap이 서버에도 설치돼 있어야 적용됨(클라이언트만 설치한 경우는 기존처럼 탐험 기반 동기화에 의존)

[0.1.46] - 2026-08-10

Files Modified / 수정 파일

PortalAccessEvaluator.cs · PortalModeHotkey.cs

• ✅fix1 : [PortalAccessEvaluator.cs, PortalModeHotkey.cs] Clarified and re-reverted v0.1.43: the user meant "others can't manage it" as "others without ownership" — a same-guild member of the owner counts as having ownership rights when the portal is in Guild mode, so they may manage it just like the owner again. Private stays owner-only (no guild exception applies since it's not Guild mode), and Public only grants usage, never management, to non-owners
• ✅fix1 : [PortalAccessEvaluator.cs, PortalModeHotkey.cs] v0.1.43 재조정 — "다른 사람은 변경 불가"는 "소유권 없는 사람"을 뜻하며, 같은 길드원은 포탈이 Guild 모드일 때 소유권이 있는 것으로 취급되어 소유자와 동일하게 관리 가능하도록 다시 되돌림. 개인(Private) 모드는 여전히 소유자만(Guild 모드가 아니므로 길드 예외 자동 미적용), 공개(Public) 모드는 비소유자에게 이용 권한만 주지 관리 권한은 절대 주지 않음

[0.1.43] - 2026-08-10

Files Modified / 수정 파일

PortalAccessEvaluator.cs · PortalModeHotkey.cs

• ✅fix1 : [PortalAccessEvaluator.cs, PortalModeHotkey.cs] Reverted the 2026-08-06 decision that let same-guild members cycle a Guild-mode portal's access mode — per user request, Private and Guild portals may now only be managed (Shift+E) by the owner; nobody else, guild member or not, can change them
• ✅fix1 : [PortalAccessEvaluator.cs, PortalModeHotkey.cs] 2026-08-06에 허용했던 "길드 모드 포탈은 같은 길드원도 모드 변경 가능" 결정을 되돌림 — 사용자 요청으로 개인/길드 모드 포탈은 이제 소유자(Shift+E)만 관리 가능하며, 길드원을 포함해 다른 누구도 변경할 수 없음

[0.1.42] - 2026-08-10

Files Modified / 수정 파일

MapInteraction.cs · PortalTracking.cs

• ✅fix1 : [PortalTracking.cs, MapInteraction.cs] Clicking a portal pin directly on the map never worked (only the left-side list did) — root cause: vanilla Minimap.GetClosestPin() only considers pins with m_save == true, but our pins are always created with save=false (setting it permanently true would leak them into the player's local map save file and duplicate on reload). Referenced Captain_TargetPortal's Map.GetClosestPortal for the known-good pattern (rewritten independently, not copied): flip m_save to true on our tracked pins only for the duration of the synchronous GetClosestPin call, then immediately revert it, so the click hit-test reuses vanilla's own search without ever risking a save mid-toggle
• ✅fix1 : [PortalTracking.cs, MapInteraction.cs] 맵에서 포탈 핀을 직접 클릭해도 이동이 안 되던 문제(좌측 목록 클릭만 동작) — 원인: 바닐라 Minimap.GetClosestPin()이 m_save == true인 핀만 찾는데, 우리 핀은 항상 save=false로 생성됨(영구히 true로 두면 플레이어의 로컬 지도 저장 데이터에 새고, 재접속 시 중복 생성됨). Captain_TargetPortal의 Map.GetClosestPortal 패턴을 참고해(그대로 옮기지 않고 새로 작성) GetClosestPin을 호출하는 그 순간에만 우리 핀들의 m_save를 잠깐 true로 켰다가 즉시 되돌리는 방식으로 수정 — 그 사이에 실제 저장이 끼어들 위험 없이 바닐라 탐색 로직을 그대로 재사용

[0.1.41] - 2026-08-10

Files Modified / 수정 파일

RpcCooldownGuard.cs

• ✅fix1 : [RpcCooldownGuard.cs] Full performance/server-load audit of every Harmony patch target against decompiled vanilla Valheim source. Only one real issue found: RpcCooldownGuard's (sender, key) -> timestamp dictionary was never pruned, and since its RPC handlers (PortalModeRpc/PortalTagsRpc) also run on the dedicated server, it grew unboundedly for the life of the server process. Added amortized cleanup (runs at most once every 60s, purges entries older than 120s — well above every cooldown value used) so memory stays bounded by recent activity instead of total server uptime. Everything else checked (minimap pin refresh, portal proximity glow, pin auto-declutter, hover text) was confirmed already efficient or negligible and intentionally left unchanged
• ✅fix1 : [RpcCooldownGuard.cs] 모든 Harmony 패치 대상을 바닐라 발헤임 디컴파일 소스와 대조해 서버 부하/랙 전수 점검. 실제 문제는 하나뿐이었음: RpcCooldownGuard의 (sender, key) → 마지막 처리 시각 딕셔너리가 한 번도 정리되지 않았고, 이 RPC 핸들러(PortalModeRpc/PortalTagsRpc)는 데디케이트 서버에서도 실행되기 때문에 서버가 오래 켜져 있을수록 무한정 커지는 메모리 누수였음. 60초에 한 번씩만(상환 방식) 120초 이상 묵은 항목을 정리하도록 추가 — 이제 크기가 "서버 가동 시간 전체"가 아니라 "최근 활동량"에 비례하게 상한이 걸림. 나머지(미니맵 핀 갱신, 포탈 근접 발광, 핀 자동분산, 호버 텍스트)는 점검 결과 이미 효율적이거나 무시 가능한 수준이라 의도적으로 손대지 않음

[0.1.40] - 2026-08-10

Files Modified / 수정 파일

PlayerIdentity.cs · PortalHoverHints.cs · PortalModeHotkey.cs · PotalMapPlugin.cs(removed 삭제) · PartySummon.cs(removed 삭제) · PartySummonPanel.cs(removed 삭제)

• ✅remove1 : [PartySummon.cs, PartySummonPanel.cs, PotalMapPlugin.cs, PortalModeHotkey.cs, PortalHoverHints.cs, PlayerIdentity.cs] Removed the entire Party Summon feature per user request — deleted PartySummon.cs/PartySummonPanel.cs, its config init call, the Groups soft dependency (nothing else uses it), its hover-hint line, its E-main-key guard in the mode-cycle hotkey, and the now-unused PlayerIdentity.GetOnlinePartyMembersExcludingMe()
• ✅remove1 : [PartySummon.cs, PartySummonPanel.cs, PotalMapPlugin.cs, PortalModeHotkey.cs, PortalHoverHints.cs, PlayerIdentity.cs] 사용자 요청으로 파티 소환 기능 전체 제거 — PartySummon.cs/PartySummonPanel.cs 삭제, config 초기화 호출 제거, Groups 소프트 디펜던시 제거(더 이상 쓰는 곳 없음), 호버 힌트 문구 제거, 모드순환 핫키의 E 메인키 감지 가드 제거, 더 이상 안 쓰이는 PlayerIdentity.GetOnlinePartyMembersExcludingMe() 제거

[0.1.39] - 2026-08-10

Files Modified / 수정 파일

PortalBrowserPanel.cs

• ✅improve1 : [PortalBrowserPanel.cs] Made the portal browser panel taller per user request so more of the list is visible without scrolling — height increased ~1.8x, from 400 to 720 (width unchanged at 190)
• ✅improve1 : [PortalBrowserPanel.cs] 요청에 따라 목록이 더 많이 보이도록 패널 세로 길이를 약 1.8배로 확대 — 400에서 720으로(가로 190은 그대로)

[0.1.38] - 2026-08-10

Files Modified / 수정 파일

PortalBrowserPanel.cs

• ✅fix1 : [PortalBrowserPanel.cs] The left-side portal list panel had a fixed background size, so once enough portals were listed the rows overflowed past the dark background and rendered directly on top of the map (unreadable). The list area is now a scrollable region (ScrollRect + RectMask2D + ContentSizeFitter) with a thin auto-hiding scrollbar, so any number of portals stay contained and scroll instead of overflowing
• ✅improve1 : [PortalBrowserPanel.cs] Lowered all panel font sizes another 4pt per user request — title "Potal_Map" 31→27, group headers 24→20, portal name rows 21→17 — and resized the panel from 210x370 to 190x400 to match
• ✅fix1 : [PortalBrowserPanel.cs] 좌측 포탈 목록 패널이 배경 크기가 고정돼있어서, 포탈이 일정 개수를 넘으면 목록이 어두운 배경 밖으로 넘쳐서 지도 위에 맨 텍스트로 뜨던(가독성 저하) 문제 수정 — 목록 영역을 스크롤 가능하게 바꿔(ScrollRect + RectMask2D + ContentSizeFitter, 넘칠 때만 자동으로 나타나는 얇은 스크롤바 포함) 포탈이 아무리 많아도 패널 안에 담기고 스크롤되도록 함
• ✅improve1 : [PortalBrowserPanel.cs] 요청에 따라 패널 글자 크기를 전부 4pt씩 추가로 축소 — 제목 "Potal_Map" 31→27, 카테고리 헤더 24→20, 포탈 이름 행 21→17 — 패널 크기도 210x370에서 190x400으로 조정

[0.1.37] - 2026-08-10

Files Modified / 수정 파일

PortalTracking.cs · PotalMapGeneralConfig.cs

• ✅new1 : [PortalTracking.cs, PotalMapGeneralConfig.cs] Portal pins clustered close together (e.g. many portals in one base) used to render stacked on top of each other, making icons and name labels unreadable. Nearby pins (within a configurable radius) are now automatically spread into a small circle purely for map display — the portal's real position and teleport destination are unaffected. New configs: "Declutter portal pins" (on by default), "Pin cluster radius" (15m), "Pin spread radius" (10m)
• ✅new1 : [PortalTracking.cs, PotalMapGeneralConfig.cs] 한 거점에 포탈이 여러 개 몰려있으면 핀 아이콘과 이름표가 서로 겹쳐 뭉개지던 문제 — 가까이 있는 포탈 핀들(설정 가능한 반경 이내)을 지도 표시용으로만 작은 원형으로 자동으로 퍼뜨리도록 개선. 포탈의 실제 위치나 텔레포트 목적지는 영향 없음. 신규 설정: "Declutter portal pins"(기본 켜짐), "Pin cluster radius"(15m), "Pin spread radius"(10m)

[0.1.36] - 2026-08-10

Files Modified / 수정 파일

PortalBrowserPanel.cs · PortalMode.cs · PortalTracking.cs

• ✅fix1 : [PortalTracking.cs] Portal name labels on the minimap were always forced red regardless of access mode; now colored per mode instead — Public=yellow, Private=blue, Guild=red (shared with the portal browser panel via a new PortalMode.GetColor() extension so both stay in sync)
• ✅fix1 : [PortalTracking.cs] 미니맵 포탈 이름표가 모드와 상관없이 항상 빨간색으로 고정돼있던 것을 모드별 색상으로 변경 — 공개=노랑, 개인=파랑, 길드=빨강 (새 PortalMode.GetColor() 확장 메서드로 포탈 브라우저 패널과 색상을 공유해 항상 일치하도록 함)

[0.1.35] - 2026-08-10

Files Modified / 수정 파일

PortalBrowserPanel.cs

• ✅improve1 : [PortalBrowserPanel.cs] All portal browser panel font sizes were still too large, so lowered each by 4pt — title "Potal_Map" 35→31pt, group headers (Public/Private/Guild) 28→24pt, portal name rows 25→21pt — and shrank the panel from 240x420 to 210x370 to match
• ✅improve1 : [PortalBrowserPanel.cs] 포탈 브라우저 패널 글자 크기가 여전히 커서 전부 4pt씩 줄임 — 제목 "Potal_Map" 35→31, 카테고리(공개/개인/길드) 헤더 28→24, 포탈 이름 행 25→21 — 패널 크기도 240x420에서 210x370으로 축소

[0.1.34] - 2026-08-10

Files Modified / 수정 파일

PortalBrowserPanel.cs

• ✅improve1 : [PortalBrowserPanel.cs] Retuned the portal browser panel (left side of the large map) font sizes down to a more readable scale after an earlier oversized pass — title "Potal_Map" 35pt, group headers (Public/Private/Guild) 28pt, portal name rows 25pt — and shrank the panel back down to 240x420 to match
• ✅improve1 : [PortalBrowserPanel.cs] 맵 좌측 포탈 브라우저 패널의 글자 크기를 이전에 과도하게 키웠던 것에서 보기 좋은 크기로 재조정 — 제목 "Potal_Map" 35, 카테고리(공개/개인/길드) 헤더 28, 포탈 이름 행 25 — 그리고 패널 크기도 240x420으로 다시 맞춤