Menu
Lumberyard
User Guide (Version 1.15)

Using Heatmap Analytics

You can use heatmaps to view data that's generated from the Game Metrics Cloud Gem and for any metric type that a game client sends. In the Cloud Gem Portal, the heatmap appears as an overlay on an image of the game map. You can see information such as the majority of player movement and where most player deaths occur.


      Example of a heatmap overlay on an image of a game map in the Amazon Lumberyard
        Cloud Gem Portal.

You can also expand heatmap functionality to use other gems that provide metrics, such as the Defect Reporter Cloud Gem. When used with this gem, you can see where bugs are generated.

To use heatmaps in the Cloud Gem Portal, you must generate events with positional data and select that event type in the heatmap tool.

Prerequisites

This tutorial assumes the following:

  • You are using a Lumberyard project that has the Cloud Gem Game Metrics enabled. For more information, see Enabling Gems.

Creating Heatmaps with the Heatmap Tool

After you complete the prerequisites, you can create a heatmap to view your data in the Cloud Gem Portal.

To create a heatmap

  1. In Lumberyard Editor, choose AWS, Open Cloud Gem Portal.

  2. In the Cloud Gem Portal, on the Cloud Gems page, under Analytics, choose Heatmap.

    
            Choose Heatmap under Analytics in the
              Amazon Lumberyard Cloud Gem Portal.
  3. On the Heatmaps page, click Create Heatmap.

    
            Click the Create Heatmap button on the
                Heatmaps page in the Amazon Lumberyard Cloud Gem Portal.
  4. For Name, enter a name to identify your heatmap.

  5. For Level Screenshot, upload a top-down screenshot of your level. Use the mouse wheel or +/- buttons to resize the image. Move the image to fill the gray image box.

    Note

    Lumberyard includes a sample screenshot in the lumberyard_version\dev\CloudGemSamples\Levels\MetricsSample\cloud_gem_portal_heatmap_image.png directory.

    You can also create your own screenshot. For more information, see Creating Screenshots of Your Level.

    
            Example of a top-down screenshot of a level in the gray image box in the
              Amazon Lumberyard Cloud Gem Portal.
  6. For Max Zoom Scale, set the minimum and maximum values. You can adjust these values to change how the aggregated data points appear as heat spots on the map.

  7. For Game World Coordinates, enter the xy coordinates for the bottom left and bottom right of the viewport screenshot. This is necessary to properly map the data points that are captured in the game to the top-down screenshot of your level.

    Lumberyard includes a text file with the xy coordinates of the sample screenshot. You can find the cloud_gem_portal_heatmap_global_coordinates.txt file in the lumberyard_version\dev\CloudGemSamples\Levels\MetricsSample directory.

    If you're using the sample screenshot, enter the following xy coordinates:

    • Lower Left: X=0.39 | Y=4.05

    • Lower Right: X=126.96 | Y=3.15

    If you created your own screenshot, you need to identify the xy coordinates. For more information, see Creating Screenshots of Your Level.

  8. For Event, select an event type from the drop-down list. This event type is the data source for the heatmap and should include positional data.

    Note

    If you're using the Metrics Sample level, the event type is called translation.

  9. For X Axis, select the x position of the event type that you selected.

  10. For Y Axis, select the y position of the event type that you selected.

  11. (Optional) You can filter search results to show metrics on the heatmap for a specified time range or that meet certain SQL filters.

    Example

    You can filter the search results to show metrics for user IDs that match XYZ (uid = 'XYZ') or for iOS devices only (platform_identifier = 'iOS').

    
              Specify SQL filters to show specific metrics on your heatmap in the Amazon Lumberyard
                Cloud Gem Portal.
  12. Click Save.

Creating Screenshots of Your Level

You can create a top-down screenshot of your level to use with the heatmap overlay.

To create a top-down screenshot of your level

  1. In Lumberyard Editor, open your level.

  2. In the Entity Outliner, select your controllable entity. For example, in the Metrics Sample level, under Player, select followcam.

    
            Choose the controllable entity's camera in the Lumberyard
                Entity Outliner.
  3. In the Entity Inspector, do the following:

    1. Under Camera, click Be this camera.

      
                Click Be this camera in the Lumberyard
                    Entity Inspector.
    2. Under Transform, for Rotate, set X to 270 degrees. This rotates the camera orthogonal to the level.

      
                For the Rotate parameter, set X to
                  270 degrees in the Lumberyard Entity Inspector.
  4. In the viewport, do the following:

    1. Click anywhere to deselect the entity.

    2. Adjust the viewport dimensions to match your level dimensions. For example, if your level has a square geometry, adjust the viewport into a square shape.

    3. Use the mouse wheel to scroll out.

    4. Use the WASD and QE keys to adjust the view. Your level should cover the bottom left and right of the viewport.

  5. Use your preferred tool to capture and save a screenshot of the viewport.

    Note

    You'll specify the path to your screenshot on the Create Heatmap page in the Cloud Gem Portal.

    
            Example top-down screenshot of the Metrics Sample level in the Amazon Lumberyard
              viewport.
  6. Pause on the bottom left of the viewport.

    Important

    The pointer must touch the terrain, not the void space.

    
            Example of the pointer touching the terrain on the bottom left of the Amazon Lumberyard
              viewport.
  7. In the bottom toolbar, locate the xy coordinates for the bottom left of the viewport.

    Note

    If the xy coordinates aren't updating as you move the pointer, you can use the right mouse button to rotate the camera slightly.

    Example

    The following image shows the pointer at X: 7.05, Y: 75.10.

    
              Locate the xy coordinates for the bottom corners of the viewport for creating
                your heatmap in the Lumberyard Cloud Gem Portal.
  8. Repeat steps 6 and 7 for the bottom right of the viewport.

    Note

    You'll specify these xy coordinates for the heatmap Game World Coordinates in the Cloud Gem Portal.