TanukiTarkovMap

KO | EN

gitlite — search

#open-source #redis #cpp #css #large-language-models #c #java #data-science #bash #typescript

TanukiTarkovMap

(★ 9)

Escape from Tarkov용 인게임 미니맵 오버레이 툴입니다. 스크린샷을 찍으면 좌표를 감지해 현재 위치를 미니맵에 표시합니다.

파일 탐색기

ZIP 다운로드

- - release.yml
  - verify-map-recovery.yml
- - 00663fc99ec6b1aaab23a2f7ca56932d49491599
  - 02d34cdc75f4d3f6113ecbe4ca7c058d5e15665a
  - 04ed5dfb3349e04a29cbc1305d53fe32c4e7b4ed
  - 08fbb47babef5c9aefdf1872f1e5b3b056da0043
  - 0a67a4f05e0782f95301bba6c98799ad69a4cca6
  - 0c3ebe3a9497bb6860793002c03b4fd92fa98131
  - 0dbf5165a87fa5a8eb38a78bee70d9d61eea2ddc
  - 0e471a4feef676eb5d483d2e612b8b8c770ce76d
  - 0ffa064bd2bb71f9b8d8b674a36422adb097bf67
  - 10d21f84c71972f1d3a7e0f434088866a5c68a2b
  - 1138b90c028ff1f6886213bc3476e49a35eff1ed
  - 133df7dd637417710503202cce8181d7bc93473c
  - 137c810cfbd043194f38700ce8b1a757fa3b3160
  - 1466c90299eaa1dbb1f438f8309664186b2c2ca9
  - 19be1b0f4b0f54d0702ff7b4b119e81b4c8cad75
  - 19e4eb83d885acca6bc4b519a260ea38b2ec6db5
  - 1a065e97bc34159407b0b8f030ded33de556e2e1
  - 200e075358bd6110ce5acbae81e596e28169cbf3
  - 21695e2f8943215a642bf3ed9fb31e234f91eb49
  - 2358a3e333c21e6196aab8acda7604d15444e464
  - 28ca06f732a4b5ce07cb69be6e97e66b06c79e58
  - 2b603388c5d32af84c2eedcf23bcb51cca526228
  - 2c05c1a2a8bf477191303ad6daf061c26f91e3db
  - 2f086394ea9009aa304be590aef8bba55076f36c
  - 317d3d494a4e5735aa111dfa8767a86a55069fe2
  - 327e70c9724db9b18e2d53d6ab08a12662ee8959
  - 3515d2fd827d5e552d20cb698795e4690e155ee5
  - 374e7354961fe67447d45783ccd1722321b3bb33
  - 38148ef0b0ec88bab0ab107ff9211f13a1b7777f
  - 3abbe33ba6f0141b45244ce520ee24e5b9b5518f
  - 3bc70ef8c9144d63ae3dc5f54b1884867250cf0a
  - 3c62fd9cf32c1fec93f6bc4b0edb8293913b8062
  - 3c6b9f04f191c9b5505dd4dedab010259fc5bb43
  - 40d705fe80968a499c0d3619255d63442b913609
  - 4184dc5c2e55b47d7d676ac842766e8334eb4593
  - 44de6aa6426a89e01e79b8ae40fb44206b505c61
  - 460a684c2f1ad0f7ef760be92ebaa7d7343761d0
  - 47e14be83524f070dec9f72eca70e39c835c164a
  - 491a066af7d6f741f83d332b5006064935962a08
  - 493959ec036422e6c083f0310a78e679ccc1b0bf
  - 497d0c595b9cf59dbf22a2b101110d72f6c365b4
  - 49c680338dc22b09c32407d41a0be351c47c8181
  - 4a3ac9b19b5f01556f63f1344f4ab8a700eb5b7f
  - 4a5db0e29a0a0dae91f29d0de3b3644cd7031c75
  - 4a82de9c4d8860250c13e15a6027a6ca0f86cb1c
  - 4b78ab296adb178b0b6289e6b30c68a48cb827ad
  - 4c3fe996ef877a326a4d8135678900afce1122e0
  - 514c6c1d8475d17e412849a4c90159517d0fa10a
  - 5154dbdf7633f01e33a410bdfdd2935c5eb08e9d
  - 51b7eb9bdcf1e349162d33bb4b6be6592b575c21
  - 531dfbc572837de638bab908d4b849dfb4d65f52
  - 53571791c757e872176e3c3fa44a7075acae685e
  - 5409a8697c5b630b0121dc3887ba508350d835de
  - 545ab10529bb2226111d1a1c694ef9ae4d96f107
  - 5518ba31b7b0b294ecbf529733218b564ed3446d
  - 5578899eda59c8b87d45dd6de0c1e3ead6012053
  - 56988701d2a7a27743c6238d3b3fbcad6a9222b7
  - 5791dd0395fba2e9b0e56d36d565d82fd8b9f9ea
  - 57a0576ceb648ac1228001d78cd594ec11a29745
  - 57d05a87b23f68d115d34b5bc84b1ebef9d1b4de
  - 58a1cc5b05ef2f63b45eaad4b242d4ee43b5f8d2
  - 5961836a4fa1762f9df895c97fd3a01311a9ebf8
  - 5a1f955935ca9f15d14718fc7398e83af55805e4
  - 5b4cebb44505669635925b4ec9e42c1e58f7dabe
  - 5c14d40b634933c040943265368488cabcd681b3
  - 5ef08e8763aabc1ad043c7e3621d593cd037da97
  - 6426d8c3a5ad764d4e03801ab5f92d0680b9e08d
  - 65ea46b42178863c0096c2b44adcf0f03c6c32f7
  - 6727ec409bb7b11989e638f85f9584b047e629aa
  - 69aa40b3007d92b02ba12f42ad39cdf0c4d63e85
  - 69d171bdc47d4a67cade64c6b821945934374a37
  - 6a60aa923ee2d4dc0d202b9ccd8b4c08f96df51e
  - 6ad956f7e5d9e120b3c5c2c347af5698bca2001f
  - 6d17a94d4af494580f1be9c7bea09b1f35d98b12
  - 6d4c464cbfd45091aab31d26713badf52938b9eb
  - 6e8e81a7383b63675c5b427d00f13efbb4e987df
  - 6fce1a3e3f329092aea9f65527a9a0409be38a89
  - 72221495048cd899049430d40c31cd8fc0996e83
  - 7280e0c7990c9608c0c13dc1804bc310d2894ded
  - 72bba0e5a8a61595bb41b77c0eb7c19a9c0f6c13
  - 75cd89aafbc422723ad1054f309f8f40e03ac0fd
  - 7d24c30d1344e3bf47acf943359f72a44e1f6986
  - 7ddf075c0c510975b8c66fb2639f4102c2b7b748
  - 7f4bf4d55d7f8d998f3a023d45bd296c5fff0406
  - 827fb90be510a2a183b849e09b85525ec09f7897
  - 8393415e3eb2b4d7fce6b4ae44bb73ea6844e668
  - 86caf9f3ca863859172c64b30aa137cba2e474c0
  - 87b135e7561d0683346650e701669ad4310c2727
  - 8be27017ee671b7f2db10ec8f48d541bc8befae4
  - 8bea17976ae343c05ae75dc52730337dc58fba3f
  - 8c319fd36db16ce1044c91d981d0ba76c50018b0
  - 8dc729fa5bd5b9f5296a43a385f3f7a778473c60
  - 8e04eaeed3917eff02248c449aad072fb0d1093d
  - 8e73de714ce186cd542ce22199c51286ae374f0e
  - 8f7270bd43d75372cd97b284b664748a17525d55
  - 96d0c99797d345f0633be92816bbfc9072104d3d
  - 99f77b9a06cb92aeac2b8ada92e282ecdda56074
  - 9ab4af3fb8f2c7032840b13b47ea904bde5b79c6
  - 9b2274c2f82fd1e145d2aa48bf37300b60325405
  - 9d898a58ecfc85e395c0a162c9b84e24ae5a438d
  - 9e11fc264723b788beac9370f99383d9744790b6
  - 9fdec975f4d204cbd05497a2b070decaec12cff0
  - 9ffba04bd83ee2d38b6953a5977675353080381e
  - a27c0fb4b2a33a742f5d1f23d5a6ced5fb462d3e
  - a29c6481aeebb352a5017af24c462b71e333aa20
  - a40f3de934ce12d58fb78f4c240179357a627bf8
  - a6bf48ee2c7cef0d93ae60928eac00b3aa0b4efa
  - aa4a4d7135b42cc5b6e123404e9e11a9b10983dc
  - aa9a4f1ef40f6b5f8587baec4cc01207eb581add
  - abc0e03f6f5ec948b66e8c8f9a002e2f4a29269a
  - ac65a0707cb4dc199127fc20d9943418bbcc4c8a
  - ae6a6aea6d0855065c36936950cf33ea6e4de1e6
  - ae6ad82f85b873dfc1ecab5c7f1554033bdd34e0
  - af3f799147a3c8620b811c7f58ece8002d8eaf81
  - b2d867a336065a57ba66750534064efd33ef450c
  - b47accccaf66fa65402e0b84c641f6aa403adc35
  - b5b86b6a872a0a4bb67023142ccd6d3c016432e8
  - b69554120a1740df44901a899ca75e7b2aac355d
  - b70075c9e093ff156454562cb29c56f8b51835da
  - b7f53591360e5bb7cdf64b95cb7dd5066df19a68
  - b880f440166dbf466cf32b1fc0da9b847cc73cd2
  - b93a02cfe9388bb3748e1e2b5bd6d13676d5f239
  - b9946efe2aa628e9920be6db880887c256dd2a50
  - c0310f092b78a5b916e0fb94c04e105a5641a3b8
  - c183a2deafae2c455df08f051181e91f8c40b693
  - c46aa91ddc9a62db52fd6f26bf42659b86086a7d
  - c503b61f64ac4ad65110d577c96d6e86e033df7c
  - c6d4f5f5898218064dfd2858ad22fa2e1a6637c1
  - c87e04c930d4670b8f7e9372e9b015dbb97dbfaa
  - c8bf287344b67b29a016be99472e5b0971f4eea7
  - d0268a5c283a13ba19b830aced11574eb1134e94
  - d173b9558d24f829f675bb1149b6490862d2d673
  - d1d070452907e36a2f1a07adafdca4452783d6bf
  - d2121ab8434716372c30d449eca9a06b75b8254d
  - d2e8b67d22c462c600be5eedd379eabce84cc794
  - d4cb1cd95834b833e4710745d1e144f6bfe75bd7
  - d4d587808b347efd83ec9fb2f7d8377f14b24e73
  - d5e5225fd4169fe62bc88e2e2d4cf3d4b9c40df5
  - d6603c2b3e65ff5fe4478da9059e4ef80e5d8f0b
  - d8af1e59b766f5505da81bb91ef0150fb89dea40
  - da39a3ee5e6b4b0d3255bfef95601890afd80709
  - db857d8316cefec1c82522cf0e8c6ac88fa227bd
  - dde410d50e0a6da58336a166e72eef6ab492f670
  - df8cff336e8078f4b10977860453d86d7c69fa29
  - e044bb14da1ca8db7d50690ce6444ae20309ff37
  - e455ab3dee6dcfa0d02e067b428626ea416a6808
  - e7ccaad56bddf2456384ed466f780471766a4c28
  - e82bbb614745b264a4975f925bea368313da982a
  - e9727da868658f164e199f13b3c66bd5d470924d
  - eb6ca1d1671badd1ee5ad755e2b1b9cabd062b7a
  - ecbf6c87d10096dc3507f11425f8875af25aa22a
  - edf07105943710d072bcc0b23fdb5761882e2413
  - ee0307f9951ae77abc2ef946901423b007cac593
  - ee85036a9cdd5da4b843f2e6262fd6c11f229a03
  - ef8c6865013cce53a1d2f7519a2bf97db58f83f7
  - f17ecf187a0ebed95fa3d91c46c4dd84d1cf84ad
  - f2c2f80d46d4ddc0b2c79c7373941be1f0e6bde5
  - f2d5f00af83f5cf836ebd20f5ffe4964a9fc4da3
  - f65b3da0f0c25dfcc9b563ca1494039dff8f9100
  - f6a1660ff3d27498e0235896e28e7e30ce18c302
  - f9c6e0ff4849f1167fb1577ed906c34a90b26402
  - fb76b9dcdf48ae692b884c6ce92850b859982180
  - fbd6177499ddc552f46a5700bc85718ad71f1bc9
  - fc6483253e9ebba1c6da7c6073585237c4554d3a
