Console Cursors 1.6.1

INTRODUCTION
1.1 SETTING UP THE CURSOR
1.1A SETTING UP THE CURSOR
1.2 CUSTOMIZING THE CURSOR
1.3 CURSOR SCALE
1.4 CURSOR TOOLTIPS
1.5 CHANGING TOOLTIP TEXT
2.1 INSPECTOR WALKTHROUGH
3.1 CANVAS CONFIGURATION
3.2 ADDING BUTTONS TO A SCENE
4.1 BREAKING DOWN FUNCTIONS
5.1 CONFIGURING INPUT MANAGER
5.2 CURSOR MOVEMENT
5.3 CURSOR BOUNDS AND OFFSETS
5.4 ADJUSTING KEYBOARD INPUT
5.5 PAUSING/RESUMING AT RUNTIME
5.6 USING THE NAMESPACE
6.1 CONFIGURING MOUSE INPUT
6.2 SWITCHING INPUT CONTROLS
7.1 TIPS

 

INTRODUCTION

Console Cursors is a quick and easy out-of-the-box solution for anyone trying to achieve a modern controller cursor becoming popularized in recent AAA games. With a simple boundaries detection, 25 unique hover animations, 25 different cursor styles to choose from, 3 different button styles, and more, you can make your game have a AAA quality console/controller navigation in just a few minutes. Console Cursor can be used for UGUI Screen Space and World Space offering endless possibilities for your game or project.

 

1.1 SETTING UP THE CURSOR

To get started, add the “CursorControl” to a scene in your project. Assign the Render Camera variable on the Canvas component to the camera functioning as your main camera in your scene. Now, make sure your Camera Main variable on the CursorController component to the same camera as your Render Camera on the Canvas component. If you press play, the cursor is already controllable through the keyboard inputs for the Horizontal and Vertical axes as well as the 25 styles in the inspector, assuming the Input Manager is still using default settings for the axis’. For Input Manager configuration, go to section 5.1

 

1.1A MOVEMENT SMOOTHING

To change the acceleration and deceleration of the cursor, go to the Input Manager and adjust the Sensitivity and Gravity settings on the Horizontal and Vertical Axis’. The larger the gravity, the faster the cursor decelerates. The higher the sensitivity, the faster the cursor accelerates

 

1.2 CUSTOMIZING THE CURSOR

For all 25 cursor styles, you can enable or disable any part that you don’t want to use and the animation will still function properly. Each cursor has it’s own animation and animator so modifying one will not affect the others. 

1.3 CURSOR SCALE

All the cursors have a 1-1 ratio in their scaling, and they all have a parent Rect Transform that can be modified. Simply adjust the scale values on the parent object of each style and it will adjust the scale without affect the animations.

1.4 CURSOR TOOLTIPS

 To enable and adjust the tooltips, all you have to do is adjust the 4 values in the figure to the right. The width and the height should be set to the equivalent values on the Tooltip game object. The Offsets are the pixel values that the tooltip which switch if it starts to move off screen.

 

To call the Tooltip’s fade function you have to add a new Event Trigger component onto the button that you want to activate a tooltip on. Then, set Pointer Enter and Pointer Exit Event Type’s to CursorDemo.ShowTooltip() and CursorDemo.HideTooltip() respectively. Make sure the game object variable slots are filled with CursorControl.

1.5 CHANGING TOOLTIP TEXT

To adjust the text on the tooltip, call Text.text in the event trigger, which will modify the string value of whatever UI Text game object is in the variable..

Title Text and Body Text are child objects of Tooltip.

2.1 INSPECTOR WALKTHROUGH

Horizontal Axis – The name of the Axis in the Input Manager being used to control the horizontal movement of the cursor.

Vertical Axis – The name of the Axis in the Input Manager being used to control the vertical movement of the cursor.

Horizontal Speed – The horizontal movement speed of the cursor.

Vertical Speed – The vertical movement speed of the cursor.

