Map and Minimap System

Purpose and Scope

The map and minimap system provides the player with a world map and a realtime minimap that visualize level layout, player and AI locations, quest targets and temporary markers. It is implemented purely in HUD/UI widgets and per‑level helper actors, without dedicated ActorComponents on the character. The system does not track exploration progress or fog‑of‑war; maps are always fully visible once configured.

---

Runtime Architecture

Widgets and UI Containers

• WB_Minimap
  Minimap widget that renders a square top‑down view of the current level and overlays markers for the player, other actors and quest objectives.

• WB_Map
  Full‑screen world map widget that shows the entire level and supports placing temporary markers with the mouse.

• WB_Gameplay_Container
  Main in‑game HUD container. It hosts WB_Minimap as a child widget so that the minimap is always visible during gameplay.

• WB_InGameContainer
  In‑game container for extended UI screens. It hosts WB_Map and is responsible for opening and closing the world map when the player uses the appropriate input.

All map logic (coordinate transforms, marker display, input handling) is implemented inside these widgets and containers. There are no separate character‑side map components.

Map Data Asset: DT_MapsContainer

All maps for all levels are described in DT_MapsContainer, a DataTable with rows of type F_MapsContainer (name conditional). Each row corresponds to one playable level or map entry.

Key fields:

• MapSoftReference : TSoftObjectPtr<UWorld>
  Soft reference to the level that this map describes.

• Name : FText
  Display name of the map in UI.

• Description : FText
  Optional description for UI or tooltips.

• Image : UTexture2D*
  Generic preview image, used where a neutral image is needed.

• Minimap : TSoftObjectPtr<UTexture2D>
  Texture used by WB_Minimap for the minimap background (square 1:1 aspect).

• Map : TSoftObjectPtr<UTexture2D>
  Texture used by WB_Map for the world map background (16:9 aspect).

• MapZones : TMap<FName, UTexture2D*>
  Map zone previews used for save slot thumbnails. Each key is a zone name, each value is a texture that visually represents that zone.

• NetworkMode : E_MapNetwork
  Enum describing in which network mode this map entry is valid (singleplayer, multiplayer, shared, etc). Used to filter maps by current network context.

• EngineData : F_MapsEngineData
  Engine‑level coordinates and origins for both minimap and world map.

F_MapsEngineData

F_MapsEngineData stores all coordinate mapping parameters for the minimap and world map:

• MinLocationMinimap : FVector2D
  
• MaxLocationMinimap : FVector2D
  
• MinLocationWorldMap : FVector2D
  
• MaxLocationWorldMap : FVector2D
  
• MinimapOrigin : FVector2D
  
• WorldMapOrigin : FVector2D

These values define how world coordinates are mapped to UV space of the minimap/world map textures and where the logical origin is. All runtime conversions between world space and UI coordinates for markers rely on this struct.

---

Generating Map and Minimap Textures

The project ships with tools to automatically capture world and minimap textures from the level using dedicated Blueprint actors.

Map Boundaries: BP_MapBoundary

BP_MapBoundary is a helper actor used to define the rectangular area of the map or minimap in world coordinates.

Key fields:

• Boundary : E_MapBoundarySide
  • RightTop
    
  • LeftBottom
    Indicates which corner this boundary instance represents.
• MapType : E_MapType
  • WorldMap
    
  • MiniMap
    Specifies whether this boundary pair belongs to the world map or minimap.

For each level, you must place two BP_MapBoundary actors per map type:

• For the world map:
  • BP_MapBoundary_UpperRight – placed at (X = MaxX, Y = 0, Z = 0), with Boundary = RightTop, MapType = WorldMap.
    
  • BP_MapBoundary_LowerLeft – placed at (X = 0, Y = MaxY, Z = 0), with Boundary = LeftBottom, MapType = WorldMap.
• For the minimap:
  • Another pair of BP_MapBoundary actors with MapType = MiniMap, positioned similarly but using a 1:1 aspect ratio.

Important: Do not delete BP_MapBoundary actors after generating textures. For correct operation you must have 4 BP_MapBoundary instances per level: two for the world map and two for the minimap.

World Map Aspect Ratio

The world map uses a 16:9 texture. To maintain the correct aspect ratio:

• The map “origin” is at world coordinates (X = 0, Y = 0); this point must correspond to the top‑left corner of your intended map area.
  