- - customs.json
  - factory.json
  - ground-zero.json
  - icebreaker.json
  - interchange.json
  - lab.json
  - labyrinth.json
  - lighthouse.json
  - reserve.json
  - shoreline.json
  - streets.json
  - woods.json
- manifest.json
- README.md
- - 0.0.1.md
  - 0.0.3.md
  - 0.0.4.md
  - 0.0.5.md
  - 0.0.6.md
  - 0.0.7.md
  - 0.1.0.md
  - 0.2.0.md
  - 0.2.1.md
  - 0.2.2.md
  - 0.2.3.md
  - 0.2.4.md
  - 0.2.5-beta.md
  - 0.2.5.md
  - 0.2.6.md
  - 0.2.7.md
  - 0.2.8.md
  - 0.3.0-beta.md
  - 0.3.1.md
- 20260816-startup-speed-and-updates.md
- 20260816-update-delivery-design.md
- 20260817-pilot-bridge.md
- 20260818-embedded-site-control.md
- 20260818-offline-map.md
- 20260910-position-recovery-pr.md
- icon.png
- screenshot.jpg
- - app.manifest
  - App.xaml
  - App.xaml.cs
  - AssemblyInfo.cs
  - Program.cs
  - TanukiTarkovMap.csproj
  - TanukiTarkovMap.csproj.user