Hover Multiplier – The speed multiplier for when the cursor is hovering over a button. 0 = 0% of original movement speed and 1 = 100% of original movement speed.

Cursor Rect – The UI Element with a Rect Transform that will function as the cursor. 

Boundaries – The Rect Transform that will be used as the edges of the screen for detection.

Xmin Offset – The amount of pixels from the left side of the screen that the cursor will detect as a boundary.

Xmax Offset – The amount of pixels from the right side of the screen that the cursor will detect as a boundary. 

Ymin Offset – The amount of pixels from the bottom of the screen that the cursor will detect as a boundary.

Ymax Offset – The amount of pixels from the top of the screen that the cursor will detect as a boundary.

Cursor Object – The current active cursor style, and the origin point at which the button click detection will be based on.

Cursors – The list of cursor game objects available in a scene to be active.

Mouse Event System – The game object with the Standalone Input Module accessing mouse input.

Fade Bool – The name of the bool variable on the Animator controlling the transitions for the cursors animations.

Tooltip Rect – The Rect Transform holding the position of the tool tip.

ToolTip Width – The ‘Width’ of the Tooltip game object. This is how Console Cursors determines the size boundaries at runtime.

Tooltip Height – The ‘Height’ of the Tooltip game object. This is how Console Cursors determines the size boundaries at runtime.

Tooltip Offset X – The Pos X of the game object ‘container’ that is used to re-position the tooltip so it always stays visible on the screen. Adjusting this value will adjust how far left or right the tooltip positions itself when re-aligning.

Tooltip Offset Y – The Pos Y of the game object ‘container’ that is used to re-position the tooltip so it always stays visible on the screen. Adjusting this value will adjust how far left or right the tooltip positions itself when re-aligning.

3.1 CANVAS CONFIGURATION

Make sure the canvas is set to Screen Space – Camera or World Space. There is NO compatibility yet for Screen Space – Overlay.This is the only way that the UI will be able to layer properly. Order in Layer can be adjusted to determine what Canvases appear on top. The higher the number, the more on top a canvas will be. Also, you can also just increase the order in layer of the CursorControl canvas if your project has specific ordering for canvases already set previously.

 

3.2 ADDING BUTTONS TO A SCENE 

Adding buttons is extremely simple. For demonstration, we will use the button prefabs available with the Console Cursors package. Drag any of the button prefabs into a canvas (any canvas will work).

There are 2 empty Event Trigger components on each button. All you need to do to have the buttons properly respond to the cursor movements and inputs is to fill them in.

Fill all 4 object slots with the CursorControl object in your scene. Select the functions as the following:

Pointer Enter – CursorController.HoverSpeed
Pointer Exit – CursorController.NormalSpeed

Pointer Enter – CursorController.FadeIn
Pointer Exit – CursorController.FadeOut

And that’s it! The buttons should now be responding. You can copy and paste the Event Trigger components onto any button, including your own, and it will function the same.

4.1 BREAKING DOWN FUNCTIONS

All the functions that will need to be called to have the cursor function properly technically and visually are in the list below. All other functions in the script are handled in the background and do not need to be modified.

HoverSpeed() – Calls a function that adjust the speed of the cursor to the multiplied value set on the Hover Multiplier slider. The slider has a value range of 0-1 with 0 equaling 0% of the original speed and 1 equaling 100% of the original speed.

NormalSpeed() – Calls a function that returns the speed of the cursor to the starting Horizontal Speed and Vertical Speed.

FadeIn() – Calls a function that sets the bool value of the string Fade Bool to True. Fade Bool can be modified in the inspector of the CursorController script. The script uses the Animator component on the cursorObject.

FadeOut() – Calls a function that sets the bool value of the string Fade Bool to False.

ShowTooltip() – Calls a function that sets the bool value of the tooltip’s fade to True.

HideTooltip() – Calls a function that sets the bool value of the tooltip’s fade to False.

