Map Helper

Documentation for BP_QuestMapPro_MapHelper

The Map Helper actor (BP_QuestMapPro_MapHelper) is a helper actor used by Quest Map Pro to determine the dimensions and origin of the world (used by calculations) as well as to capture images of the world that can either be used as-is for both the world map and mini map, or serve as a basis for art-based map creation. It is required for the map systems of Quest Map Pro and should be added to the map. It will be removed at runtime once all information has been retrieved from it, as to not impact runtime performance.

Helper Functions

The Map Helper actor has three helper functions that can be used in the editor to assist in working with the map systems.

Update Helper Actor

This helper function should be called in the editor after setting the North West and South East target point references and is used to calculate the total world size.

Capture Map Image

This function is used to capture the world in its entirety as one single image that can be used for the map when at zoom 1.0x, or exported to serve as a guide for art creation.

Capture Tiered Map Images

This function is used to capture multiple tiers of the world at different zoom levels, as defined by the Tiered Zoom Transitions array. Note that this function may cause the engine to freeze depending on the number of images needed, resolution of images, etc.

Implementation

The Map Helper actor should be added to your world before attempting to work with any of Quest Map Pro’s map systems at runtime as they all require this actor to be set up and configured. The actor will be removed as part of the initialization process of the Systems Manager.

Use of this actor itself can be separated into three distinct stages.

Setup

Regardless of the type of capture desired, the Map Helper needs to first be configured correctly.

Step 1: Add actor to the world

Simply drag the Map Helper actor into your scene and place it somewhere. Note that this actor has no impact on runtime so its location is not particularly important. Upon successful completion of Step 3, it will be automatically placed in the center of your world, so it can be useful to ensure it is easy to find within the engine’s World Outliner.

Step 2: Add target points to world

Add two target points to your world via Place Actors. These two points should represent the most North-Western point and most South-Eastern point that should be shown on the map so move them to the appropriate locations within the scene. It is important to know which target point is which, so it is recommended to give them distinct names within the outliner.

Note: These should be the absolute NW and SE corners of your map as it will be shown in a map image, not the most NW/SE player-accessible points. For example, if your playable world is surrounded by a mountain range that you wish to include in the map, then these mountains should fall within the region defined by the two target points.

Step 3: Point to target points and run Update Helper Actor

Set the North West reference to the NW target point added in Step 2. Do the same for the South East reference with the SE target point. Finally, click the Update Helper Actor to run the update function. This should move your Map Helper to the middle of your world (as defined by the target points). It will maintain the z-axis value it had already. You will be able to see your calculated world size, in Unreal Units (equivalent to cms by default) by looking at the now populated value World Size. Despite its appearance, this value is exposed for reference only - setting it will not do anything.

Capturing Map Images

There are two methods to capture map images. Both can be used to create engine-captures that can be utilized as map image data, or exported into art software (such as Photoshop, Krita, etc.) to create artistic map images. There are benefits and drawbacks to each method, and each is suited to different project styles. For more information on choosing the method, please see the Map Capture Methods section.

Capturing a Single Map Image

Note: Ensure that Setup steps have been completed correctly before proceeding.

Step 1: Set Resolution

Set the Render Target Resolution to the desired resolution. Higher resolutions will appear much crisper at runtime, which is particularly noticeable at higher zoom levels, but come at the cost of using more memory.

Step 2: Set Capture Location

Set the location to save captures with the Capture Location variable. All captures will be placed within the folder defined as a subfolder of Content. For instance, if Capture Location is set to MapCapture, the capture image will be placed in Content/MapCapture. Note that capture locations can include multiple folders by the use of the forward slash. As an example, setting Capture Location to Map/Capture will capture the image in Content/Map/Capture. Folders will be created if they do not already exist.

Step 3: Set Capture Name

Using Capture Name to define the file name of the capture. Note that this will never overwrite files, instead creating sequenced numbered alternatives. For example, if a texture called MapCapture already exists, when capturing a new file will be named MapCapture1. The next will be MapCapture2. etc.

Step 4: Set Capture Height Offset

Set the Capture Height Offset to reflect the highest point in your map that needs to be captured. Anything above this height will be clipped in the map capture. By default this value is relative to the actor location, but if an absolute height is desired, enable Height Offset is Absolute.

Step 5: Capture the Map Image

Click on the Capture Map Image button. Your map image should now be captured and saved as a texture in the folder defined by Capture Location with the file name defined by Capture Name. This texture should now be set to use the Compression Settings: UserInterface2D (RGBA) and the Texture Group: UI.

