Build Your Own Location-Based Game

Requirements

Installation

1. Install the plugin from Fab to the engine, or copy the HitzGeoMap folder into your project's Plugins folder.
2. Open Edit > Plugins, search for Hitz GeoMap, tick it and restart the editor.
3. In the Content Browser settings turn on Show Plugin Content to see the sample level and materials.

Your First Map

1. Open Maps/HGM_Sample in the plugin's content and press Play. Walk with W A S D, drag to orbit, scroll to zoom.
2. For your own level, drag an HGM Map Actor into it and set Origin to a latitude and longitude.
3. Drag in an HGM Map Player Pawn. It possesses itself, so no game mode is needed.
4. Press Play. On a phone the map moves to the player's real position at the first GPS fix.

To see the map without pressing Play, select the map actor and click Preview In Editor. Clear Preview removes it.

Map Settings

Everything is on the map actor. Edits in the Details panel apply while the game is running, and each setting has a Blueprint function.

More tiles means more downloading and more memory. On a phone a Tile Radius of 2 or 3 is a sensible range.

Providers & Keys

Pick the provider with Source Preset. For a keyed provider, enter your key under Project Settings > Plugins > Hitz GeoMap > Default Access Token, or in Access Token on the map actor.

• Use a public key only. A key can be read from a packaged game.
• The provider's credit must stay on screen. If you turn Show Attribution off, show it in your own UI.
• Mapbox also asks for its logo and linked credits on screen. The plugin shows the text; the logo and links are yours to add.

Any other server

Set Source Preset to Custom and fill in Custom Source: the address with {z}, {x}, {y} and optionally {token}, the credit line, and the zoom range. Then set Custom Layer Names to the layout the server follows.

Styling Layers

The Map Layers list holds the 13 built-in layers: Highways, Main Roads, Streets, Paths, Rail, Waterways, Water, Forest, Parks, Farmland, Sand, Built-Up Land and Buildings.

At runtime use Set Layer Visible, Set Layer Color and Set Ground Color. Press Save Style As Asset to write the current look to an asset you can assign to other maps.

Placing Meshes

A Custom Rule on the map actor turns the features of one provider layer into geometry or placed objects.

1. Set Source Layer to the provider's layer name. Click Log Available Layers during Play to print every name.
2. Set Mode to Instanced Meshes and pick your Static Mesh.
3. For areas such as forests, turn on Scatter Inside and set Density Per Hectare. For lines such as roads, set Spacing Meters.
4. Size it with Placement Scale and Random Scale Range. Sizes follow the world scale.

Add Example Rules gives you working trees, road posts and point-of-interest markers to copy from. Other modes draw flat areas, raised shapes or strips, or spawn an actor class on each feature.

Spawning Actors

Add an HGM Actor Spawner and list your actor classes in Entries.

Keeping a place collected

Every spawned actor has a Spawn Id that is the same on every device and in every session. When the player collects an actor, call Get Spawn Id, then Block Spawn Id, and save the Id. When the game loads, call Block Spawn Id for each saved Id.

Making an actor usable

Implement the HGM Interactable interface on it. The pawn's interaction component reports when it comes within reach and calls it when the player taps it. To pin any other actor to a coordinate, add an HGM Geo Anchor component.

Player & GPS

Use the supplied pawn, or add its components to your own. Each works without the others.

Bind On Status Changed on the location component to tell the player what is happening:

HUD & UI

From any Widget Blueprint, get the HGM Map Events subsystem and bind what you need.

For buttons, call the functions on the pawn's HGM Map Input component: Recenter Camera, Cycle Camera Mode, Zoom Camera, Set Virtual Stick Input, Interact With Nearest.

The map actor has its own events for streaming: On Map Ready, On Focus Tile Changed, On Tile Loaded and On Tile Unloaded.

Android

• The plugin adds the location permissions to your app and asks the player the first time location starts.
• It reads GPS, network location and the compass directly from Android. Do not enable the engine's Location Services plugins.
• Location stops while the app is in the background and resumes when it returns.
• A stationary phone's GPS wanders by a metre or two. The plugin ignores that, so the player stays still and no false distance is counted.
• In Project Settings > Android, turn on Package game data inside .apk unless you distribute through Google Play with expansion files.

Troubleshooting