# World Map Markers

# World Map Markers

The Citizens system can display NPC locations on the world map and minimap. Markers show quest status indicators so players can easily find NPCs with available quests.

## How Markers Work

Markers are **per-player**. Each player sees markers based on their own quest progress. A quest giver might show a `!` for one player (quest available) and a `?` for another (quest ready to turn in).

The system uses two independent mechanisms:

1. **WorldMap MarkerProvider** -- Places icons on the world map/minimap via the Hytale WorldMap API.
2. **Quest Marker Entities** -- Floating symbols above the NPC's head visible in the 3D world (like `!` or `?` above a quest giver).

Both are managed automatically by the Quest mod when quest NPC profiles are configured.

## Marker Types

| Marker | Icon | Meaning |
|--------|------|---------|
| `quest_available` | `!` | This NPC has a quest available for the player. |
| `quest_turn_in` | `?` | The player can turn in a completed quest at this NPC. |
| `quest_progress` | `...` | The player has an active quest from this NPC (in progress). |

On the world map, each marker type uses a distinct icon:

- **Quest Available** -- `Quest_Available.png` (yellow exclamation mark)
- **Quest Turn In** -- `Quest_TurnIn.png` (yellow question mark)
- **Quest Progress** -- `Quest_Progress.png` (grey question mark)

## Automatic Quest Markers

When using the Quest mod with NPC profiles, markers are set and removed automatically:

1. A player joins or a quest state changes.
2. The Quest mod checks which NPCs have quests available, active or complete for that player.
3. Markers are set via `CitizenService.setMarker(citizenId, playerId, markerType)`.
4. When the quest state changes (e.g. quest accepted, completed, turned in), the marker is updated or removed.

No manual configuration is needed for quest-driven markers. They work out of the box when you configure quest NPC profiles.

## Multi-World Support

When your server uses multiple worlds, the marker provider must be registered on **each world** separately. The Quest mod handles this automatically via the `AddPlayerToWorldEvent`:

1. When a player enters a world, the event fires.
2. The system checks if the marker provider is already registered on that world.
3. If not, it registers the `CitizenMarkerProvider` on the new world.

This ensures markers appear on the world map regardless of which world the player is in. No manual configuration is needed — multi-world registration is handled automatically.

:::note
If you are writing a custom marker provider, you must register it on each world individually using `world.getWorldMapManager().addMarkerProvider(id, provider)`. Use a `Set` to track which worlds already have the provider registered to avoid duplicates.
:::

## Manual Markers (Admin)

For testing purposes, you can manually set markers on any citizen:

```
/kscitizen marker <citizenId> !
/kscitizen marker <citizenId> ?
/kscitizen marker <citizenId> off
```

- `!` -- Shows an exclamation mark above the NPC (quest available).
- `?` -- Shows a question mark (quest turn in).
- `off` -- Removes the marker.

Manual markers are only visible to the player who runs the command (per-player system).

## World Map Display

The world map shows markers with the NPC's name and a status suffix:

| Marker Type | Display |
|-------------|---------|
| Quest Available | `Kira (!)` |
| Quest Turn In | `Kira (?)` |
| Quest Progress | `Kira (...)` |

Markers only appear when the NPC's position is within the player's view distance on the map.

## 3D Quest Markers (Above NPC Head)

In addition to map icons, the Quest Marker system spawns floating marker entities above NPCs in the 3D world. These are the `!` and `?` symbols you see floating above quest givers.

Key characteristics:
- Positioned above the NPC's nametag hologram.
- Height adjusts automatically based on the NPC's `scale` and `nametagOffset`.
- Only visible to players who have a relevant quest state (per-player visibility).
- Automatically despawned when no players need to see the marker.

## Configuration

There is no separate configuration file for markers. The system derives all marker data from:

1. **Citizen positions** -- From `citizens.json` (the NPC's `posX`, `posY`, `posZ` and `worldName`).
2. **Quest states** -- From the Quest mod's player data (which quests are available, active or complete).
3. **NPC profiles** -- From the Quest mod's `quest_npc_profiles/` folder (which citizen is linked to which quests).

If you want an NPC to appear on the world map with quest markers, ensure:
- The citizen exists in `citizens.json` with valid position data.
- The Quest mod has an NPC profile linking that citizen to one or more quests.
- The NPC's world matches the player's current world.