• Let BP_MapBoundary_UpperRight be located at X = MaxX, Y = 0, for example X = 18000.
  
• Then BP_MapBoundary_LowerLeft must be located at:
  • X = 0
    
  • Y = 9/16 * MaxX (for MaxX = 18000, this gives Y = 10125)
    
  • Z = 0

This ensures the captured area matches the 16:9 aspect ratio of the final map texture.

Map Capture Utility: BP_MapUtility

BP_MapUtility is the actor that actually captures the map or minimap texture.

Usage:

1. Place BP_MapBoundary actors as described above (two for world map, two for minimap).
   

2. Add a BP_MapUtility actor to the level. It automatically finds all relevant BP_MapBoundary instances and computes its own placement and capture region.
   

3. Configure BP_MapUtility:

   • MapType : E_MapType – WorldMap or MiniMap.
     
   • ProjectionType : E_ProjectionType – Orthographic.

4. Use the provided Blueprint action (for example, UpdateFlag or a similar button in the Details panel) to capture the current view into a render target.
   

5. Convert the RenderTarget texture to a UTexture2D asset.
   

6. Open DT_MapsContainer and assign:

   • The generated world map texture to the row’s Map field.
     
   • The generated minimap texture to the row’s Minimap field.

The same steps are repeated for minimap generation, with the only difference being the aspect ratio and boundary placement:

• Minimap textures use a 1:1 aspect ratio.
  
• BP_MapBoundary_UpperRight and BP_MapBoundary_LowerLeft are placed so that both X and Y extents match (for example, X = 18000, Y = 18000).
  
• For both boundary actors, set MapType = MiniMap and appropriate Boundary values (RightTop for upper right, LeftBottom for lower left).

---

Map Zones and Save Slot Previews

The MapZones field in DT_MapsContainer is used to show zone‑specific images in save slot previews. The mechanism is:

1. The level contains a BP_WorldSections actor with one or more UBoxComponent children.
   
2. Each BoxCollisionComponent is placed over a logical region of the level (e.g. “Town”, “Industrial Area”) and given a tag that defines the zone name.
   
3. When the player saves the game, the system checks which BP_WorldSections box currently contains the player’s position.
   
4. The corresponding zone name (from the box’s tag) is used as a key into MapZones.
   
5. The texture assigned to that key becomes the preview image for the save slot.

This allows any level to be divided into arbitrary zones, with save previews automatically reflecting the area where the player saved.

---

Marker System

The map and minimap display markers for various actors and gameplay objects. The system distinguishes between temporary markers (explicitly placed by the player) and persistent markers driven by actor type and marker profiles.

Temporary Markers: BP_TemporaryMarker

Temporary markers are created when the player manually clicks on the world map:

• Left mouse button (LMB) on WB_Map spawns a BP_TemporaryMarker actor at the corresponding world location.
  
• This actor displays a marker on both the world map and minimap as long as it exists.
  
• Temporary markers are considered “Point of interest” type.

Deleting or clearing temporary markers is handled either by specific UI actions or by destroying the spawned BP_TemporaryMarker actor.

Marker Profiles: BP_GS_MarkerProfile

Persistent and dynamic markers (for players, NPCs, vehicles, quest actors, etc.) are configured through BP_GS_MarkerProfile, a DataAsset that defines how a given actor type should appear on the map.

Key boolean parameters:

• Need Marker in World
  Whether a 3D world marker (for example, floating icon) is needed.

• Persistent On The World Map
  If true, the marker remains on the world map even after the actor leaves the detection radius of the player’s MapActorsCollector.

• Need Marker On UI Maps
  Whether a marker should be shown on UI maps (world map and/or minimap).

• Persistent On The UI Map
  If true, the marker stays visible on UI maps even when the actor is no longer within detection radius.

• Rotate
  Whether the marker icon on map/minimap should rotate with the actor’s rotation.

Marker profiles are assigned in BP_GS_Character via:

• MarkerTypeSettings : TMap<EActorType, BP_GS_MarkerProfile*>

This map defines marker behavior per actor type. For all non‑temporary markers, actual markers are purely UI widgets; only temporary markers are real actors (BP_TemporaryMarker).

Actor Detection: MapActorsCollector

