> 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/points-of-interest/point-of-interest-scriptable-object.md).

# Point of Interest Scriptable Object

### Overview

The **Point of Interest** (POI) ScriptableObject is the data asset at the heart of Quest Forge's navigation systems. Every icon that appears on the minimap, compass bar, or as a world-space marker is driven by one of these assets. A single POI asset is shared across every system simultaneously — assign it to a `POIMarker` component in the scene and the icon appears on the minimap, compass, and world map with no additional configuration.

POIs are organised by **Category**, which determines how they are filtered on the world map and minimap, and how they integrate with the quest and location systems. The special **Location** category unlocks an extended set of fields that power the discovery system, fast travel, fog-of-war reveal, and hierarchical location trees (e.g. a city as the parent of named buildings within it).

Creating and configuring POI assets is entirely done in the Project window — no scene setup is required for the asset itself.

<figure><img src="/files/4YQDfbppAPOWsRDf9Tmd" alt=""><figcaption></figcaption></figure>

***

### Creating a POI Asset

**Right-click in the Project window → Create → Malbers Quest Forge → POI → Point of Interest**

Give the asset a descriptive name in the Project panel (e.g. `POI_Whiterun`, `POI_QuestGiver_Aldric`). The asset name is separate from the display name shown on screen.

***

### Inspector Sections

#### POI Information

The core identity of this point of interest.

| Property        | Type               | Description                                                                         |
| --------------- | ------------------ | ----------------------------------------------------------------------------------- |
| **POI Name**    | string             | The display name shown in tooltips, the world map, and any UI that reads `POIName`. |
| **Description** | string (multiline) | Optional flavour text displayed in map tooltips and discovery pop-ups.              |
| **Category**    | POICategory        | Classifies this POI for filtering and system integration (see Categories below).    |

The inspector shows a live summary line beneath these fields confirming the name and category, or a warning if the name field is left blank.

***

#### Visual Settings

Controls the icons displayed by every system that reads this POI.

| Property         | Type   | Description                                                                                   |
| ---------------- | ------ | --------------------------------------------------------------------------------------------- |
| **Map Icon**     | Sprite | Icon used on the **minimap** and **world map**.                                               |
| **Compass Icon** | Sprite | Icon used on the **compass bar**. Can differ from the map icon for legibility at small sizes. |
| **Icon Color**   | Color  | Tint applied to both icons wherever they appear. Default: white (no tint).                    |
| **Icon Scale**   | float  | Uniform size multiplier. 1 = default size as configured on the map/minimap component.         |

> **Live Preview** — When either icon slot is filled, the editor renders a 32 × 32 tinted preview of each sprite inline, labelled "Minimap" and "Compass". If both slots are empty a warning is shown, because the POI will be invisible in all navigation UIs.

***

#### Display Settings

Independently toggles which navigation surfaces show this POI and how far away it is visible.

| Property              | Type  | Default | Description                                                                                                                                                         |
| --------------------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show on Minimap**   | bool  | true    | Include this POI in the minimap icon pool.                                                                                                                          |
| **Show on Compass**   | bool  | true    | Include this POI on the compass bar.                                                                                                                                |
| **Show World Marker** | bool  | true    | Render a 3D world-space marker above the object.                                                                                                                    |
| **Show Distance**     | bool  | true    | Append a distance readout to the POI label where supported.                                                                                                         |
| **Min Distance**      | float | 5       | The player must be **at least** this many world units away before the icon appears. Prevents icons from appearing when the player is standing on top of the object. |
| **Max Distance**      | float | 100     | The player must be **within** this many world units for the icon to appear.                                                                                         |

The inspector confirms the visible range in a summary line (e.g. *Visible between 5 m and 100 m*) and warns if Min Distance ≥ Max Distance. A second summary shows which surfaces the icon is active on; all three off triggers a warning.

***

#### Priority Settings

Controls draw order and distance exemption.

| Property        | Type | Default | Description                                                                                                                                                             |
| --------------- | ---- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Priority**    | int  | 0       | Higher values cause this POI's icon to render on top of lower-priority POIs when they overlap. Quest objectives typically use priority 10; general world markers use 0. |
| **Always Show** | bool | false   | When enabled, Min/Max Display Distance are ignored and the icon is visible at any range. Use for critical quest markers or named cities.                                |

***

#### Location Settings *(only visible when Category = Location)*

When you set **Category** to `Location`, a dedicated section appears with fields for the discovery and fast-travel systems. These fields are not present or relevant for any other category.

