Skip to main content

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​

MarkerIconMeaning
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 TypeDisplay
Quest AvailableKira (!)
Quest Turn InKira (?)
Quest ProgressKira (...)

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.