- TanukiTarkovMap.sln
- archive-maps.mjs
- cdp-debug.mjs
- verify-archive.mjs
- verify-map-recovery.mjs
.gitattributes
.gitignore
.mailmap
AGENTS.md
build.bat
CheckList0.md
CLAUDE.md
LICENSE
PROJECT.md
README.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> **Escape from Tarkov용 인게임 미니맵 오버레이 툴입니다.<br>스크린샷을 찍으면 좌표를 감지해 현재 위치를 미니맵에 표시합니다.**

게임 위에 항상 떠 있는 창으로 [tarkov-market.com](https://tarkov-market.com/pilot)의 인터랙티브 맵을 띄우고, 인게임 스크린샷에 기록된 좌표로 현재 위치를 실시간 표시합니다. 알트탭 없이 단축키 한 번으로 맵을 확인할 수 있습니다.

![인게임 실행 화면: 게임 위에 항상 표시되는 맵 오버레이](https://raw.githubusercontent.com/siakun/TanukiTarkovMap/main/images/screenshot.jpg)

---

## 설치

1. [Releases 페이지](https://github.com/siakun/TanukiTarkovMap/releases/latest)에서 최신 Setup 설치 파일(`TanukiTarkovMap-Setup-<버전>-x64.exe`)을 내려받습니다.
2. 실행해 설치하면 이후 업데이트는 자동으로 적용됩니다. 설정에서 자동 업데이트를 끄거나 원하는 버전으로 되돌릴 수도 있습니다.

설치 없이 쓰고 싶다면 같은 페이지의 포터블 버전(`TanukiTarkovMap-Portable-<버전>-x64.zip`)을 내려받아 압축을 풀고 실행합니다. 포터블은 설치 절차가 없어 아래 요구 사항의 VC++ 재배포 패키지를 직접 깔아야 합니다.

> **요구 사항**: Windows 10/11 (x64), [Microsoft Visual C++ 2015-2022 재배포 패키지(x64)](https://aka.ms/vs/17/release/vc_redist.x64.exe)
>
> 재배포 패키지는 내장 브라우저(CefSharp)가 쓰는 런타임입니다. Setup 설치 파일은 없으면 설치 과정에서 알아서 깔아 주므로 따로 준비할 것이 없고, 포터블만 직접 설치가 필요합니다. 없이 실행하면 `CefSharp.Core.Runtime.dll`을 불러오지 못했다는 오류로 앱이 시작하지 않습니다.
>
> **안전성**: 게임 메모리를 읽거나 게임 프로세스에 개입하지 않습니다. 이 앱이 읽는 것은 스크린샷 파일명(이미지 내용이 아니라 이름에 담긴 좌표만)과 입장한 맵이 기록된 게임 로그 두 가지뿐이며, 게임 파일을 수정하지 않습니다. 자세한 원리는 [프로젝트 배경](#프로젝트-배경)을 참고하세요.

---

## 사용법

1. TanukiTarkovMap을 실행합니다. 게임의 스크린샷 폴더는 자동으로 감지되며, 필요하면 설정 창에서 직접 지정할 수 있습니다.
2. 게임을 시작하면 입장한 맵으로 자동 전환됩니다.
3. 게임 중 단축키(기본 `F11`, 설정에서 변경 가능)로 맵 창을 켜고 끕니다.
4. 인게임 스크린샷 키(기본 `PrtScn`)를 누르면 맵에 현재 위치가 표시됩니다. 스크린샷을 찍을 때마다 위치가 갱신됩니다.

창 표시/숨김 단축키는 미니맵 창 전체를 트레이로 숨기거나 다시 표시하며, 앱을 종료하지 않습니다. 위치 갱신에는 게임의 Screenshot 키를 사용합니다. 한 모니터에서 게임 위에 계속 띄우려면 상단 핀(항상 위)을 켜 주세요.

> **Steam 사용자 주의**: Steam의 `F12` 스크린샷은 Steam 오버레이 기능이라 좌표가 기록되지 않습니다. 반드시 게임 자체 설정(Controls)의 Screenshot 키를 써야 하며, 기본 `PrtScn`이 동작하지 않는다는 보고가 있으니 그 경우 다른 키로 재바인딩하세요.

설정 창에서 단축키, 투명도, UI 표시 여부, 자동 맵 전환, 스크린샷 자동 정리, 업데이트 방식을 바꿀 수 있습니다. 맵 타일이 쌓이는 브라우저 캐시가 얼마나 되는지 확인하고 비우는 것도 같은 창에서 합니다. 문제가 생기거나 건의할 내용이 있으면 [GitHub Issues](https://github.com/siakun/TanukiTarkovMap/issues)에 남겨 주세요.

---

## 주요 기능

| 기능 | 설명 |
|------|------|
| 맵 오버레이 | 게임 위에 항상 표시되는 인터랙티브 맵 (Always-on-Top) |
| 실시간 위치 추적 | 인게임 스크린샷을 찍으면 맵에 현재 위치를 자동 표시 |
| 자동 맵 전환 | 게임 로그를 감지해 입장한 맵으로 자동 전환 |
| 전역 단축키 토글 | 단축키(기본 `F11`) 한 번으로 맵 창 표시/숨김, 조합키와 특수키 지원 |
| 투명도 조절 | 상단 바가 숨겨지면 창이 반투명해져 게임 시야 방해를 최소화 |
| UI 정리 | 웹페이지의 불필요한 요소를 제거해 맵만 표시 |
| 군즈 최근 목격 제보 | PvE 목격 제보의 맵 표시 |
| 업데이트 관리 | 새 버전 자동 적용, 자동 업데이트 끄기, 지난 버전으로 되돌리기 |

군즈 최근 목격 제보는 기본적으로 꺼져 있으며, 설정에서 켤 수 있습니다. 군즈는 확률에 따라 스폰하므로 제보와 실제 출현이 다를 수 있습니다.

---

## 프로젝트 배경

Escape from Tarkov은 인게임에서 스크린샷을 찍으면 파일명에 플레이어의 월드 좌표(X, Y, Z)와 카메라 회전값이 함께 기록됩니다. 개발사 Battlestate Games가 버그 리포트용으로 공식 제공하는 기능이며, 게임 메모리나 프로세스에 접근하지 않고 디스크에 저장된 파일만 읽습니다.

```
2025-12-20[02-09]-420.18, 1.00, 319.01-0.00089, -0.99307, -0.00012, -0.11748_15.11 (0).png
└ 날짜/시각 ┘ └ 위치 X, Y, Z ┘ └ 카메라 회전(쿼터니언) ┘
```

[tarkov-market.com](https://tarkov-market.com/pilot)의 Pilot 페이지는 이 좌표를 받아 맵 위에 현재 위치를 표시합니다. 다만 브라우저로 여는 웹앱은 구조적 한계가 있습니다. 게임 위에 항상 고정(Always-on-Top)하거나, 창을 반투명하게 만들거나, 전역 단축키로 토글하는 것처럼 운영체제 창을 직접 제어하는 일을 할 수 없습니다. 데스크톱 클라이언트가 필요한 이유가 여기에 있습니다.

이런 도구는 이미 여럿 있습니다. 원조는 tarkov-market.com이 공식 감지하는 [ggdiam/TarkovPilot](https://github.com/ggdiam/TarkovPilot)(.NET Framework, 트레이 전용 헬퍼)이고, 한국 커뮤니티의 [byeong1/Tarkov-Client](https://github.com/byeong1/Tarkov-Client)는 이를 Edge WebView2로 감싸 창 안에 띄웠습니다. 이 프로젝트는 byeong1 버전의 아이디어에서 출발했지만, 웹뷰 엔진을 CefSharp로 교체하고 창 제어, 좌표 동기화, 빌드 파이프라인을 처음부터 다시 설계했습니다.

---

## 기술 스택

| 구분 | 사용 기술 |
|------|-----------|
| 언어, 런타임 | C#, .NET 8.0 |
| UI | WPF, MVVM (CommunityToolkit.Mvvm), Microsoft.Xaml.Behaviors |
| 웹뷰 | CefSharp.Wpf.NETCore (Chromium) |
| 네이티브 제어 | P/Invoke (user32.dll) |
| 웹 연동 | CefSharp JavaScript 주입 (window.pilot 브리지) |
| DI | Microsoft.Extensions.DependencyInjection |
| 트레이 | Hardcodet.NotifyIcon.Wpf |
| 배포, 자동 업데이트 | Velopack, GitHub Actions |

---

## 기술적 구현

이 프로젝트의 핵심은 "웹앱이 못 하는 일을 네이티브 클라이언트가 대신하는 것"입니다. 각 기능을 어떤 문제 때문에, 어떤 방식으로 풀었는지 정리합니다.

### 1. Edge WebView2에서 CefSharp로 포팅

출발점이 된 도구는 Windows에 내장된 Edge WebView2를 썼지만, 이 프로젝트는 웹뷰 엔진을 CefSharp(Chromium Embedded Framework)로 교체했습니다. WebView2는 런타임이 사용자 환경에 의존하는 반면, CefSharp는 Chromium을 앱과 함께 배포해 환경에 독립적이고 렌더 프로세스, 스크립트 주입, 줌 같은 동작을 더 직접 제어할 수 있습니다. 페이지 로드 시점(`FrameLoadEnd`)에 맞춰 커스터마이징 스크립트를 주입하고, `JavascriptMessageReceived`로 웹에서 앱으로 오는 메시지를 받는 방식으로 통합했습니다.

### 2. P/Invoke(user32.dll)로 네이티브 창 제어

웹앱이 할 수 없는 OS 창 제어를 P/Invoke로 직접 구현했습니다.

- **Always-on-Top**: `SetWindowPos`에 `HWND_TOPMOST`를 적용해 게임 위에 고정
- **반투명 창**: `GetWindowLong`/`SetWindowLong`으로 `WS_EX_LAYERED` 스타일을 켜고 `SetLayeredWindowAttributes(LWA_ALPHA)`로 알파값 조절
- **전역 단축키**: 저수준 키보드 훅(`SetWindowsHookEx`)으로 게임이 포커스를 가진 상태에서도 토글 동작

모든 Win32 호출은 `PInvoke.cs` 한 곳에 모아 선언하고, `WindowTopmost`와 `WindowTransparency` 같은 의도 단위 래퍼로 감싸 호출부가 플래그를 직접 다루지 않도록 했습니다.

### 3. 실시간 좌표 동기화 (FileSystemWatcher + Pilot 브리지)

스크린샷 폴더를 `FileSystemWatcher`로 실시간 감시하다가 새 파일이 생기면, 파일명을 내장 브라우저의 Pilot 브리지에 전달합니다. 브리지는 파일명에서 좌표와 회전값을 읽고 사이트의 지도 기능으로 위치를 표시합니다. 게임 로그도 함께 감시(`LogsWatcher`)해 플레이어가 입장한 맵을 자동으로 전환합니다.

`PilotBridge`는 페이지에서 사용 가능한 Pilot 서비스를 확인해 좌표를 전달합니다. 이전 `window.pilot` 경로와 Nuxt의 Pilot 서비스를 지원하며, 좌표가 지도에 반영됐는지 확인한 뒤 전달을 마칩니다. 로딩 중 놓친 최신 입력은 다시 보내고, 새로고침이나 페이지 이동으로 사라진 방향 스크립트도 복구합니다.

2026-08-17까지는 앱 안에서 ASP.NET Core Kestrel로 포트 `5123`에 WebSocket 서버를 띄우고, 사이트가 그 서버에 접속해 파일명을 받아 갔습니다. 같은 날 tarkov-market이 Pilot v2를 배포하면서 사이트가 로컬 앱 대신 자기 서버(`wss://tarkov-market.com/ws/pilot`)로만 붙게 바뀌어, 서버를 띄워도 접속하는 클라이언트가 없어졌습니다. 서버 중계 규약을 따라가려면 계정 인증까지 구현해야 하는데 `window.pilot`은 그것 없이 같은 일을 하므로, WebSocket 서버와 ASP.NET Core 의존을 걷어내고 브리지 호출로 갈아탔습니다. 진단 근거와 버린 대안, 사이트 변경을 알아차리는 방법은 [Pilot 연동과 위치 전달 경로](docs/20260817-pilot-bridge.md)에 정리했습니다.

### 4. 오프라인 맵 (실험적 기능)

설정에서 "로컬 맵 사용"을 켜면 상단 바에 Online/Local 전환이 생깁니다. Local은 사이트에 접속하지 않고 앱에 담긴 사본으로 맵을 엽니다. 지도와 Levels, 선택한 진영의 추출구, 현재 위치와 방향만 남기므로 사이트가 죽어 있어도 레이드에 필요한 정보가 동작합니다.

사본은 `tools/archive-maps.mjs`가 실제 브라우저로 맵 페이지를 열어 받은 응답을 저장한 것이고, 앱은 CefSharp의 요청 가로채기로 그 응답을 돌려줍니다. 주소는 온라인과 같지만 Local은 독립된 임시 저장 공간에서 열어 온라인의 DB와 캐시가 사본에 섞이지 않게 합니다. 모드를 전환하면 같은 맵을 다시 열고 마지막 위치를 전달하며, 앱의 진영과 확대 설정도 다시 적용합니다. 브라우저의 방문 기록과 Local 페이지 안에서만 저장한 설정은 전환할 때 초기화됩니다. 설계 근거와 한계는 [오프라인 맵 설계](docs/20260818-offline-map.md)에 정리했습니다.

### 5. 게임 로그 파싱으로 자동 맵 전환

게임은 실행할 때마다 로그 폴더(공식 런처는 `게임 폴더\Logs`, 스팀판은 `게임 폴더\build\Logs`) 아래에 새 세션 폴더를 만들고 `application.log` 등에 상태를 기록합니다. 게임 폴더는 레지스트리에서 자동 감지하며(공식 런처 -> 스팀 순), 실패하면 설정에서 직접 지정할 수 있습니다.

- **공식 런처**: `HKLM\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\EscapeFromTarkov`의 `InstallLocation` 값 (폴더가 실제 존재할 때만 채택)
- **스팀**: `HKLM\SOFTWARE\WOW6432Node\Valve\Steam`의 `InstallPath`에서 `steamapps\libraryfolders.vdf`를 파싱해 얻은 모든 라이브러리 폴더의 `steamapps\common\Escape from Tarkov`를 확인

`LogsWatcher`는 가장 최근 세션 폴더를 골라 감시하고(새 폴더가 생기면 자동으로 갈아탐), 로그 파일이 갱신될 때마다 마지막으로 읽은 위치부터 새로 추가된 줄만 이어 읽습니다(`FileShare.ReadWrite`로 열어 게임의 쓰기와 충돌하지 않음). 앱 시작 전에 이미 쌓여 있던 과거 로그로는 화면을 전환하지 않아, 지난 판의 맵으로 잘못 바뀌는 것을 막습니다.

맵 판별은 씬 로드 로그(`scene preset`) 줄에서 `path:maps/<프리셋>.bundle`의 프리셋 이름을 뽑아 합니다. 매치 생성 로그(`TRACE-NetworkGameCreate profileStatus`)의 `Location:` 값도 같은 정보를 담지만, 씬 로드 줄이 언제나 먼저 나오고 이쪽만 남는 레이드도 있어 씬 로드 줄 하나만 봅니다.

뽑아낸 프리셋 이름은 감지한 자리에서 곧바로 맵으로 해석합니다. 로그 문자열을 해석하는 코드를 `LogsWatcher` 한 곳에 묶어 두려는 것이고, 그 뒤 단계는 문자열이 아니라 맵 객체만 주고받습니다.

```
scene preset 줄 감지
  -> LogsWatcher          프리셋 이름 추출
  -> MapConfiguration     프리셋을 맵으로 해석 (등록되지 않은 값이면 여기서 중단)
  -> MapEventService      맵 변경 이벤트 발행
  -> MainWindowViewModel  SelectedMapInfo 대입 (드롭다운 수동 선택이 합류하는 지점)
  -> WebBrowserViewModel  CefSharp 주소 이동
```

맵과 프리셋의 관계는 1:N입니다. Ground Zero는 레벨 구간마다, Factory는 시간대마다 프리셋이 따로 있어서 맵 하나가 프리셋 목록을 갖는 형태로 `MapConfiguration`에 등록합니다. 목록에 없는 프리셋이 나오면 전환하지 않고 그 이름만 앱 로그에 남깁니다. 게임에 새 맵이 추가됐을 때 무엇을 등록해야 하는지 그 줄로 알 수 있습니다.

자동 전환이 `SelectedMapInfo`를 거치는 것도 의도한 부분입니다. 사용자가 드롭다운에서 맵을 고를 때와 같은 지점으로 합류시키면, 주소를 바꾸고 스크립트를 다시 주입하는 코드가 한 벌만 남습니다. 자동 전환을 끄면 이 대입만 건너뛰므로 수동 선택은 그대로 동작합니다.

레이드에 들어간 뒤에 앱을 켜면 진입 로그가 이미 지나가 있어 실시간 감지가 걸리지 않습니다. 그래서 과거 로그에서도 맵 이름만은 읽어 마지막 값을 기억해 두고, 인게임에서만 찍히는 스크린샷을 신호로 삼아 그 맵으로 보정합니다. 이미 그 맵을 보고 있으면 아무 일도 일어나지 않으므로, 정상적으로 전환된 뒤에는 스크린샷을 찍어도 화면이 흔들리지 않습니다.

이 밖에 BattlEye 초기화 로그(`BEClient inited successfully`)는 레이드 경계 신호로 삼아 스크린샷 자동 정리를 트리거하고, 알림 로그의 퀘스트 알림(JSON)을 파싱해 퀘스트 진행 상태도 페이지에 전달합니다.

### 6. CefSharp와 JavaScript 양방향 통신

위치 및 방향 연동을 수정한 뒤에는 Node 22 이상과 Chromium 계열 브라우저가 설치된 환경에서
`node tools/verify-map-recovery.mjs --archive archive`를 실행합니다. 브라우저는 창 없이 임시
프로필에서 실행되며, 재현 페이지의 복구 동작과 네트워크를 차단한 지도 사본을 검사합니다.
이 검사는 PR과 릴리스에서도 실행되고, 실패하면 배포가 중단됩니다. 실제 게임에서의 창 순서와
포커스, WPF에서의 모드 전환은 별도로 확인해야 합니다.

웹 UI를 앱에 맞게 다듬는 로직은 JavaScript로 주입합니다. `.js` 파일을 Embedded Resource로 묶어 `JavaScriptLoader`로 읽고, 페이지 로드 후 `EvaluateScriptAsync`로 실행합니다(헤더와 푸터 제거, 패널 토글, 위치 마커에 방향 표시 추가 등). 반대로 웹에서 일어난 사건(맵 변경, 연결 상태)은 `postMessage`로 보내 `JavascriptMessageReceived`에서 받고, CommunityToolkit.Mvvm의 `WeakReferenceMessenger`로 ViewModel에 전달합니다. C#과 JS의 경계를 메시지로 느슨하게 연결했습니다. 남의 사이트를 앱 안에서 고쳐 쓸 때 쓰는 기법과 겪은 함정은 [임베디드 웹페이지 제어 레퍼런스](docs/20260818-embedded-site-control.md)에 정리했습니다.

### 7. MVVM 아키텍처와 DI

코드비하인드(`*.xaml.cs`)에는 로직을 두지 않는다는 원칙을 지켰습니다. UI 인터랙션은 Microsoft.Xaml.Behaviors 기반 Behavior로 분리하고(창 드래그, 트레이 최소화, 단축키 입력 캡처 등), 데이터와 비즈니스 로직은 ViewModel과 Service에 둡니다. 서비스는 Microsoft.Extensions.DependencyInjection으로 등록하고 `ServiceLocator`로 접근하며, ViewModel 사이 통신은 직접 참조 대신 Messenger로 처리해 결합도를 낮췄습니다.

### 8. 릴리스 자동화 (GitHub Actions + Velopack)

버전 태그(`v1.0.0` 또는 `0.1.0` 형태)를 push하면 GitHub Actions가 self-contained로 publish하고, Velopack(`vpk`)으로 설치 파일과 포터블 zip을 패키징해 GitHub Release에 자동 업로드합니다. 사용자 쪽에서는 앱 시작 시 Velopack `UpdateManager`가 새 버전을 확인하고 조용히 받아 다음 실행에 적용합니다. 빌드부터 배포, 자동 업데이트까지 태그 하나로 이어집니다.

버전을 올릴 때는 `src/TanukiTarkovMap/TanukiTarkovMap.csproj`의 `Version`을 변경하고,
`docs/releases/<Version>.md`에 [release-notes 스킬](.agents/skills/release-notes/SKILL.md)의
작성 기준에 따라 업데이트 내역을 작성합니다.
이 디렉터리의 버전별 파일이 업데이트 이력이며, 배포 시 같은 파일을 GitHub 릴리스 본문과
Velopack 패키지에 함께 넣습니다. 태그와 프로젝트 버전이 다르거나 내역 파일이 없으면
배포를 중단합니다. 로컬 패키징은 프로젝트 버전과 같은 값을 `build.bat <Version>`에 전달합니다.

### 9. 버전 선택과 되돌리기

자동 업데이트는 최신 버전으로만 흐릅니다. 새 버전에서 문제를 만난 사용자가 스스로 빠져나올 길이 없다는 뜻이라, 설정에서 자동 업데이트를 끄고 원하는 버전을 직접 고를 수 있게 했습니다.

여기에는 Velopack의 기본 경로를 쓸 수 없습니다. `GithubSource`는 "최신 릴리스 하나에 모든 패키지가 모여 있다"를 전제로 그 릴리스의 `releases.win.json`만 읽고 다운로드 주소도 그 안에서만 찾습니다. 이 저장소는 전체 패키지가 250MB를 넘어 태그마다 자기 버전만 올리므로, 기본 경로로는 최신과 그 직전까지 두 버전만 보입니다. 그래서 릴리스 목록은 GitHub Releases API로 직접 조회하고, 고른 태그 하나에 고정된 `IUpdateSource`(`GitHubReleaseSource`)를 만들어 Velopack의 다운로드, 체크섬 검증, 적용 절차에 태웁니다.

패키지 메타데이터를 직접 조립하지 않고 릴리스가 이미 담고 있는 피드 JSON을 파싱하는 것도 이 때문입니다. Velopack은 받은 패키지의 SHA를 피드 값과 대조하는데, 손으로 만든 값에는 그 해시가 없어 검증을 통과시킬 방법이 없습니다.

위로 올라갈 때는 그 사이 버전들의 delta를 이어 붙여 받습니다. 전체 패키지가 242MB인데 delta는 한 개에 수백KB라 차이가 큽니다. 되돌릴 때는 언제나 전체 패키지를 받습니다. delta는 올라가는 방향으로만 만들어지기 때문입니다. 사이 릴리스가 지워졌거나, 건너뛸 단계가 너무 많거나, delta를 다 합친 크기가 전체 패키지에 견줘 커지면 그때도 전체를 받습니다. 오래 걸릴 수 있는 작업이라 진행률을 화면에 표시합니다. 다운로드가 끝나도 프로세스를 강제로 끊지 않고, CefSharp가 쿠키와 IndexedDB 파일을 놓도록 정상 종료한 뒤 패키지를 적용합니다.

최신이 아닌 버전을 고르면 자동 업데이트를 함께 끕니다. 켜둔 채로 두면 다음 실행에서 곧바로 최신으로 되돌아가 사용자가 고른 버전이 사라지기 때문입니다.

설정의 실험적 기능에서 베타 받기를 켜면 `v0.1.1-beta`처럼 정식 출시 전 버전도 목록과 자동 업데이트 대상에 들어옵니다. 꺼두면 조회 단계에서 빠지므로 목록에 보이는 것과 자동 업데이트가 따라가는 대상이 언제나 같습니다.

이 차단은 자동 업데이트 설정이 들어간 버전부터 유효합니다. 그보다 오래된 버전으로 내려가면 그 버전의 업데이트 코드가 설정을 보지 않고 최신을 받아 오므로 거기에 머무를 수 없습니다. 이미 배포된 코드는 고칠 수 없어 설계로 막을 방법이 없고, 설정 화면에서 그 사실을 미리 알리는 것으로 대신합니다.

---

## 개발 안내

.NET 8 SDK 설치 후 `src` 폴더에서 `dotnet build`로 빌드할 수 있습니다. 아키텍처와 설계 등 개발 관련 내용은 [`PROJECT.md`](PROJECT.md)를 참고하세요.

---

## License

[MIT License](LICENSE)

> 이 프로젝트는 Battlestate Games 및 Tarkov Market과 제휴 관계가 없는 비공식 도구입니다. 게임 메모리를 읽거나 게임 프로세스에 개입하지 않으며, 스크린샷 파일명(이미지 내용은 읽지 않음)과 맵 이름이 기록된 게임 로그만 읽습니다.

TanukiTarkovMap

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README