> For the complete documentation index, see [llms.txt](https://malbersanimations.gitbook.io/animal-controller/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://malbersanimations.gitbook.io/animal-controller/malbers-questforge/minimap/minimap-ui-manager.md). # Minimap UI (Manager) ### Overview **MinimapUI** is a MonoBehaviour that renders a real-time top-down minimap in your game's HUD. It handles the full pipeline: scrolling or live-camera map display, a player position indicator with directional arrow, a camera-facing direction cone, POI icons sourced from the **POIManager**, a dotted path system drawing routes to active quest objectives and player-placed waypoints, and a current location name display fed by the **LocationManager**. The component supports two map rendering modes — a **live top-down camera** feeding into a RenderTexture for fully dynamic scenes, or a **static pre-baked texture** that pans and zooms via UV manipulation for better performance on large open worlds. Both modes use the same coordinate system, and their **World Size** and **World Center** values must stay in sync with any **WorldMapUI** in the same scene. All runtime elements — player indicator, camera direction cone, POI icon pool, and path dot pool — are instantiated as children of the **Minimap Container** at Start. The entire update cycle runs in `LateUpdate()` so it resolves after all character and camera movement for that frame.
### Required UI Structure The component expects the following Unity UI hierarchy at a minimum: ``` MinimapRoot (Canvas or Panel) └─ MinimapContainer (RectTransform) ← Minimap Container field └─ MapRenderer (RawImage) ← Map Renderer field ``` All runtime-created elements (player indicator, camera cone, POI icons, path dots) are instantiated as children of **Minimap Container** at Start. *** ### Properties **Minimap Settings** | Property | Type | Default | Description | | --------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Minimap Container** | `RectTransform` | Required | The root RectTransform for all minimap UI elements. POI icons, path dots, the camera cone, and the player indicator are all parented here at runtime. | | **Map Renderer** | `RawImage` | Required | The `RawImage` that displays the map — either a live `RenderTexture` from the minimap camera, or a scrolling static texture. | | **Map Radius** | Float | `100` | How many world units are represented from the centre of the minimap to its edge. Controls the visible area and scales all world-to-minimap coordinate conversions. | | **Map Zoom** | Float | `1.0` | Zoom multiplier on top of map radius. Values above `1.0` zoom out (show more world); values below zoom in. Clamped to `0.5–3.0`. Adjusts the camera's orthographic size (live mode) or the UV rect width (static mode). | *** **Rotation Settings** > **Note:** Map rotation (**Rotate With Player** and **Rotate With Camera**) is currently disabled in the Inspector and reserved for a future update. The minimap always renders **north-up**. Directional awareness is provided instead by the **Camera Direction Cone** and the rotating player indicator. | Property | Type | Default | Description | | -------------------- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Auto Find Camera** | Bool | `true` | When the Camera Direction Cone is enabled, automatically locates `Camera.main` at Start. If `false`, or if a manual reference is needed, assign **Camera Transform** directly. | | **Camera Transform** | `TransformReference` | None | Explicit reference to the camera used for the direction cone. Only shown when **Auto Find Camera** is off, or when a `TransformReference` variable asset is preferred. | *** **Player Indicator** | Property | Type | Default | Description | | ---------------------- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Player Icon Prefab** | `GameObject` | None | Prefab instantiated as the player's dot on the minimap. The instance is parented to the Minimap Container and positioned at `(0, 0)` when **Center On Player** is `true`. Its rotation is updated every `LateUpdate` to match the player's world Y angle (north-up mode). | | **Player Transform** | `TransformReference` | Auto | The player's Transform. Falls back to `GameObject.FindGameObjectWithTag("Player")` at Start if empty. | | **Center On Player** | Bool | `true` | Keeps the player indicator fixed at the centre of the minimap and instead scrolls the map beneath it. | *** **Camera Direction Cone** A Genshin Impact-style translucent wedge overlaid on the player indicator showing which direction the camera is currently facing. | Property | Type | Default | Description | | ----------------------- | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Show Direction Cone** | Bool | `true` | Enables the cone. When `true`, a child GameObject named `"CameraDirectionCone"` is created inside the Minimap Container at Start, placed behind the player indicator in the sibling order. | | **Cone Sprite** | Sprite | None | Optional wedge or triangle sprite used as the cone's visual. If left blank, a **procedural `ConeGraphic`** is generated at runtime using the arc angle. | | **Cone Color** | Color | White, 15% alpha | Tint and transparency of the cone. | | **Cone Scale** | Float *(0.2–1.0)* | `0.6` | Size of the cone relative to the minimap's pixel radius. A value of `0.6` means the cone extends 60% of the way to the minimap edge. | | **Arc Angle** | Float *(30–120°)* | `60` | The angular width of the cone in degrees. Only applied to the procedural fallback — sprite-based cones are shaped by the sprite itself. | **Cone rotation logic (north-up map):** * In the default north-up configuration, the cone's local rotation is set to `-cameraTransform.eulerAngles.y` each `LateUpdate`, so it always points in the camera's current facing direction relative to north. *** **POI Icons** | Property | Type | Default | Description | | --------------------- | ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **POI Icon Prefab** | `GameObject` | None | Prefab for POI markers. Must have an `Image` component for the icon sprite. An optional child `Text` component displays the POI name when the icon is within 80% of the minimap radius. | | **Max Icons** | Int | `20` | Hard cap on simultaneously visible POI icons. A pool of this many instances is pre-created at Start. POIs beyond the cap are silently omitted. | | **Scale By Distance** | Bool | `true` | Linearly scales each icon between **Icon Min Scale** and **Icon Max Scale** based on world distance — closest icons are largest. | | **Icon Min Scale** | Float | `0.5` | Scale applied to icons at the outer edge of the map radius. | | **Icon Max Scale** | Float | `1.5` | Scale applied to icons at the centre (distance ≈ 0). | **Icon placement and clamping:** * World offset from player is projected to minimap space using `offset * (minimapRadius / mapRadius)`. * Icons beyond the map radius are skipped entirely. * Icons within range but near the edge are **clamped with 10px padding** — on circular maps they are pulled to the inner edge of the circle; on square maps they are clamped per-axis. This ensures icons always remain fully inside the minimap frame. * Icon sprite and colour are read from `IPOITarget.MapIcon` and `IPOITarget.IconColor`. *** ### **Map Rendering** The minimap supports **two mutually exclusive rendering modes**. If both are configured, the live camera takes priority. Exactly one must be assigned — the Inspector shows an error if neither is set. **Option 1 — Live Camera Rendering** | Property | Type | Description | | ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Minimap Camera** | `TransformReference` | A reference to the Transform of a top-down orthographic Camera GameObject. At Start, the camera's `targetTexture` is set to the Render Texture and the Map Renderer's texture is pointed at it. | | **Render Texture** | `RenderTexture` | The RenderTexture asset the minimap camera renders into. Must be pre-created and assigned to both this field and the camera. | In live mode, `UpdateMapPosition()` moves the minimap camera's XZ position to match the player each `LateUpdate`, keeping its Y at its configured height. The camera's orthographic size is adjusted by `SetZoom()` to match `mapRadius / mapZoom`. **Option 2 — Static Map Texture** | Property | Type | Description | | ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Static Map Texture** | `Texture2D` | A pre-baked top-down map image. The component scrolls the texture by adjusting the `RawImage.uvRect` each frame. | | **Texture Scale** | Float | Additional zoom multiplier for fine-tuning the visible area without changing Map Radius. | | **World Size** | `Vector2` | Total world extent in units: `X` = width (east–west, world X axis), `Y` = depth (north–south, world Z axis). **Must match WorldMapUI's World Size if both components are in the same scene.** | | **World Center** | `Vector2` | World-space centre of the map texture: `X` = world X centre, `Y` = world Z centre. **Must match WorldMapUI's World Center.** | **UV calculation (static mode):** ``` visibleFractionX = (mapRadius * 2) / worldSize.x * mapZoom * textureScale uvCenterX = (player.x - worldCenter.x) / worldSize.x + 0.5 uvRect = Rect(uvCenterX - visibleFractionX/2, uvCenterZ - visibleFractionZ/2, visibleFractionX, visibleFractionZ) ``` The UV rect scrolls smoothly as the player moves, keeping the player's position centred in the texture viewport. *** **Visual Settings** | Property | Type | Default | Description | | ------------------------ | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Border Image** | `Image` | None | Optional decorative border or frame Image drawn over the minimap. | | **Use Circular Minimap** | Bool | `true` | Applies a Unity `Mask` component to the Minimap Container using the **Circular Mask** sprite. The mask's `showMaskGraphic` is set to `false` so only the mask shape is used, not its visual. | | **Circular Mask** | Sprite | None | A circular sprite used as the mask shape. Only shown when **Use Circular Minimap** is enabled. | *** **North Indicator** | Property | Type | Default | Description | | ---------------------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **North Indicator** | `GameObject` | None | A UI element (e.g. a small "N" label or arrow) that orbits the minimap centre indicating true north. Only active when map rotation is enabled. | | **Indicator Distance** | Float | `90` | Pixel radius from the minimap centre at which the north indicator is placed. | > The north indicator only moves when map rotation is active. In the current version (north-up only), it remains stationary. *** **Current Location Display** When enabled, displays the name of the `PointOfInterest` location the player is currently inside — sourced from the **LocationManager** — above or near the minimap. | Property | Type | Default | Description | | ------------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Show Current Location** | Bool | `true` | Enables the location display. Subscribes to `LocationManager.OnCurrentLocationChanged` at Start. | | **Location Text** | `TextMeshProUGUI` | Required | The text component that shows the location name. | | **Location Container** | `GameObject` | None | Optional parent GameObject for the location UI. Hidden when no location is active and **Default Text** is empty. | | **Location Prefix** | String | `""` | Text prepended to the location name (e.g. `"Location: "`). | | **Default Text** | String | `""` | Text shown when the player is not inside any named location. If left empty and the player exits all locations, the **Location Container** is hidden instead. | | **Fade Duration** | Float | `0.3` | Duration of the cross-fade transition when the location changes. The text fades out over half the duration, updates, then fades back in. A `CanvasGroup` is auto-added to the text component if needed. Set to `0` for an instant swap. | *** **Quest Objective Path Drawing** Draws a dotted path on the minimap from the player toward active quest objective locations. | Property | Type | Default | Description | | --------------------------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Enable Path Drawing** | Bool | `true` | Master toggle. When disabled, all path dots are hidden and `DrawPathsToObjectives()` is skipped. | | **Only Tracked Objectives** | Bool | `true` | When `true`, only draws paths to objectives from the currently tracked quest (`QuestManager.GetTrackedObjectives()`). When `false`, draws to all active objective locations. | | **Draw To Closest** | Bool | `false` | When `true` (and **Only Tracked** is `false`), draws a path to only the single closest objective (`QuestManager.GetClosestObjective()`). | | **Path Color** | Color | Yellow | Colour of quest objective path dots. | | **Use Dotted Line** | Bool | `true` | Renders the path as evenly spaced dots. When `false`, a solid line is drawn (requires a `LineRenderer`). | | **Dot Spacing** | Float | `10` | Pixel distance between dot centres along the path. Only used when **Use Dotted Line** is `true`. | | **Dot Size** | Float | `3` | Pixel size of each circular dot. Only used when **Use Dotted Line** is `true`. | | **Path Width** | Float | `2` | Line width in pixels. Only used when **Use Dotted Line** is `false`. | | **Animate Path** | Bool | `true` | Advances an `animationOffset` each frame at **Animation Speed**, causing dots to appear to flow toward the objective. | | **Animation Speed** | Float | `20` | Pixels per second the dot pattern advances. Only used when **Animate Path** is `true`. | | **Use NavMesh** | Bool | `false` | When `true`, calculates path points using `NavMesh.CalculatePath()` so the path follows walkable terrain. When `false`, a straight line from player to objective is used. Falls back to a straight line if NavMesh calculation fails. | | **Max Path Points** | Int | `50` | Maximum NavMesh path corners to process. | | **Show Waypoint Path** | Bool | `true` | Draws a second distinct dotted path to the active navigation waypoint set via the world map. | | **Waypoint Path Colour** | Color | Cyan | Colour of the waypoint navigation path. Should differ from **Path Color** so the two paths are visually distinct. | **Path dot pool:** 80 dot GameObjects are pre-created at Start and parented to the Minimap Container. The first \~50 slots are used for quest objective paths; the remaining \~30 are available for the waypoint path. All dots are hidden at the start of each `LateUpdate` and re-enabled as needed. **Path clipping:** Before drawing, each path segment is clipped to the minimap bounds: * **Circular minimap** — parametric line–circle intersection clips segments to the circular boundary. * **Square minimap** — Cohen–Sutherland algorithm clips segments to the rectangular boundary. Dots that fall outside the clipped segment are skipped. A 5px inner padding prevents dots from being drawn right on the edge. *** ### Update Loop All per-frame logic runs in `LateUpdate()` in this order: 1. **UpdateMapPosition** — Moves the minimap camera XZ (live mode) or recalculates the UV rect (static mode). 2. **UpdateMapRotation** — Applies container rotation if map rotation is enabled; always updates the camera direction cone and player indicator arrow. 3. **UpdatePOIIcons** — Fetches all active `IPOITarget`s from POIManager, culls by distance, pools and positions icons. 4. **UpdateNorthIndicator** — Orbits the north indicator if rotation is active. 5. **UpdatePathAnimation** — Advances `animationOffset` by `deltaTime * animationSpeed`. 6. **DrawPathsToObjectives** — Hides all dots, re-evaluates objectives, clips and draws quest paths then waypoint path. *** ### Public API | Method | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SetZoom(float zoom)` | Sets `mapZoom` clamped to `0.5–3.0`. Adjusts camera orthographic size for live mode; UV rect recalculates automatically on next `LateUpdate` for static mode. | | `ZoomIn()` | Calls `SetZoom(mapZoom + 0.25f)`. | | `ZoomOut()` | Calls `SetZoom(mapZoom - 0.25f)`. | | `ToggleRotation()` | Toggles `rotateWithPlayer`. Resets container rotation to identity when both rotation flags become `false`. | | `SetRotateWithPlayer(bool)` | Enables or disables player-relative rotation. Disables camera rotation if `true`. | | `SetRotateWithCamera(bool)` | Enables or disables camera-relative rotation. Disables player rotation if `true`. Triggers camera auto-find if needed. | | `SetCameraTransform(Transform)` | Sets the camera reference at runtime. Useful for cameras that change at scene load. | | `SetPathDrawingEnabled(bool)` | Enables or disables path drawing and hides all dots immediately when disabled. | | `SetPathColor(Color)` | Updates `pathColor` and recolours all pooled dot instances immediately. | | `SetOnlyTracked(bool)` | Sets the **Only Tracked Objectives** flag at runtime. | *** ### Inspector Testing Tools *(Play Mode Only)* | Button | Action | | ------------------- | ------------------------- | | **Zoom In** | Calls `ZoomIn()`. | | **Zoom Out** | Calls `ZoomOut()`. | | **Toggle Rotation** | Calls `ToggleRotation()`. | *** ### Setup Checklist * [ ] Run the One-Click Setup from the QuestForge Helper Tools! * [ ] Assign **Minimap Container** (a `RectTransform` inside your Canvas). * [ ] Assign **Map Renderer** (a `RawImage` inside the container). * [ ] Choose a rendering mode: * **Live Camera (Recommended!):** Create a top-down orthographic Camera, create a `RenderTexture` asset, assign both to **Minimap Camera** and **Render Texture**. * **Static Texture:** Assign a **Static Map Texture**, set **World Size** to match your world dimensions, and set **World Center** to your world's XZ centre. * [ ] Create a **Player Indicator Prefab** (a small Image) and assign it. * [ ] Create a **POI Icon Prefab** (an Image with an optional child Text) and assign it. * [ ] If using a circular minimap, assign a circular **Circular Mask** sprite and enable **Use Circular Minimap**. * [ ] If using static map texture, ensure **World Size** and **World Center** match any **WorldMapUI** in the same scene. *** ### Usage Tips * **Static vs live camera** — Static texture is the higher-performance choice for large open worlds; a live minimap camera adds a real-time top-down render pass each frame. For most games, static is preferred. * **World Size and Center alignment** — If your world is 2000×2000 units centred at the origin, set `worldSize = (2000, 2000)` and `worldCenter = (0, 0)`. If the map is offset (e.g. the terrain starts at `(-500, -300)` in world space), set `worldCenter` to the terrain's XZ midpoint. * **Map Radius tuning** — Start with a radius equal to roughly 10–15% of your world's width. Too small and the player can barely see ahead; too large and icons become tiny and indistinct. * **NavMesh paths** — Enable **Use NavMesh** only if your walkable areas are fully baked. On large open worlds a straight-line path is often cleaner and more readable on the minimap than a jagged NavMesh route. * **Quest vs waypoint path colours** — Keep **Path Color** and **Waypoint Path Color** visually distinct. A warm colour (yellow/orange) for quest objectives and a cool colour (cyan/blue) for the player-placed waypoint is a common convention. * **Dot pool size** — 80 dots are pre-allocated. If you have multiple active quest objectives each with long paths, you may exhaust the pool. Reduce **Dot Spacing** to fit more dots per path, or reduce **Max Path Points** to shorten NavMesh paths. * **Camera direction cone** — If no **Cone Sprite** is assigned, a procedural cone is generated. For a polished look, create a simple white wedge sprite and assign it — it gives you full control over the shape, feathering, and transparency via the **Cone Color** alpha. * **Debug mode** — Enable **Debug Mode** during development to log coordinate conversions, camera reference resolution, and pool activity. Be aware that the POI position debug log in the update loop is intentionally commented out by default as it spams heavily — enable it only as a last resort for icon placement issues.