In your application or game you might wish to be able to see other users on the map. The COALA Unity package provides a solution for this out of the box.

Getting Started

As a first step you need to create a prefab that represents other users on the map. You can also use the "Other user Kite" prefab we use in or PaperMap Example. In any case the prefab needs to have the CoalaUserOnMap component attached to it.

When you have your prefab ready to go, create a new empty Game Object in the scene you want other users to appear in. This scene should also contain your COALA map. Attach the CoalaOtherUserPositionUpdateSystem component to the newly created Game Object. In the Inspector for CoalaOtherUserPositionUpdateSystem you should see an empty "User On Map Prefab" field. Insert the prefab you created previously in here.

Visibility Settings

There are several visibility options you can choose from in the CoalaOtherUserPositionUpdateSystem component:

• Never means that other users will not be able to see this particular user on the map

• Always means that other users will always see this particular user on the map

• Only in specified areas means that this particular user will only show up in the areas defined in the COALA back-end for other users.

Visibility settings can be set via the Inspector or via script.

While seeing other users in the app can enhance the experience for your users, they should be able to choose not to share their location with other people if they are not comfortable doing so. In fact you should let them opt-in to sharing their location before showing it to other users. That's why the Visibility Settings field in CoalaOtherUserPositionUpdateSystem is set to Never by default.

User Visibility Range

When getting other users' location from COALA you are typically only interested in the location of users within a certain area. The borders of this area can be set in the See Other Users Range field. A value of 1000 for example means that you want to be able to see the location from users that are within a 2km x 2km square around your current GPS location.

Update cycle

To get updates about users' position from the server, requests need to be sent out regularly. The frequency of these requests can be modified via the values under Update Cycle. The new data request frequency is also dependent on your own movement and on the number of users that are currently nearby. Generally speaking, every time you move you request new data from the server with the following restrictions.

• Min Seconds Between Updates specifies the minimum time between two requests. So even if you move all the time, new requests are only sent out after "Min Seconds Between Updates" seconds

• Max Seconds Between Updates specifies the maximum time between two requests. Even if you do not move at all a request will be sent out at least every "Max Seconds Between Updates" seconds

When a request returns 0 users nearby, we can expect that the next request also will not contain any new users in most cases. That is why we can decrease the frequency for updates. In this case Min Seconds Between Updates No Other Users overrides Min Seconds Between Updates and Max Seconds Between Updates No Other Users overrides Max Seconds Between Updates.

Extend functionality

While the COALA Unity Package offers an out of the box solution for basic needs, you might want to extend some functionality to better suit your needs.

Custom payloads

A common need is to associate certain data with a particular user. This is for example useful if you want to display a username over another user's head. In this case you can modify a Payload field in the COALA request. To do this you have to extend CoalaOtherUserPositionUpdateSystem and override the GetPayload() method. Here you can return a string that represents the data you want other users to see. An easy way to do this is to create a CustomPayload struct with the relevant variables. You can then use Unity's JsonUtility class to parse the struct into a string.

using Thoughtfish.Coala.OtherUserVisibility;

using UnityEngine;

public class OtherUserPositionUpdateSystem : CoalaOtherUserPositionUpdateSystem

{

public CustomPayload payload;

protected override string GetPayload()

{

return JsonUtility.ToJson(payload);

}

}

[System.Serializable]

public struct CustomPayload

{

public string username;

}

In the above example you can set the username via the Inspector or by setting the payload of OtherUserPositionUpdateSystem directly.

After sending the custom payload to the server you also need to be able to parse the custom payload in the response. To do that extend CoalaMapUser and override UpdatePayload(string payload). Here you can handle the payloads from other users.

using Thoughtfish.Coala.OtherUserVisibility;

using TMPro;

using UnityEngine;

public class OtherPlayerOnMap : CoalaUserOnMap

{

public TextMeshProUGUI _nameText = null;

protected override void UpdatePayload(string payload)

{

CustomPayload payloadObject = JsonUtility.FromJson<CustomPayload>(payload);

_nameText.text = payloadObject.username;

}

}

Other