Codex
Assets
Cursor System
Create smooth, responsive context sensitive and animated cursors for your game.
Introduction
The cursor system allows for easy code free context sensitive mouse cursors with support for animation.
The Cursor Animator component handles cursor animation, you should only have 1 of these active at any given time.
With an active Cursor System you can effect the state of the pointer by attaching Cursor State components to desired game objects or through code where you want or need a more bespoke solution.
Cursor State
A cursor state is a scriptable object derived from GameEvent<bool> which represents a state that the game's pointer can be in.
Cursor States are GameEvents of type bool, meaning that when the state is set or removed it is "invoked" raising the game event and indicating its state. As such you can create an event driven system that responds to states being activated or deactivated by simply adding a listener to the state.
1
cursorState.AddListener(HandleThisStateChanged);
Copied!
You can then handle the event as such
1
void HandleThisStateChanged(EventData<bool> param)
2
{
3
//The sender will be the state that was changed
4
var state = param.sender as CursorState;
5
//The value will be true if activated false if deactivated
6
Debug.Log(state.name
7
+ (param.value ? " is active" : " is inactive"));
8
}
Copied!
Hot Spot
A
Vector2 representing the hot spot of the cursor e.g. the "tip" in the case of an arrow or wedge or a pointing finger. This is the finite location of the pointer.Animation
A
CursorAnimation field, this is a custom object which defines the settings of a simple texture animation.Animation.Loop
Indicates rather or not the animation should loop endlessly or if it should animate to the end and hold the last frame
Animation.TextureArray
The set of textures to be animated through. Each frame should be its own texture and should have the same hot point as is defined on the Cursor State.
Animation.FramesPerSecond
How many frames should be shown in 1 second. This value is used to determine the time per frame dictating the speed of the animation.
System Configuration
The cursor system works with a concept of "Cursor State", a state defines the icon to be used and the settings for its animation. At run time the state can be changed by triggers such as Mouse Over Cursor State behavior.
Default State
This default state is the state the system will return to when a component state is no longer true; for example when your pointer exits a Mouse Over Cursor State object it will return to the Default State you defined in the Cursor System.
Cursor Mode
Defaults to Auto, this indicates what type of cursor the game should use. Software Cursors can be more flexible in terms of what you can do with them, however they also tend to show a lag or latency and so Auto or Hardware is recommended.
Hold On Mouse Down
Hold on mouse down is a feature of the Set State function of Cursor System. When a state is being applied, it can optionally be applied as "Hold On Mouse Down". This indicates to the system that if the left mouse button is pressed while the state is active that the state should persist for as long as the left mouse button is held.
Hold On Mouse Down is most often used with drag features such as drag and drop UI elements, drag to resize handles on windows and drag to move handles on windows. This insures that the cursor doesn't switch to default as the mouse is moved around and gives a more natural feel to the user.
You can configure Mouse Over Cursor State and Button Cursor State to set the Hold On Mouse Down value when they are activated. The Hold On Mouse Down value can also be set from code when setting a state.
1
SetState(CursorState state, bool setOnDown, bool holdOnDown);
Copied!
Set On Down the second parameter when set true will cause any current holding state to be overridden with this state.
That is if the system is currently holding a state active due to Hold On Mouse Down, then by passing true into Set On Down the system will override that state with the new state. This is used by Button Cursor State to apply the State On Click value.
Mouse Over Cursor State
This simple component can be added game objects and will cause the state of the cursor to change when the mouse enters the object. Optionally the state can be set to hold on mouse down, which can be useful of hand grab icons such as might be used for a drag to scroll UI element.
Button Cursor State
The button cursor state handles two (2) possible state changes, one for mouse enter similar to the Mousse Over Cursor State and one for On Click. This allows the component to show a 2nd cursor state while the mouse is held down such as highlighted pointer or tapping finger.
Change Cursor Default State
The change cursor default state will change the registered default state on enter and exit.
Examples
In most cases the desired effects can be handled code free, however the system is also designed with programmers in mind and has an easy to use interface. Most of the examples below will require a reference to a desired CursorState. Generally this reference would be set at development time much like you would any reference in Unity.
1
public class SomeBehaviour : MonoBehaviour
2
{
3
public CursorState cursorState;
4
}
Copied!
You can then simply drag the desired state into the "Cursor State" field in the Unity Inspector.
Set Active
The most common way to set state would be to use the Mouse Over Cursor State or Button Cursor State components, however you can also set the state from code.
From the state
1
//The same as calling SetActive(this, false, false);
2
cursorState.Active = true;
Copied!
or
1
cursorState.SetActive(setOnHold, holdOnDown);
Copied!
From Cursor System
1
CursorSystem.SetActive(cursorState, setOnHold, holdOnDown);
Copied!
Get Active
From the state
1
var isActive = cursorState.Active;
Copied!
From Cursor System
1
var activeState = CursorSystem.CurrentState;
Copied!
Cursor State Event
The Cursor State object is derived from GameEvent<bool> and so you can define an event driven structure with changes in pointer state.
1
cursorState.AddListener(HandlerFunction);
Copied!
The handler should take a single parameter of type EventData<bool>
1
private void HandlerFunction(EventData<bool> data)
2
{
3
//The sender is the CursorState
4
var cursorState = data.sender as CursorState;
5
6
//The value indicates rather it was activated or deactivated
7
if(data.value)
8
Debug.Log(cursorStae.name " was activated");
9
else
10
Debug.Log(cursorStae.name " was deactivated");
11
}
Copied!
Last modified 7mo ago