Capturing Images for Tiered Zoom Levels

Note: Ensure that Setup steps have been completed correctly before proceeding.

Step 1: Set Capture Location

Set the location to save captures with the Capture Location variable. All captures will be placed within the folder defined as a subfolder of Content. For instance, if Capture Location is set to MapCapture, the capture image will be placed in Content/MapCapture. Note that capture locations can include multiple folders by the use of the forward slash. As an example, setting Capture Location to Map/Capture will capture the image in Content/Map/Capture. Folders will be created if they do not already exist. In the case of tiered zoom capture, multiple folders will be created within the capture location, with each level of zoom being placed in its own folder for easier management.

Step 2: Set Capture Name

Using Capture Name to define the file name of the capture. Note that this will never overwrite files, instead creating sequenced numbered alternatives. For example, if a texture called MapCapture already exists, when capturing a new file will be named MapCapture1. The next will be MapCapture2. etc. As tiered zoom levels utilize a sequence of images, textures will be named to reflect this, with files being named [CaptureName]_ZoomX_N, where X reflects the zoom tier and N reflects which image in sequence it is.

Step 3: Set Capture Height Offset

Set the Capture Height Offset to reflect the highest point in your map that needs to be captured. Anything above this height will be clipped in the map capture. By default this value is relative to the actor location, but if an absolute height is desired, enable Height Offset is Absolute.

Step 4: Define Zoom Tiers

For each tier of zoom desired, a new entry must be added to the Tiered Zoom Transitions array. Each entry in this array should define what level the map should transition to use images at this tier (the Transition Zoom), how many images make up the grid dimension (x and y) at this tier (Grid Dimensions) and the resolution of each grid segment (Segment Resolution). The array should be sorted in order of lowest zoom to highest. An example of how this might be set up would be as follows:

In this example the system will capture, and as a result use:

Tier 0: One single image of resolution 2048x2048 for any zoom above 0x

Tier 1: A grid of 4x4 images of resolution 1024x1024 for any zoom above 2.0x

Tier 2: A grid of 16x16 images of resolution 1024x1024 for any zoom above 4.0x

For more information on how these tiers are utilized to save on performance, improve map readability, etc. see Tiered Zoom Levels.

Step 5: Capture Map Images

Click the Capture Tiered Map Images button. This may appear to cause the editor to freeze due to the number of images that may be required to capture. Let the engine complete its process before doing anything else. Upon completion, a series of images should now be available within the location defined by Capture Location. Every image captured should be set to use the Compression Settings: UserInterface2D (RGBA) and the Texture Group: UI (this can be done via the Bulk Edit via Property Matrix which is available after selecting all images, right clicking and navigating to the Asset Actions submenu).

Video Tutorial on Tiered Zoom Levels:

Settings Overview

Configuration

World Size	Reference variable only. Displays the calculated total world size upon completion of the Update Helper Actor function. Should not be set manually.
North West	Target point at point in the world considered the most North-Western location in the world.
South East	Target point at point in the world considered the most South-Eastern location in the world.

Map Capture

Render Target Resolution	Desired resolution for the generated helper image for making map artwork. Note that higher resolutions can cause some stutters in the editor during the capture process. Does not impact gameplay at all. Only relevant for single image capture using Capture Map Image - does not impact tiered zoom levels at all.
Capture Location	Determines the directory that captures are saved to by default relative to the main Content folder.
Capture Name	Determines the name of the capture. Multiple captures will have numbers affixed to them. Tiered zoom captures will have additional information pertaining to their tier included in the file name.
Capture Height Offset	Determines the height above the landscape at which the capture occurs. Should reflect height above the highest point in your map that needs to be captured. Anything above this height will be clipped in the map capture. By default this value is relative to the actor location, but if an absolute height is desired, enable Height Offset is Absolute.
Height Offset is Absolute	If enabled, the Capture Height Offset will be an absolute z level rather than a relative location above the helper actor's location.
Enabled Tiered Zoom Transitions	If enabled, the map system will automatically transition between different resolution images using a grid-based layout of different zoomed segments of the map.
Automatically Populate Textures for Map	If enabled, the array of images will automatically update to reflect new captured images.
Tiered Zoom Transitions	Defines the settings for each tiered zoom of the map captures. See Tiered Zoom Levels for more information.
Tiered Zoom Data	Data used to represent the zoomed tiers, including what zoom level causes a transition, what textures to use for that level and so on. See Tiered Zoom Levels for more information.
Warning	Intended to be a warning about potential performance impact of the capture process.

