Explorers Kit

It’s easy to get lost on an adventure. Grab an Explorers Kit and never loose your way :compass:

FEATURES

  • An In-Game compass with tons of options to configure its behaviour
  • A backpack with the compass attached to it for style points
  • Support for multiple compasses that function independently of one another
  • Everything works out of the box with no complicated setup.
  • Color customization :art:
  • Simple API

GETTING STARTED

:stop_sign: A Compass must be part of a Player/Character child hierarchy to function for now. Non player compasses are a Work in Progress

  1. Find and Install the Explorers Kit package from the community tab

image

  1. Navigate to your templates and drag the EXKCompass template onto your Player template

  2. Drag the EXKBackpack template instead to use the backpack style compass

image

:speech_balloon: You can even drag both or even multiples of both. Compasses galore!

:checkered_flag: Hop into preview mode and take it for a spin. Default behaviour should work out of the box.

The Compass will be set to a default position and rotation to work sensibly out of the box. This happens if the relative position/rotation of the compass is zero. Setting your own position and rotation in the editor will override these defaults.

The Backpack also has default position and rotation as part of the template. Refer to the EXK Backpack section for more information.

EXK Compass

Let’s walk through some of the functionality of the EXKCompass



:speech_balloon: Hover over the properties in the editor to get detailed tooltips on what they do and how to use them.


NAVIGATION : Rotation Mode and Pointer Heading

The navigation properties let you change the navigational behaviour of the compass. Play with these options in the editor and jump into preview to get a better feel for what they do.

Change RotationMode to determine what part of the compass will rotate; the inner direction markers or the pointer needle.

:warning: The Directions RotationMode is more limited compared to the Pointer mode.

In Directions mode the inner markers will always align with the world axes.



:speech_balloon: Changing to Pointer mode opens up a few more options

Setting the compass to Pointer rotation reveals the PointerHeading property. Use this to determine where the pointer needle points. Hover over the property to get a description on what the different PointerHeading choices do

NAVIGATION : Target Tracking

The compass can be given a target to track. This is done by setting a target on the CompassTarget editor property or by modifying the property through code (more on that later)

When there is a valid target the Pointer will point to it if the PointerHeading is set to Target or Hybrid (when within range for Hybrid)

The TargetTrackingRange and TargetLocatedDistance properties will also come into play here.

When the Pointer Heading is set to Hybrid the pointer will only point to the target if it’s within the range set on TargetTrackingRange

image CraytaClient-Win64-Shipping_uwdoea7Gm0

:bulb: Left : TargetTrackingRange also activates the range indicator on the compass when the target is within this range.

:bulb: Right: TargetLocatedDistance activates the found indicator on the compass when the distance from the compass to the target is less than or equal to it.


OTHERS & EVENTS

Bind to the OnTargetFound event to execute functionality when the active tracking target is located. Set ClearOnFound to clear the compass target once the current target is found. A new target will need to be set again for tracking to begin

The Compass will be enabled and working by default. You can change this through disabling the StartEnabled property should you need to. The compass can be re-enabled through code.


THEMES & CUSTOMIZATION

EXK Compass has 6 pre-defined color themes; Default, Haunted, Coral, Caribbean, Forest and Cyberpunk

If you’d like to use your own custom colors set the CompassTheme property on the compass to Custom

When set to Custom the compass will use colors defined on the EXKUICompass asset properties. Edit these properties to set up your own colors.

image
‎ ‎ Set theme to Custom and modify properties below

image

:stop_sign: Avoid modifying the properties not contained in the Asset properties section if you’re not sure of what they do.

image

:bulb: The EXKUICompass widget is found on the EXK Compass template right under the EXKCompass script


CUSTOM POINTER

:speech_balloon: Try changing the pointer mesh to make your compass truly yours



:bulb: You can change the pointer mesh by navigating to the Pointer Mesh entity in the EXKCompass hierarchy and changing the mesh asset. Play with the position, rotation and scale to get it in place.

Remember to align the front of your pointer to face the North marker on the compass

CraytaClient-Win64-Shipping_8xeEFYrsPv

:stop_sign: Do not alter the transform of the Pointer Pivot. Only modify the Pointer Mesh

:speech_balloon: HIt play and watch your fancy custom compass in action

EXK Backpack



The EXKBackpack template is essentially just an EXKCompass with a backpack mesh as its parent.

image

The EXKBackpack script is responsible for setting up this backup on a player template.

:bulb: The Backpack template has some defaults set up to attach the backpack to a Player’s back if it’s dragged onto a player template without any further modifications

If AttachOnStart is set to true, the backpack will try to attach itself to it’s parent if it has one.

The SocketName property is used when attaching the backpack to a Player to determine the socket to attach to

The Offsets help position and rotate the backpack in relation to its parent

Utiliy

:warning: Since the EXKCompass script is on the compass object it can be a bit troublesome to call functions using methods such as SendToScript() on the Player/Parent of the compass. You will have to get a reference directly to the compass object. Making use of SendToScripts() on the parent won’t work as the EXKCompass script doesn’t live on the Player; it lives on the Compass.

The Explorers Kit package provides a Utility script to deal with this problem.

image

Introducing the EXKCompassEventHandler script

:bulb: Add the Compass Event Handler script on the Player or parent of the compass object. Having done so you can now make use of SendToScripts() to call the API functions on the Player/parent and the event handler utility script will pass it on to any children.

:bulb: You can also nest the event handler script so function calls will be passed on to children which may then pass it onto their children. You might have noticed the EXK Backpack also has an Event Handler script on it to pass the API calls to its child compass (or compasses if you have more than one)

Making use of the EXKCompassEventHandler makes scripting for the compasses much easier and hassle free. You can modify multiple compasses with just one function call.

:warning: Modifying a specific individual compass would still require a direct reference to that compass (this is not relevant if your Player/parent only has a single compass in their hierarchy)

:stop_sign: It’s worth mentioning, using the event handler with multiple layers of nesting can be bad for performance. Especially if you have objects that have lots of children. The EXKCompassEventHandler script works by getting all the children of the entity it’s attached to and calling SendToScript() on each child and so on down the chain if those children also have an event handler script.

Just something to keep in mind. In most normal use cases it shouldn’t be a problem. Just don’t go crazy with giving your players hundreds of compasses.
If you plan on having only one compass in your player or parent objects hierarchy then perhaps maintaining a direct reference would be easier.

API

EXKCompass:ToggleCompass(isEnabled)

Turns the compass on or off. When turned off the compass will not update.

isEnabled : boolean | Pass in true to enable compass and false to disable compass


EXKCompass:UpdateTarget(targetEntity)

Set a new target for the compass. Will be ignored if the entity passed in is not valid

targetEntity : entity | Pass in the entity to act as the new target for the compass


EXKCompass:ClearTarget()

Clears the target on the compass so it has no active target


EXKCompass:SetCompassTheme(themeCode)

Changes the color theme of the compass

themeCode : integer | Number from 0 to 6 (inclusive)

0 = Custom
1 = Default
2 = Haunted
3 = Coral
4 = Caribbean
5 = Forest
6 = Cyberpunk

If an invalid number is passed in (not from 0-6) the default theme will be used


EXKBackpack:Wear(wornBy)

Attaches the backpack to a Player or parent object. This function applies the offset position and rotation set in the script properties

wornBy : entity | New parent to try and attach this backpack too

1 Like