Map

Modules PulseMap (data: maps of levels, map sources, map coordinates) and PulseMapUI (minimap, world map and the map view widget; shows the minimap and the world map through the UI host of Pulse Foundation, the Pulse HUD by default, and uses the HUD section of its player settings). The editor tool that renders the picture of a level is in PulseEditor. A level gets a map from a picture of it seen from above; the minimap and the world map show that picture with the player, the markers of the marker registry of PulseFoundation and the paths of the path register.

Overview

Type What it is
UPulseMapDefinition Data asset Map (Primary Asset Type PulseMap): where the picture comes from (source), background color, zoom limits
FPulseMapSource Source of the picture, an instanced struct. FPulseMapSource_Image (Image): one texture of a known world area; sources without one picture draw tiles (e.g. Pulse World of the bridge PulseWorldGameplayBridge)
APulseMapActor Pulse Map Actor: says which map its level uses; its box is the area the map image tool renders
UPulseMapSubsystem World subsystem: the map of the world (Set Map, map actor, Level Maps, provided map, Default Map), OnMapChanged, the tiles of maps without one picture
UPulseMapViewWidget Pulse Map View: draws picture, paths, markers and player arrow for any view (center, size, rotation)
UPulseMapPathSubsystem Local player subsystem: the path register, lines on the minimap and the world map (AddPath, UpdatePath, RemovePath)
UPulseMinimapWidget Pulse Minimap: the map around the player, turning with the view or north up
UPulseWorldMapWidget Pulse World Map: a menu with the whole map, drag and zoom
UPulseMapUISubsystem Local player subsystem: puts the minimap on the HUD, opens and closes the world map
UPulseMapSettings Project Settings > Pulse > Gameplay > Map: map per level, default map, limits of the tiles
UPulseMapUISettings Project Settings > Pulse > Gameplay > Map UI: activation, minimap on the HUD, world map class, key, layer
UPulseMapPlayerSettings Player settings in the HUD section: minimap on or off, rotation, zoom

Setup

  1. Turn on the Pulse HUD (bEnableHUD, see HUD system): the minimap and the world map show through the UI host of Pulse Foundation, which is the Pulse HUD by default. Map UI Activation (Map UI settings) decides when they start: With UI Host (default) with the Pulse HUD or a Presenter Class of your own in Project Settings > Pulse > Foundation > UI, Always also with the default presenter (widgets in the viewport), Never not at all.
  2. Place a Pulse Map Actor in the level (Place Actors panel, search “Pulse Map”). Scale its box over the playable part of the level; things above the top of the box are left out of the picture (roofs, clouds), the turn of the actor is ignored.
  3. Press Render Map in the details of the map actor (or run Pulse.Map.Render in the editor console). The tool renders the area from above and creates T_<Level>_Map (texture) and DA_<Level>_Map (map) in a folder Map next to the level, sets the map on the actor and saves both assets. Save the level afterwards. Rendering again updates both in place.
  4. Play: the minimap is in the top right corner, M opens the world map.

Without a map actor the tool renders the bounds of the visible levels (ALevelBounds, actors with bRelevantForLevelBounds) and places a map actor there. A level can also get its map from the settings instead of a map actor: Level Maps (one map per level) or Default Map (every other level).

Pulse.Map.Render [Resolution] [Unlit] [/Game/Folder]: the resolution is the longer side of the picture (default 2048, the other side follows the area), Unlit renders the base colors without light and shadow, a folder overrides the place of the assets. The picture is rendered twice as large and scaled down; fog, clouds, atmosphere, motion blur and depth of field are off.

The map asset

Property What it does
DisplayName Title of the world map.
Source Where the picture comes from. Image: Image (north up) and WorldBounds (Min = south west corner, Max = north east corner).
BackgroundColor Around the picture and on maps without one.
MinimapViewSize World units across the minimap (the zoom of the minimap; the player setting scales it).
MinViewSize / MaxViewSize Closest and farthest zoom of the world map. MaxViewSize 0: the whole map, 100 km for a map without bounds.

The check (Pulse Check, Data Validation) reports a map without a source, an Image source with an empty area and zoom limits in the wrong order.

Map sources

FPulseMapSource is an extension point: another plugin or a bridge adds a source of its own as a child struct, and the map asset picks it in Source.

