COMPASS WAYPOINTS AND CLOCK — 0.1.7 PUBLIC BETA

ZIP-only delivery. Close Valheim before installing the ZIP yourself. No installed
DLLs were modified for this update. Requires BepInEx 5 / BepInExPack_Valheim.
The DLL belongs at BepInEx/plugins/CompassWaypointsClock/CompassWaypointsClock.dll.
Disable the old HUDCompass and Clock Mod to avoid duplicate displays.

MAP CONTROLS — NO WAYPOINT MANAGER
Open the large map, hold Ctrl, and click:
  Ctrl + double-left-click: append a waypoint at the cursor.
  Ctrl + right-click: delete the nearby waypoint.
Placement follows the vanilla double-click gesture with Ctrl held. A single
Ctrl-click gives a reminder instead of placing a waypoint.
Hints, action feedback, filter controls and the remove-visited checkbox are
parented to the large map itself. Filters sit at the map's top left; hints sit
above the native bottom controls. All action feedback is also logged.
Blocked actions report the menu/player condition that prevented placement.
Waypoints are numbered in order. Removing any point closes the gap, retaining
relative order. Ctrl actions never change or delete ordinary saved map pins.
Ordinary map controls and middle-click pings retain their usual behaviour.
F7/feet/aim shortcuts and the manager have been removed.

The map has a 'Remove visited waypoints' checkbox. Checked: reaching the next
point removes it and renumbers the remainder. Unchecked: reached points remain
on the map with a visited mark; guidance advances to the next unvisited point.
After the last point, the retained markers remain and there is no next target.
Deleting a retained marker does not reactivate other completed points. New points
appended afterwards become the next targets.

ARRIVAL AND GUIDANCE
The compass labels the destination "Next Waypoint", with direction and distance.
The next waypoint has a diamond sprite; other route points appear as diamonds
among nearby compass icons, respecting the Waypoints filter and shared range. Map diamonds
remain numbered for route order. Retained visited diamonds are dimmed. Behind-you
targets have edge indicators. Reaching it shows 'Waypoint n reached' and logs that
same message. A short local arrival chime is enabled by default.
[Waypoints] ArrivalChime=false disables it; ArrivalVolume sets volume from 0 to 1
(default 0.5). It plays only when the next waypoint completes, not on placement.
Default arrival radius: 10 metres, with a two-second grace and 0.75-second dwell.
Map placements ignore height. Arrival is suspended while planning on the large
map, while the compass is hidden, and during death, teleporting or cutscenes.
Only the next unvisited waypoint can complete. Maximum 128 points.

CONFIGURATION
BepInEx/config/au.tyvalheim.compasswaypointsclock.cfg
Edit while the game is closed, or use a compatible live configuration manager.
The map checkbox writes AutoRemoveVisited to this same config.

[Display]
ShowCompass = true
ShowClock = true
VagueClock = false
TwelveHourClock = false
CompassColor = #EBD9AD
ClockColor = #EBD9AD
CompassRange = 300
ClockOffset = 50
MarkerMinSize = 0.5
MarkerMaxSize = 1.2

ShowCompass and ShowClock independently select one, both or neither element.
VagueClock=true replaces exact time with Midnight, Late night, Early morning,
Morning, Late morning, Midday, Afternoon, Evening, Late evening or Night.
VagueClock overrides TwelveHourClock. All formats use in-game time.

CompassColor and ClockColor are independent. Accepted formats:
  #RGB, #RGBA, #RRGGBB, #RRGGBBAA (the leading # is optional)
  Examples: #FFFFFF, 00FFFF, #FF8800CC, gold, cyan, ivory
Names are case-insensitive. Common names include white, black, red, green, blue,
yellow, cyan, magenta, orange, purple, silver, grey/gray, navy, teal, gold, amber,
ivory, warm white and transparent. An invalid value falls back to warm white
and produces a logged status message. Alpha is the last component.
CompassColor controls compass text; category colours below control markers.
ClockColor remains independent. Native saved-pin artwork can influence tint.

CompassRange is the SINGLE distance limit for every compass marker category.
It defaults to 300 metres, including waypoints. Map visibility is not range-limited.
ClockOffset controls the clock's distance below the compass (default 50 reference
pixels, previously 58). Smaller values raise it. Clock-only mode stays at the HUD
origin. Every compass icon uses the same configurable smooth distance scaling: by default, 50% of its
original size at the shared range limit, growing to 120% up close (85% halfway).
MarkerMinSize and MarkerMaxSize are GLOBAL bounds, not per-type settings.
For example, 0.1 and 2.0 give 10% size at the range limit and 200% up close.
Allowed values are 0.05 to 5. Equal bounds give fixed-size icons; reversed bounds
are treated in ascending order. Changes apply live in a configuration manager.
The obsolete MarkerScale multiplier is removed automatically on startup.
Waypoint diamonds use the same rule. Map icons and text sizes are unchanged.

