QD_MapLink - live position for the Queen's Domain maps
=======================================================

Shows a "you are here" arrow on the Queen's Domain maps (https://acranon.github.io/queenscompanion/map/) that follows you
while you play, e.g. with the map open on a second monitor. Unofficial fan-made mod; it only reads your
position and save and changes nothing in the game or your saves.


What you need
-------------
- Windows 10 or 11 (nothing else to install; the helper uses the built-in Windows PowerShell).
- UE4SS for Queen's Domain, experimental build (tested with v3.0.1 experimental). It is not included here.
  Get it from the UE4SS releases page:  https://github.com/UE4SS-RE/RE-UE4SS/releases
  (the "experimental" release; follow its install guide: the files go next to the game's .exe).
- A desktop browser: Chrome, Edge or Firefox.


Install
-------
1. If Windows marks the download as "from the internet": right-click QD_MapLink.zip > Properties >
   tick "Unblock" > OK, before unzipping.
2. Copy the QD_MapLink folder from this zip into the UE4SS Mods folder:
     ...\steamapps\common\QueensDomain\QueensDomain\Binaries\Win64\ue4ss\Mods\QD_MapLink\
   (older UE4SS layouts: ...\Binaries\Win64\Mods\QD_MapLink\)
   so that this file exists:
     ...\Mods\QD_MapLink\Scripts\main.lua
3. The folder already contains an empty file named enabled.txt, which tells UE4SS to load the mod.
   (Delete enabled.txt to switch the mod off.)


Use
---
1. Start the game. The mod starts a small helper in the background (you may see a window flash briefly
   at game start).
2. Open a map, click "Live position..." at the bottom of the left panel and tick "show where I am".
   The page remembers this.
3. Chrome/Edge may ask whether the site may "access other apps and services on this device" or
   "devices on your local network": allow it. That is how the page reaches the helper on your own PC.
4. In the game, once you are in the world, the map shows a blue arrow where you are, pointing where you
   look. "follow" keeps the map centred on you (dragging the map turns it off), "auto floor" switches the
   height cut to the floor you are on. If you are in a different area, the map shows a link to that map.
   The 3D view shows a blue cone.
5. "Collected" (in the left panel, once the helper is found): the map reads your newest save and dims (or
   hides) what you have already opened, picked up, broken, killed or read; the marker numbers become
   done / tracked. A dashed yellow ring marks things you left behind: a meal ticket next to food you ate,
   or a loot lizard's sack still lying on the ground. The game only saves about every 2 minutes (and when
   you rest), so the mod also passes on what you open, break, pick up or read right away: the map updates
   within a few seconds and the panel says "live (save from <time> + N changes)". After a death the game
   goes back to your last rest, and so does the map.


How it works / privacy
----------------------
- The mod writes your position (x, y, z, facing, loaded level names) about 5 times a second to
    %TEMP%\QD_MapLink_position.json
- The helper (QD_MapLink\helper\maplink_server.ps1) serves that file at
    http://127.0.0.1:47615/position
  It listens on 127.0.0.1 only: other computers cannot reach it and nothing is sent over the internet.
  It only answers that address (read-only), and only lets the map site (acranon.github.io) and map pages opened
  from your own disk read it.
- Port: 47615. If something else uses that port the helper quietly does nothing.
- For "Collected", the helper also reads your save files (read-only; it never writes or locks them):
    %LOCALAPPDATA%\QueensDomain\Saved\SaveGames\<id>\World0.sav and World0_Suspend_0/1.sav
  and serves what they record at http://127.0.0.1:47615/state (same rules as above). What changed since
  the last save (opened / broken / picked up / read, as the game records it) the mod writes to
    %TEMP%\QD_MapLink_delta.json
  and the helper adds it to /state.
- The helper closes by itself about 10 seconds after the game exits.


Troubleshooting
---------------
- The map says "looking for the game on this PC": the helper isn't running. Double-click
  QD_MapLink\helper\start_helper.bat (keep its window open while you play), then reload the map.
  Check the UE4SS log (UE4SS.log) for lines starting with [QD_MapLink].
- The map says "helper running, waiting for the game": you are in a menu or loading screen, or the mod
  isn't loaded (check that enabled.txt is there and UE4SS is installed).
- Nothing at all in the browser: make sure you allowed local network access for the site (click the icon
  left of the address bar > Site settings), and that you use http://127.0.0.1 and not a different PC.
- Turn the feature off on the map page by unticking "show where I am".