Function What a source returns
GetWorldBounds(OutBounds) The world area of the map, false for a map without bounds (an endless world).
GetImage(OutImageBounds) One picture of the whole map and the area it shows, null if the source has none.
GetTileLayout(OutLayout) How the source cuts the world into tiles (FPulseMapTileLayout: tile size of level 0, pixels, coarsest level, border); false if it draws no tiles.
GetTileContentKey(WorldContext) What the tiles show right now; when it changes (a new world), every tile is thrown away. 0: nothing to draw yet.
RequestTile(WorldContext, Request, Done) Draws one tile (FPulseMapTileRequest: key, world area, pixels, border); may work on other threads and calls Done once, from any thread, with (Pixels + 2 Border) squared colors (row 0 north, column 0 west, sRGB) or an empty array. False if it cannot draw now (asked again later).

Tiles

A map whose source has no single picture but a tile layout (an endless world) is drawn in square tiles. Level 0 is the finest; each level doubles the tile size. UPulseMapSubsystem keeps the tiles of the map of its world for every view on that machine:

  • Which tiles: every frame each view (minimap, world map) takes the finest level whose pixels are at least as large as a screen pixel, and the tiles that cover it (a turned minimap takes the tiles around its circle, so the set does not change while it turns). Views that could touch more than Max Tiles Per View take coarser tiles; the count does not depend on where the view is, so the level does not change while the map is dragged. The tiles two levels coarser are asked first: a few of them fill the whole view while the fine ones come.
  • Drawing: a tile without its own picture is drawn with the matching part of the nearest coarser picture; drawn tiles never overlap. Each picture has a border of one pixel, so tiles blend into each other without seams.
  • Requests: at most Max Tile Requests at once, nearest to the middle first. A source that cannot draw yet (no world) is asked again after Tile Retry Seconds, a request without an answer is given up after Tile Timeout Seconds.
  • Changes: InvalidateArea(Area) marks the tiles of an area as old: they keep their picture until the new one arrives, also when the change came while a request ran. A new content key (another world) throws every tile away.
  • Memory: beyond Max Tile Textures (default 192 tiles of 258 x 258 pixels, about 50 MB) the tiles no view used in the last frames are dropped; their textures are reused for the next tiles (up to half the limit stay free), so memory does not wait for the garbage collector.

The rules are pure functions in PulseMapTiles.h (Pulse::Map::Tiles), tested by the specs PulseMap.Tiles.

Provided maps

A system that knows the map of its world gives it with SetProvidedMap (the bridge PulseWorldGameplayBridge does this for a Pulse World). Set Map, a map actor and the Level Maps of the settings win over a provided map; the Default Map does not.

Coordinates

Maps are north up: north is +X of the world, east is +Y. The top of a picture is north, its right edge east. The functions are pure (PulseMapTypes.h, namespace Pulse::Map) and tested by the specs PulseMap.Coordinates:

Function What it does
WorldToUV / UVToWorld World point to the place in a picture (0, 0 top left) and back.
WorldToWidget / WidgetToWorld World point to the place in a map widget for a view (FPulseMapView: center, view size across the shorter side, rotation, widget size) and back.
GetIconAngle Angle of an arrow for a yaw on a view (clockwise from up).
ClampViewSize View size within zoom limits.
GetVisibleArea World area a view shows (its turned corners).

A view with a rotation puts that yaw up: the minimap that turns with the player uses the yaw of the camera.

Minimap

UPulseMinimapWidget follows the pawn of its player (the camera without a pawn) every frame. It turns with the view or keeps north up (player setting Minimap rotation), zooms by Minimap zoom and hides itself when the level has no map or the player turned it off. The default layout is a frame (style role Pulse.UI.Panel.HUD) with a map view that keeps markers on its edge, hides markers outside their MinDistance / MaxDistance and shows “N” in the direction of north.

With Add Minimap To HUD (Map UI settings, on by default) UPulseMapUISubsystem adds the minimap to the gameplay part of the UI host whenever the host is ready, again after every map change (FPulseUIGameplayWidgetSlot of Pulse Foundation: at Minimap Anchor with Minimap Offset and Minimap Size; with the Pulse HUD into GameplayRoot of the layout), so it hides with the HUD and while menus are open. A host that already shows a Pulse Minimap (one placed in the layout) keeps it; a layout without a GameplayRoot panel gets none (the log says so). GetMinimap() returns the minimap the host shows, also one the host placed itself, not only one the subsystem added.

Your own minimap: a Widget Blueprint child of Pulse Minimap with a Pulse Map View named MapView and a border named Frame, set as Minimap Class.

World map

UPulseWorldMapWidget is an activatable widget on a layer of the UI host (World Map Layer, default Pulse.UI.Layer.Game; the Pulse HUD puts that layer onto Pulse.HUD.Stack.Main). It opens with the whole map and the player in the middle (as far as the map allows).

