Maps_Locations

A core concept of LoGaCulture is location. Location of heritage sites, people and history is the heart of this project and therefore using locations in LUTE is a key aspect of the tool.

Locations are defined as custom Variables which store a scriptable object that include details of a specific location (most importantly, latitude and longitude).

Locations are used in a myriad of Orders, Nodes and Condition statements. A common use of a location will be to tie it to a Node's Event Handler which will play that Node once the location criteria has been met.

Mapbox Attribution

LUTE currently uses Mapbox and Open Street Maps which requires attribution on public releases. You can find out more by heading to: https://docs.mapbox.com/help/dive-deeper/attribution/.

We have included a prefab which you can place into your scene which will cover the basics outlined in the above link. This prefab can be found in: LUTE>Resources>Prefabs>MapboxAttribution. Once placed into the scene, ensure that the Canvas on the object points to the camera which is used to render the map as the Attribution object uses the 'Map' layer (ensure the camera renders this layer if you cannot see it during runtime). You can see a working example of this in the 'Demo' or 'BasicGame' demo scenes.

Adding Locations

To first add a location you must open the map up. To do so:

1. Ensure you have the Flow Engine Window open and a Flow Engine selected in the scene.
2. Select Show Map in the top left toolbar of the Flow Engine Window.

3. We suggest docking the map window somewhere for ease of use.

Setting Map Visuals

When opening the map, the Inspector Window will update to show the settings for the Map. Feel free to customise your settings but please play close attention to changing map layers:

1. Unfold the drop-down IMAGE
2. Select the drop-down for Data Source

3. Choose your preferred style. Please note that the style chosen will be visible in the editor and will also be used in the final experience (i.e, from the player's perspective)

Navigating the Map

To pan the map (akin to how you would navigate any other map software) you can hold left-click and drag the mouse when inside the bounds of the map window. Alternatively, you can use the keyboard controls WASD. Settings for panning speeds can be adjusted in the Map Inspector Window.

You can zoom in and out of the map using the scroll wheel or find the zoom level under the GENERAL drop-down in the Map Inspector Window.

Under the GENERAL drop-down you can also search for specific locations using key-words. To do so:

1. Select 'Search'.

2. Begin typing your location.
3. Select the desired location from the list if it appears or continue to refine your search until it does.

4. The map will update with the desired location.

The Map at Runtime

Oftentimes with location games, we restrict how the player can interact with the map. You can adjust the map movement settings by navigating to the MapCameraMovement script component on Map object. Here you can adjust speed of panning/zooming, whether to allow certain types of movement and restrain the zoom levels of the Map.

The default settings are fairly typical and allow for a lot of freedom so you may wish to play around with this until you find the style of interaction you are looking for.

Creating Location Variables

Adding a new Location Variable can be done in two ways:

1. You can create a new LocationInfo scriptable object by right-clicking in your project folder or selecting 'Assets' then Create/LUTELocation/Location Information. If you do so, you must also create a Variable on the Flow Engine that will reference this new location object.
2. Add a location using the Map Window by right-clicking where you wish your desired location to be and enter the details you wish for the location:

When adding a new location on the map you will be required to enter a suitable name for the new location. Once the location has been created, a new Location Variable will also be created with the name provided and will reference this new scriptable object.

In our example, we name our location 'Info Hub' with the colour white and a custom information icon:

Modifying Location Pin Styles

By default, there are three status of a location:

1. Unvisited: the location has not yet been found.
2. Visited: the player has visited the location.
3. Completed: the player has visited the location and completed all associated Nodes that use the location.

Each of these states will display the location marker differently. We hold a list of these states and their relative display options on the LUTE Map Manager script component found on the Map object.

The display list is essentially a list of individual classes that contain a state and display options. In the example below, we have provided display options for all three states. If no display options are provided then a fallback sprite is used to indicate that this information is missing.

The display options contain a simple collection of display related settings for a location marker. You can adjust these to meet your needs for the default visualisation of any given location marker.

Overriding Location Displays

In certain cases, you may wish to show unique displays for specific location markers. You can achieve this two ways:

1. Override the actual display list found the location information object.
2. Override the list during runtime via. Location Event Handlers.

Overriding the location informaiton display list

Once you have created a custom Location Status Display List (often by duplicating the default one) you will need to reference this on the Location Information object itself. For example, here is the location with the default list:

And here is the location with a custom list:

Overriding via Location Event Handlers

Rather than overriding the lists within the editor scope, you can also do this during runtime. If you have a Node that uses an Location based Event Handler, you will often find that the Event Handler can use a custom location display list for the given location. For example:

This will override the location information's display list during runtime so that it uses the custom list rather than the default one.

Custom Location States and Displays

If you desire to go beyond the three default states a location has and want to modify the visuals of a location marker based on a custom state then this is also possible. The first step is to define the custom state on the display list that the location will use. In this example, we have a custom state with a label of 'Rabbit' where we show a location marker that looks like a rabbit:

Then on a Node we can override Location's current status to custom with the given label 'Rabbit':

Now when this Node is called, the location status will be set to custom and the related location marker will use the display list to draw the related display options for the custom 'Rabbit' option.

You can 'Force Permanent Change' when doing so which forces the location to never update its status regardless of any other runtime changes. If you wish to revert these changes then simply use the Unlock Location Marker Visuals Order:

Using Locations as Event Handlers

Quite often you may wish to not only play content when a player reaches a location but extend this funtionality. For example, you may wish for the player to press the location pin rather than it automatically be triggerd or you may wish to update the location pin visuals depending on the state of a Node. To do so change the Event Handler on a Node to 'Location/OnLocation'.

You can then update the Location field to your desired location variable and customise the properties of this event handling to suit your needs.

Using Locations in Condition Statements

Another common use case for Location Variables is to use them in Condition Statements. For example, perhaps some Orders on a Node will want to fire whereas some will require a Location to be met. To do so:

1. Select your desired Node.
2. Add a Logic>If Order to this Node.

3. Select the Order and observe the Order Inpsector.
4. From the Variable drop-down select the newly created Location Variable.

5. You can either choose 'Equals' or 'Does Not Equal' for the Compare field which will either evaluate and return true if the player is or is not at the location, respectively. In our case, we state is as 'Equal' ensuring that the Orders will not execute until the player has reached this location.
6. If you wish for this behaviour to only be called once after the prior Orders have been completed then we are done. However, if you wish for statement to constantly be checking and execute when player reaches a location then please ensure that the Node is Activated By Update (ensuring that the condition statement is being evaulated every frame or so).

Demo Map Mode

Oftentimes, we are not at the location to test our experiences in full. As such, we provide a way to test locations remotely using 'Demo Map Mode'. When this mode is active, a central target image will be displayed when using the map in Play Mode and this will act as the dummy player location; if this image gets in range of a given location then it will satisfy the location check.

To toggle this mode, select your Flow Engine object in the scene and toggle the 'Demo Map Mode' boolean check:

When unchecked, the physical location of a given device will be used (a permission check will have to be accepted when the experience requires the location of the device and it is the first time the application has been launched on a specific device).