On the player character there is a USphereComponent called MapActorsCollector. Its responsibilities:

• Detect nearby actors that should be represented on the map by handling overlap events.
  
• On BeginOverlap, an actor with a supported EActorType is associated with its configured BP_GS_MarkerProfile and a corresponding marker widget is shown on the minimap/world map.
  
• On EndOverlap, the system checks Persistent On The World Map and Persistent On The UI Map to decide whether to remove or keep the marker.

This allows short‑range markers (e.g. nearby loot) to disappear naturally, while important markers (quest targets, vendors, vehicles) remain visible across the map.

Marker Types and EActorType

Marker types are defined by EActorType, which covers all relevant actor categories:

• OtherPlayers
  
• PointOfInterest (temporary markers created by the player)
  
• Quest
  
• BotTeamMelee / BotTeamFirearms
  
• BotEnemyMelee / BotEnemyFirearms
  
• Player
  
• NPCQuest
  
• NPCShop
  
• Vehicle
  
• Dummy

Each EActorType is mapped to a BP_GS_MarkerProfile that controls visibility, persistence and rotation.

---

Quest Integration

Quest integration with the map is implemented directly from BPQuestComponent using a simple API:

• When a quest stage requires the player to find an item or reach a zone, the quest system spawns the corresponding actor (for example, a quest item actor or a quest zone actor).
  
• After spawning, BPQuestComponent calls into the map/minimap API to add a marker for that actor.
  
• A binding is created to the actor’s OnDestroyed event. When the actor is destroyed (for example, the item is picked up or the zone objective is completed), the map system removes the corresponding marker widget.

Because quest targets are regular actors detected by MapActorsCollector and controlled by marker profiles, there is no separate “quest location database”: all integration happens through actors and their lifecycles.

---

Minimap Behavior

The minimap is rendered as a separate texture and behaves independently from the world map.

Key characteristics:

• Uses its own square texture (Minimap) with a 1:1 aspect ratio generated via BP_MapBoundary + BP_MapUtility as described above.
  
• Uses EngineData.MinLocationMinimap, MaxLocationMinimap and MinimapOrigin for coordinate mapping.
  
• The minimap widget rotates the player icon rather than the map texture itself; the map remains “north‑up” while the icon shows the player’s facing direction.
  
• Visibility of NPCs, bots and other actors on the minimap is controlled by:
  • Their EActorType → BP_GS_MarkerProfile mapping in BP_GS_Character.
    
  • The detection radius of MapActorsCollector.

There is no fog‑of‑war or exploration progress: all areas of the minimap texture are visible once the texture is assigned.

---

World Map Behavior

The world map is shown via WB_Map and generally occupies the full screen.

Key characteristics:

• Uses the Map texture from DT_MapsContainer.
  
• Uses EngineData.MinLocationWorldMap, MaxLocationWorldMap and WorldMapOrigin for converting world coordinates to map UI positions.
  
• Shows the same set of markers as the minimap, subject to Need Marker On UI Maps and persistence flags in BP_GS_MarkerProfile.
  
• Allows the player to place temporary markers:
  • Left mouse button (LMB) click on the map converts the click position to a world location.
    
  • A BP_TemporaryMarker actor is spawned at that location and a corresponding marker widget is displayed.

World map displays no exploration fog and always shows the full texture; all “progress” is purely in terms of current markers.

---

Networking and Modes

DT_MapsContainer.NetworkMode is used to filter which maps are valid for the current network mode:

• Singleplayer maps.
  
• Multiplayer maps.
  
• Maps available in both modes.

The map and minimap widgets read the current map row based on the loaded level and network mode, then use its Minimap, Map and EngineData to configure visuals and coordinate transforms. Marker logic is local to each client but respects authoritative actor lifecycles (servers spawn and destroy actors that drive markers).

---

Limitations and Notes

• The map and minimap system does not implement fog‑of‑war or exploration progress; all areas are always visible.
  
• There is no dedicated save data for map state: user‑placed temporary markers and map settings are not persisted across sessions.
  
• All non‑temporary markers are purely UI widgets driven by actor type and marker profiles; only temporary markers have dedicated actor classes (BP_TemporaryMarker).
  
• All coordinate mapping depends on correct placement and configuration of BP_MapBoundary actors and correct EngineData values in DT_MapsContainer.