Other settings retain camera/player heading, scale and top offset. Under [Waypoints], Enabled controls route functionality,
AutoRemoveVisited controls retention, and ArrivalRadius controls arrival distance.
On startup, obsolete Controls/RouteManager, AddAtFeet, AddAtAim, AutomaticArrival
and per-category CompassRange keys are removed from the config. Existing supported
filters and colours remain intact. Old ranges do not override the new 300m default;
a later choice for Display/CompassRange is preserved on subsequent launches.

OBJECT MARKERS AND FILTERS
Ships, carts and portals encountered by your client get separate map markers.
All categories default visible on both map and compass. Ships are yellow,
carts are cyan, and portals
are red and visible. Portal labels use their tags. These are encountered objects,
not an ownership list; objects discovered around other players' bases can appear.

Open the large map and click 'Marker filters'. Each category has independent
Map and Compass checkboxes: Ships, Carts, Portals, Waypoints, Saved pins, Beds,
Bosses, Deaths, Players, Events, Pings, Locations and Other icons.
These choices persist in the existing config. Hiding a category does not delete
its objects, saved pins or waypoints. Saved pins are a single category; the game's
native map icon filters still apply. Existing native dynamic icons (such as your
bed) now appear on the compass too. Other mods' native map pins are grouped by
their icon type; custom/unknown types use Other icons. No pins are deleted.

Each [Markers - <category>] config section contains:
  ShowOnMap / ShowOnCompass: independent visibility switches.
  Color: the same hex/name formats listed above; applies to map icons and labels
    and compass markers. Example: yellow or #FFFF00 for Ships.
The compass shows up to 16 nearby object/saved-pin markers
within its forward arc, plus the next waypoint. Filters act before this limit.
Only icons already known to the map are used: this does not discover unexplored
bosses, every bed in the world, or players who have not shared their position.
Checked pins and area-only circles are omitted from the compass.
The old Display/ShowMapPins value supplies the initial SavedPins compass setting
when upgrading. Waypoint/saved-pin colours initially inherit CompassColor.

Loaded objects update four times per second. When an object leaves the loaded
area, its marker becomes a dimmed 'last seen' position. This is not global live
tracking: another player can move or destroy an object while you are away/offline.
Received destruction notifications remove markers; otherwise a stale position
can persist until the client learns more. Never interpret it as a live guarantee.

Remembered objects use separate per-character/per-world .objects files beside
route files, with checksums, atomic writes and backup recovery. Cache limit: 4096
objects; map display limit: 512 markers, with ships before portals and carts.
No game world objects or server settings are changed. Marker artwork is original,
generated by this mod. Existing tracking mods may produce duplicate markers;
disable their relevant category if you prefer this mod's markers.

TEST THIS UPDATE
- Find a ship, cart and portal. Hide carts on the map and leave ships visible.
- Independently toggle their compass columns and test near/far range settings.
- Change category colours; verify normal native pins can still be used.
- Move objects, leave the area, reconnect, and check live/last-seen behaviour.
- In multiplayer, ask another player to move/destroy a loaded ship or cart.
  Preserve LogOutput.log for failures. This acceptance has not been performed here.

STORAGE AND UPGRADING
Routes remain per character/world under:
BepInEx/config/CompassWaypointsClock/<world>-<character>.cwc
This version reads 0.1.0 routes and preserves their points. Legacy manager-paused
routes resume; archived route templates remain stored but have no manager UI.
The new format persists visited state. Back up your route directory before
upgrading if you may revert: version 0.1.0 cannot read files written by 0.1.1.
Atomic writes, checksums, validation and backup recovery remain in place.
If both storage copies are invalid, route editing is disabled without overwriting
them. Compass and clock remain available. Native saved map pins are never removed.

DIAGNOSTICS AND TEST STATUS
DetailedLogging defaults to true. User-facing messages always log, regardless of
that switch. Preserve BepInEx/LogOutput.log after any issue, before relaunching.
55 executable route/time/storage checks passed. See TEST-RESULTS.txt for the
current isolated Unity results,
covering map action dispatch, deletion/renumbering, retained visits, v1 migration,
map toggle callbacks, colour parsing/application, and actual UI rendering.
These tests do not replace live Valheim mouse input/multiplayer acceptance.

Please test: Ctrl-add three points, delete the middle, reach the next; switch
retention and confirm visited points stay without repeat toasts; reconnect; check
ordinary pins and the Fifth Beacon are unaffected. Try vague time and two different
colours. This test ZIP currently uses keyboard/mouse placement.
Gamepad support is a roadmap feature and is not implemented in this beta.
Multiplayer coexistence needs further acceptance; live mixed-client and
dedicated-server testing remains outstanding. See RELEASE-REQUIREMENTS.txt.

The Fifth Beacon is separate. Optional NavigationApi v1 snapshot/append hooks
remain available for a later adapter. Network route sharing is not implemented.
See CREDITS.txt. Native fonts/icons are referenced at runtime, not packaged.