| Property                  | Type            | Description                                                                                                                                                                                                                                                                                                                    |
| ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Enable Fast Travel**    | bool            | When true, the player can warp to this location from the World Map. Requires `WorldMapFastTravel` to be configured in the scene.                                                                                                                                                                                               |
| **Location ID**           | string          | A unique string identifier used by the save system and quest objective matching. If left empty, an ID is **auto-generated** by lowercasing the POI Name and replacing spaces with underscores (e.g. `"Iron Mine"` → `"iron_mine"`). The auto-generated ID is previewed in the inspector so you can verify it before deploying. |
| **World Position**        | Vector3         | The canonical world-space position of this location. This field is **read-only** in the inspector — it is set by clicking **Sync World Position to Asset** on the `POIMarker` component placed in the scene. The inspector shows a formatted coordinate readout, or a warning if still at (0, 0, 0).                           |
| **Location Radius**       | float           | Radius in world units defining the location's trigger area. When a player-controlled object enters this radius, the `LocationManager` marks the location as discovered. Must be greater than 0.                                                                                                                                |
| **Is Discoverable**       | bool            | When enabled, this location participates in the discovery system — it starts undiscovered and triggers discovery events when first entered. Disable for locations that are always considered known (e.g. a starting village).                                                                                                  |
| **Hide Until Discovered** | bool            | *(Only shown when Is Discoverable is enabled)* Suppresses the minimap and compass icons until the player has discovered this location for the first time. This keeps unexplored areas clean.                                                                                                                                   |
| **Location Type**         | LocationType    | Classifies this location for filtering and UI display (see Location Types below).                                                                                                                                                                                                                                              |
| **Parent Location**       | PointOfInterest | An optional reference to another Location-category POI that acts as a parent in a hierarchy. For example, `POI_Dragonsreach` would reference `POI_Whiterun` as its parent. Used by UI to build region trees.                                                                                                                   |

> **Location Summary Box** — The inspector renders a compact summary at the bottom of the Location Settings section: Type, discoverable status, marker visibility rules, fast travel state, trigger radius, and parent name (if set). This gives a quick at-a-glance confirmation of all discovery settings.

***

### POI Categories

The **Category** field classifies the purpose of this POI. The minimap, world map, and POI Filter Manager use the category to group and filter icons.

| Category         | Typical Use                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `QuestObjective` | Active quest target (interact point, kill target area, delivery spot). |
| `QuestGiver`     | NPC or object that starts a quest.                                     |
| `Waypoint`       | Player-placed or system-placed navigation points.                      |
| `Location`       | Named discoverable place (unlocks Location Settings section).          |
| `Enemy`          | Hostile character or creature that should appear on maps.              |
| `NPC`            | Friendly or neutral characters of interest.                            |
| `Item`           | Notable collectible or loot location.                                  |
| `Merchant`       | Shop or trader location.                                               |
| `FastTravel`     | Dedicated fast-travel node (e.g. a stable or shrine).                  |
| `Custom`         | Catch-all for any gameplay-specific classification not covered above.  |

***

### Location Types

Available when Category is set to **Location**. Used for filtering and UI categorisation.

`City` · `Village` · `Town` · `Dungeon` · `Cave` · `Ruins` · `Landmark` · `Camp` · `Fort` · `Tower` · `Shrine` · `Forest` · `Mountain` · `Lake` · `Other`

***

### POI Summary & Quick Actions

At the bottom of every POI inspector (regardless of category), a **POI Summary** box shows:

* **Name** and **Category**
* **Priority** value
* **Visibility** — which surfaces are active and the distance range (or "ALWAYS VISIBLE" if Always Show is on)

Two **Quick Action** buttons sit below the summary:

| Button              | Effect                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| **Show Everywhere** | Sets ShowOnMinimap, ShowOnCompass, and ShowWorldMarker all to true in one click.                        |
| **Hide Everywhere** | Sets all three visibility flags to false. Useful for temporarily suppressing a POI without deleting it. |

***

### Public API

These properties and methods are available at runtime via script.

#### Read-Only Properties

