Cursor API
TIM COOPER / Anonymous
Oct 22, 2012|2:0 Min
Cursor API


During the last ninja camp Shawn and I worked on getting hardware cursors into Unity, and now in Unity 4.0 they are ready. Built in support for cursors in Unity has been a heavily requested feature, and we are happy to see it in a state ready for you to use.

The cursor API is very simple and allows you to configure a default cursor for your project as well as change the cursor on demand. When setting a cursor you can specify if you want the cursor to be a hardware cursor or a software cursor. If you use a hardware cursor then rendering will be handled by the OS, otherwise Unity will render the cursor for you after everything else in the scene has been rendered.

So why would I want to use hardware cursors?
Hardware cursors are cursors managed by the operating system. They are framerate independent and work in the same way that operating system cursors work. This means that if your game is running slowly mouse input will still feel nice and not be laggy. This helps with the user experience.

Why would I ever use a software cursor over a hardware cursor?
On some platforms hardware cursors have limitations, for example on Windows the cursor is limited to a version specific resolution (32x32). In situations where you want a larger cursor you may be required to use a software cursor.

How do I configure cursors?
In the project settings for your project you will notice that there are some new options for cursors:

By setting the 'Default Cursor' and the 'Cursor Hotspot' (click position in pixels from the top left of image) you can configure the default cursor for your application. The default cursor will replace the standard operating system arrow that is normally used.

The API to change cursor at runtime is quite simple:
static void SetCursor (Texture2D texture, CursorMode cursorMode);
static void SetCursor (Texture2D texture, Vector2 hotspot, CursorMode cursorMode);

Where CursorMode is either Auto or ForceSoftware. When using Auto hardware cursors will be used if supported on the platform (with the texture being resized if required). ForceSoftware does as the name indicates. It is safe to mix hardware and software cursors.


// mouse over cursor
var cursorTexture : Texture2D;
// cursor mode to use
var cursorMode : CursorMode = CursorMode.Auto;
// cursor hotspot (pixels from top left of image)
var hotSpot : Vector2 =;

function OnMouseEnter () {
// when we mouse over this object, set the cursor
Cursor.SetCursor(cursorTexture, hotSpot, cursorMode);

function OnMouseExit () {
// when we mouse off this object restore the default cursor (passing null)
Cursor.SetCursor(null,, cursorMode);