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
- 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,Alwaysalso with the default presenter (widgets in the viewport),Nevernot at all. - 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.
- Press Render Map in the details of the map actor (or run
Pulse.Map.Renderin the editor console). The tool renders the area from above and createsT_<Level>_Map(texture) andDA_<Level>_Map(map) in a folderMapnext to the level, sets the map on the actor and saves both assets. Save the level afterwards. Rendering again updates both in place. - 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.