| Member                | Returns         | Description                                                  |
| --------------------- | --------------- | ------------------------------------------------------------ |
| `POIName`             | string          | Display name.                                                |
| `Description`         | string          | Tooltip/discovery text.                                      |
| `Category`            | POICategory     | The category enum value.                                     |
| `MapIcon`             | Sprite          | The minimap/world-map sprite.                                |
| `CompassIcon`         | Sprite          | The compass-bar sprite.                                      |
| `IconColor`           | Color           | Tint colour for all icons.                                   |
| `IconScale`           | float           | Size multiplier.                                             |
| `ShowOnMinimap`       | bool            | Whether to render on the minimap.                            |
| `ShowOnCompass`       | bool            | Whether to render on the compass.                            |
| `ShowWorldMarker`     | bool            | Whether to render a world-space marker.                      |
| `ShowDistance`        | bool            | Whether to append a distance label.                          |
| `MinDisplayDistance`  | float           | Near clip distance.                                          |
| `MaxDisplayDistance`  | float           | Far clip distance.                                           |
| `Priority`            | int             | Render priority (higher = in front).                         |
| `AlwaysShow`          | bool            | Distance limits bypassed when true.                          |
| `IsLocation`          | bool            | True when `Category == POICategory.Location`.                |
| `LocationId`          | string          | Auto-generates from name if the `locationId` field is empty. |
| `WorldPosition`       | Vector3         | Canonical world position set via POIMarker sync.             |
| `LocationRadius`      | float           | Discovery trigger radius in world units.                     |
| `IsDiscoverable`      | bool            | Whether the location participates in the discovery system.   |
| `HideUntilDiscovered` | bool            | Whether the marker is hidden before first discovery.         |
| `LocationTypeValue`   | LocationType    | The location type enum value.                                |
| `ParentLocation`      | PointOfInterest | Reference to a parent POI, or null.                          |
| `EnableFastTravel`    | bool            | Whether fast travel to this location is permitted.           |

#### Methods

| Method                               | Description                                                                                                                                                                         |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SetWorldPosition(Vector3 position)` | Writes the `worldPosition` field. Called automatically by the **POIMarker** editor's **Sync World Position to Asset** button — prefer using that button over calling this directly. |
| `SetLocationId(string id)`           | Overwrites the `locationId` field at runtime.                                                                                                                                       |
| `SetLocationRadius(float radius)`    | Overwrites the `locationRadius` field at runtime.                                                                                                                                   |

***

### Workflow: Setting Up a New POI

1. **Create the asset** — Right-click in the Project window → Create → Malbers Quest Forge → POI → Point of Interest.
2. **Set POI Name and Category** — The Name is what appears on screen; Category determines which system features are available.
3. **Assign icons** — Drag a Sprite into **Map Icon** (used on minimap and world map) and **Compass Icon** (used on the compass bar). The editor previews both icons tinted with Icon Color.
4. **Configure display range** — Set Min and Max Display Distance to suit the POI type. Quest objectives typically have a larger max range; ambient decorative POIs a shorter one.
5. **Set priority** — Leave at 0 for general markers. Raise to 10 or higher for critical quest targets that should never be hidden behind other icons.
6. **If Category = Location**:
   * Set a **Location ID** or leave blank to auto-generate.
   * Confirm or set **Location Type** and **Location Radius**.
   * Toggle **Is Discoverable** and **Hide Until Discovered** as appropriate.
   * Enable **Fast Travel** if players should be able to warp here from the world map.
   * Place a `POIMarker` at the location in your scene and click **Sync World Position to Asset** to write the world-space coordinate back into this asset.
7. **Reference in scene** — Drag this asset into a `POIMarker` component's **Point of Interest** field. The marker registers itself with `POIManager` on Awake, and the minimap, compass, and world map will display the icon automatically.

***

### Usage Tips

* **Asset name vs. display name** — The `.asset` filename in the Project window is for your own organisation. The **POI Name** field inside the asset is what players see.
* **Location ID uniqueness** — If two Location-category POIs produce the same auto-generated ID (because they share a name), the save system and quest matching will collide. Always manually assign unique IDs when names are similar.
* **World Position stays (0, 0, 0) until synced** — The inspector will warn you. Place the `POIMarker` in the scene first, then sync.
* **Icon Scale stacks** — `IconScale` on the POI asset is a multiplier applied on top of the base icon size configured on the MinimapUI or WorldMapUI component. A value of 1 means "use the map's default size."
* **Always Show for key locations** — Cities and major quest hubs generally benefit from `Always Show = true` so they appear regardless of how far away the player is, just like games such as Skyrim's location markers.
* **Hierarchy depth** — `ParentLocation` is a single reference, not a full tree traversal. If you need deep hierarchies (region → city → district → building), each POI simply references the one directly above it; any UI building a tree must walk the chain manually.
* **Fast Travel requires WorldMapFastTravel** — `EnableFastTravel = true` on the asset alone does nothing without the `WorldMapFastTravel` component present as a child of the `WorldMapUI` GameObject.