SwitchingToConsoleInput() – Calls a function that switches from mouse input to hand-held controller input. First, it will check to make sure you have a mouseEventSystem in the scene. Make sure to fill the variable Mouse Event System in the inspector for CursorController or the script will not function properly. The cursor will then become visible through an alpha channel switch (from 0-1). The cursor event system is enabled and the mouse event system is disabled. in Runtime, this will immediately switch the input Controls.

SwitchingToMouseInput() – Calls a function that switches from console hand-held input to mouse input controller. First, it will check to make sure you have a mouseEventSystem in the scene. Make sure to fill the variable Mouse Event System in the inspector for CursorController or the script will not function properly. The cursor will then become invisible through an alpha channel switch (from 1-0). The cursor event system is disabled and the mouse event system is enabled. in Runtime, this will immediately switch the input Controls.

5.1 CONFIGURING INPUT MANAGER

Console Cursors uses 3 Axes in the Input Manager: Horizontal, Vertical, and Submit. Horizontal and Vertical are modifiable through the inspector on the CursorController script. Submit is the default button for clicking a button.

 

5.2 CURSOR MOVEMENT

The sensitivity values on Horizontal and Vertical are set to 1 solely for consistency with keyboard controls. The keyboard input Axes are also named Horizontal and Vertical so Unity will read them both simultaneously. Keyboard input is from 0-1 while a joystick has small incremental values. You can adjust the Sensitivity down to increase the smoothness of the movement of the cursor, but make sure to also increase the Horizontal Speed and Vertical Speed.

5.3 CURSOR BOUNDS AND OFFSETS

To adjust the area of the screen that the cursor can move, adjust the Xmin, Xmax, Ymin, and Ymax Offset values.

5.4 ADJUSTING KEYBOARD INPUT

If you choose to control the cursor with keyboard input, the first two Axes in the Input Manager have Positive and Negative button values controlling the movement. Modify those values to change which keys will move the cursor.

You can use this same method to adjust the Submit Axis joystick and keyboard button.

5.5 PAUSING/RESUMING AT RUNTIME

Depending on the genre of your game you might want to disable control of the cursor and re-enable it at specific points. You can enable/disable the cursor by calling PauseGame() and ResumeGame() on the CursorControl object.

5.6 USING THE NAMESPACE

To reference the CursorController.cs script through another C# script, use the following:

using SlimUI.ConsoleCursors;

6.1 CONFIGURING MOUSE INPUT

If you want to disable console controls and enable the mouse input, or start with the mouse input instead, simply add an Empty Game object and add the Standalone Input Module component. Assign the game object to the Mouse Event System variable slot on the CursorController script on CursorControl. Change the Alpha value on CanvasGroup from 1 to 0 to hide the console cursor. 

Make sure the Standalone Input Module Event System is active and the CursorControl Event System is disabled!

6.2 SWITCHING INPUT CONTROLS

To switch from Hand-Held to Mouse and vice versa have any script call the Switching functions (Section 4.1) corresponding to the desired input controller. In an options menu, if you are pressing a button to change input, call CursorController.SWITCHFUNCTION() and the script will handle the rest.

7.1 TIPS

Every variable has a tooltip describing it’s function, so you don’t have to guess what each variable is for!

Just hover over the variable to see it’s description in case something is confusing. 

To make sure that Console Cursors input is functioning properly, and the ability to switch between Mouse & Keyboard / Controller, use the EventSystem attached to the parent object. 

 

For programmers, the code has been documented to ensure adjusting code is quick and easy. 

NOTE* Each cursor style has its own Animations and Animator, so modifying one will not affect the others.

NOTE* Do NOT rename elements of the Cursor Styles as the Animator uses exact names to reference the key frame animations.

NOTE* Make sure at the start of the scene there is only 1 Event System active in the scene.

NOTE* Make sure that on the CursorControl object, BOTH Render Camera and Camera Main variables are filled with the same camera object or the cursor will not be able to detect the UGUI elements properly.

Have a suggestion to improve the documentation or package?

5 + 1 =