Input What it does
Drag (any mouse button) Moves the map.
Mouse wheel Zooms around the cursor (ZoomStep per notch).
W A S D, arrow keys, left stick Moves the map (PanSpeed).
Q / E, + / -, Page Down / Up, right stick Zooms (KeyZoomSpeed).
Space, C, top face button, right stick press Back to the player.
Back action (Escape, B) or the map key again Closes the map.

Hovering a marker shows it larger with its name. A click that does not drag the map (it moved less than 4 Slate units while pressed), with any mouse button, and the confirm button of a gamepad (at the middle of the view) are reported as an FPulseMapClick: where on the map (WorldLocation), the marker under the cursor (Marker, a handle of the marker registry), the key and the map. OnMapClicked of the widget and OnMapClicked / OnMapClickedNative of UPulseMapUISubsystem get it; the map itself does nothing with it. A world map of your own calls NotifyMapClicked of the subsystem. PulseNavGameplayBridge uses it for destinations of the guide of Pulse Nav. While it is open the menu follows a new map of the world, and it closes itself when the world loses its map. The map key closes the map through a Slate input processor, because the game gets no input while the map is open; the input context of the menu (cursor, UI only) comes from the Pulse player input manager (World Map Input Context).

The key is the input action World Map Input Action (IA_PulseMap) of the mapping context World Map Mapping Context (IMC_PulseMap, key M), added for every local player. Leave the mapping context empty when the game maps the action in a context of its own. ToggleWorldMap, OpenWorldMap and CloseWorldMap of UPulseMapUISubsystem open it from Blueprint or C++.

Your own world map: a Widget Blueprint child of Pulse World Map with MapView, Backdrop, TitleText and HintText, set as World Map Class.

Markers

Maps show the markers of the marker registry of PulseFoundation (UPulseUIMarkerSubsystem, Pulse::UI::GetMarkers) whose channels include Map (AddMarker, default channels: compass, screen and maps; see Markers, tooltips and overlays). The map view reads the records of the registry and follows OnMarkerChangedNative; it works without the Pulse HUD. A marker of a tracked actor follows the actor.

Marker field On maps
Icon The icon (texture or material, loaded when needed); empty: the diamond of the UI theme.
ColorRole Tint of the icon.
Name Shown while the marker is hovered on the world map.
bShowOnScreenEdge Stays on the edge of the minimap while it is outside.
MinDistance, MaxDistance The minimap hides the marker outside this range from the player (like the compass), in the DistanceUnits of the marker (centimeters, meters, kilometers, miles or feet; Pulse::Map::UI::IsMarkerInRange, specs PulseMap.UI).

A marker only for maps: AddMarker(Data, Map) of the registry.

Paths

The path register (UPulseMapPathSubsystem, one per local player, Pulse::Map::GetPaths) holds lines for the maps, like the marker registry holds markers: a route, a border, a trail of your own. A path is plain data (FPulseMapPathData):

Field What it does
Points The line through world points (X north, Y east; Z is not used). At least two.
ColorRole Color role of the UI theme (Pulse.UI.Color.*); empty: Pulse.UI.Color.Accent.
Kind Any tag, for RemovePathsOfKind and filters.
Width Width of the line in Slate units (default 4).
DashLength, GapLength Dashes along the line in Slate units, so they keep their size when the map zooms; 0 draws a solid line.
Opacity Opacity when faded in.
FadeInSeconds, FadeOutSeconds A new path fades in, a removed path fades out (default 0.4 s each); 0 shows or removes it at once.
Channels Which maps show it: Minimap, WorldMap or both (default).

AddPath(Data) returns a handle (FPulseHandle). UpdatePath(Handle, Data) gives the path new points at once (no movement from the old points to the new ones; the fade in goes on). RemovePath(Handle, bFade) fades it out over its Fade Out Seconds and drops it then (Removing, then Removed on OnPathChanged / OnPathChangedNative); without fade it goes at once. For another line, such as a new route, remove the old path and add a new one: the old one fades out while the new one fades in. Only the opacity changes over time (Pulse::Map::Paths::GetOpacity), never the points. The fades run on real time, also while the game is paused. The cleanup of the player’s world removes every path.

The map view draws the paths of its Path Channel (Minimap on the minimap, WorldMap on the world map and by default) over the picture and under the markers, with RefreshPaths (the minimap and the world map call it every frame; call it while your own view ticks). Paths are local: nothing is replicated. Specs PulseMap.UI.Paths (fades, updates, removal, dashes).

With Pulse Nav, PulseNavGameplayBridge shows the route of the guide as a path (a new route fades in, the old one out) and the next waypoint as a marker; see Nav Gameplay.

