Cursor System
Create smooth, responsive context sensitive and animated cursors for your game.
Last updated
Create smooth, responsive context sensitive and animated cursors for your game.
Last updated
Support us as a GitHub Sponsor and get instant access to all our assets, exclusive tools and assets, escalated support and issue tracking and our gratitude. These articles are made possible by our GitHub Sponsors ... become a sponsor today!
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.
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.
You can then handle the event as such
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.
A CursorAnimation
field, this is a custom object which defines the settings of a simple texture animation.
Indicates rather or not the animation should loop endlessly or if it should animate to the end and hold the last frame
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.
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.
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.
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.
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 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.
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.
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.
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.
The change cursor default state will change the registered default state on enter and exit.
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.
You can then simply drag the desired state into the "Cursor State" field in the Unity Inspector.
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.
or
The Cursor State object is derived from GameEvent<bool> and so you can define an event driven structure with changes in pointer state.
The handler should take a single parameter of type EventData<bool>