Fixes

These settings exist to assist with working around potential issues associated with using the Map Helper actor and capturing maps. For more information, see the Common Issues page of this documentation.

Apply Directional Lighting	If you are experiencing issues with your map captures coming out blank/entirely black, it is likely due to a conflict with another system. Applying directional lighting at the time of capture can in many cases fix this issue. This fix should resolve capture issues in scenarios where the map may not be well lit, as well as when using systems such as Ultra Dynamic Sky.
Apply Material Fixes	If you are experiencing issues with objects in your scene not being captured, this fix can be used to apply a temporary material to said objects just for the capture. Once the capture is complete, the original material will be reapplied. This fix should resolve capture issues with Riverology and Oceanology, but may be useful in other scenarios.
Actors to Fix	A list of actors in your scene that you wish to apply a material fix to for capture, as well as the material to use for each actor.
Classes to Fix	A list of actor classes in your scene that you wish to apply a material fix to for capture, as well as the material to use for each actor. Please note that actors listed in ActorsToFix will override instances of actors found using this list.

Post Processing

Enable Post Process Materials	If enabled, the post processing material defined by PostProcessMaterials will be applied to the capture.
Post Processing Materials	A list of post processing materials to apply to the capture.

Map Capture Methods

Quest Map Pro includes two different support versions for map capture and display. Each method has strengths and drawbacks that should be considered when deciding which to use. Some projects will be particularly suited to one method over the other.

Single Map Image

Using a single map image is the simplest method for both capturing and displaying the world. It uses a single capture (or art-piece) of the world to portray the entire map. This can be achieved by following the steps outlined in Capturing a Single Map Image and ensuring that Enable Tiered Zoom Transitions is set to false. Once a capture has been created, it can be used as is, or exported and edited or used as a guide to create artwork. The final image to be used must be set as the Map Image under Map Controls in the Map System component.

Strengths of using a single map image:

• Very simple implementation

• Low art budget

  • Only one image is required, cutting down the work required by artists

• Minimal variance runtime impact on performance

  • As only one image is required, and that image is of a fixed resolution, its very easy to account for this image

• One texture per map/level

Drawbacks of using a single map image:

• Fixed resolution and visual quality

  • As only one image is used, the map image will appear quite low quality when zoomed in significantly

• Potentially larger impact on performance than tiered zoom levels

  • To mitigate low visual quality, a very high resolution image can be used, but this can end up using more video memory than a tiered zoom approach of similar or greater visual quality

The best use cases for a single map image is in games with a small world, when using Quest Map Pro in a game with multiple levels that are displayed as maps on their own, or when providing the player a world map that they can not zoom in much. In other instances, a tiered zoom approach will often provide a superior visual experience at a lower performance cost.

Tiered Zoom Levels

The tiered zoom level approach to map captures creates a series of map images that are segmented and displayed in grids as a singular map. As the player pans the map, the segments required are dynamically loaded in, ensuring that a much higher visual quality (than a single image) can be achieved while minimizing, or in some cases lowering, the impact on runtime performance. This can be achieved by following the steps outlined in Capturing Images for Tiered Zoom Levels and ensuring that Enable Tiered Zoom Transitions is set to true. It is recommended to ensure that Automatically Populate Textures for Map is set to true to automatically update the Tiered Zoom Data with the newly captured images. Once captured, these images can be used as is or exported and edited or used as guides to create artwork.

Strengths of using tiered zoom levels:

• Much higher visual quality can be achieved

  • As the images are loaded in based on the current zoom level, higher quality images can continuously be loaded as required, ensuring that even at incredibly high zoom levels, the map being displayed is of high quality

• Potentially lower overall performance impact than a single map image

  • Due to the dynamic loading of images, a lower resolution can be used at any point, potentially lowering the amount of VRAM required than that of a single image while maintaining the same level of detail

• Very well suited to mini map usage

Drawbacks of using tiered zoom levels:

• Higher art budget

  • As multiple files are required at higher levels of quality, it will require more time and effort to create an art-based map than a single image

• Runtime performance variance

  • As the player can be given control over map panning, directly influencing how many images are loaded, there is a potential for some variance in how much video memory is being used at once

• Multiple, potentially many, textures per map/level

Tiered Zoom Levels are very well suited to large game worlds, projects requiring high quality mini maps or any project where the player is able to zoom into the map at any high level. In most cases, tiered zoom levels are superior to single map images.