The map view widget

Pulse Map View (UPulseMapViewWidget) draws a map into your own widgets: SetMap, SetView (center, view size, rotation), SetPlayer (location, yaw), RefreshMarkers (reads the markers of the registry again; call it while you tick), RefreshPaths (reads the paths of the path register again, with their fades), bShowPaths and PathChannel, FindMarkerAt and SetHighlightedMarker for hovering (handles are FPulseHandle of the registry), LocalToWorld / WorldToLocal, UpdateTiles (maps in tiles: call it once per frame while the view shows) and ClearTiles (a view that stops showing lets go of its tiles). Appearance: player arrow (theme icon Pulse.UI.Icon.Arrow, PlayerIconRotation -90 because that arrow points right), marker size, edge markers, the “N”, text role and color role of the arrow.

Player settings

UPulseMapPlayerSettings registers three options in the HUD section of the Interface tab (with Register Player Settings of the Map UI settings): Minimap (on or off), Minimap rotation (turn with the view, north up) and Minimap zoom (50 to 200 %). Setting ids Pulse.Setting.Map.ShowMinimap, .MinimapRotation, .MinimapZoom.

Multiplayer

Maps are local: every machine finds the map of its world, every local player has its own minimap and world map, and the markers and paths are those of the registers of that player. Nothing is replicated. SetMap changes the map on the machine where it is called.

Messages

Channel Payload Origin Notes
Pulse.Message.Map.Opened FPulseMapMessage Client The world map opened. Player: the controller of the local player, Source: the map.
Pulse.Message.Map.Closed FPulseMapMessage Client The world map closed.

Blueprint and C++

Function What it does
UPulseMapSubsystem::GetMap / GetMapOrigin The map of the world and where it comes from (Set Map, map actor, Level Maps, provided, Default Map).
UPulseMapSubsystem::SetMap(Map) Sets the map of this machine at runtime; null goes back to the map actor and the settings.
UPulseMapSubsystem::SetProvidedMap(Map) / GetProvidedMap The map a system knows for its world (after Level Maps, before the Default Map).
UPulseMapSubsystem::InvalidateArea(Area) Draws the tiles of an area again (invalid box: everywhere).
UPulseMapSubsystem::GetTiles / GetTileTexture (C++) The tiles a view shows and their pictures; UPulseMapViewWidget::UpdateTiles uses them.
OnMapChanged / OnMapChangedNative The map of the world changed.
UPulseMapDefinition::GetWorldBounds / GetMaxViewSize Area and farthest zoom of a map.
APulseMapActor::GetAreaBounds The area of the map actor’s box.
UPulseMapUISubsystem::OpenWorldMap / CloseWorldMap / ToggleWorldMap / IsWorldMapOpen / GetMinimap The map widgets of a local player.
UPulseMapUISubsystem::OnMapClicked / OnMapClickedNative / NotifyMapClicked Clicks on the world map that did not drag it (FPulseMapClick).
UPulseWorldMapWidget::OnMapClicked The same clicks on one world map widget.
UPulseMapPathSubsystem::AddPath / UpdatePath / RemovePath / RemovePathsOfKind Paths on the minimap and the world map.
UPulseMapPathSubsystem::FindPath / GetPaths / GetNumPaths / GetPathOpacity The paths of the register and how strongly one is drawn now.
OnPathChanged / OnPathChangedNative A path was added, updated, started to fade out or was removed.
Pulse::Map::Paths::GetOpacity / MakeDashes (C++) The fade of a path at a time and the dashes of a line.

The specs PulseMap cover the coordinates (PulseMap.Coordinates), how the subsystem picks a map (PulseMap.Subsystem), the tiles (PulseMap.Tiles), the edge and zoom helpers of the widgets (PulseMap.UI) and the paths (PulseMap.UI.Paths).

Example

LV_PulseGameplay_Example has a Pulse Map Actor over the whole level with the map DA_PulseGameplay_Example_Map (/PulseGameplay/Examples/Map, 40 x 40 m, rendered with the tool). Play it: the minimap shows the trees, rocks and the training dummy, M opens the world map, PulseUIMarker and PulseMapMarker add markers.

Switching it off. UPulseMapUISubsystem is switchable: add it to Disabled Subsystems (Project Settings > Pulse > Foundation > Subsystems) when your game brings its own map widgets. The map data, markers and the map view widget stay. See Replacing and switching off subsystems.

Cheats

See Console.


PulseGameplay plugin documentation.

This site uses Just the Docs, a documentation theme for Jekyll.