Categories & Tags
Archive

Cursor API

October 22, 2012 in Demos, Tutorials and Tips, Technology by

Hi,

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 (32×32). 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.

Example:

// 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 = Vector2.zero;

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, Vector2.zero, cursorMode);
}

Share this post

Comments (24)

Comments are closed.

22 Oct 2012, 7:36 am

Another nice feature incoming :)
Good job!

Nicolas M
22 Oct 2012, 7:42 am

Great news.

Will we see other *Ninja powered* awesome projects in Unity 4 ? (For example the voxel editor)

puk
22 Oct 2012, 7:45 am

Will it work when exporting to flash?

Foriero
22 Oct 2012, 7:56 am

Nice and what is the release date of Unity 4? :-) We are waiting and you (Unity) are silent about it. Would be nice to update preordered customers about progress of Unity 4 so that we can take strategic decision when releasing our games. But anyway we are looking for Unity 4 and you guys do really nice job. Thank you.

22 Oct 2012, 8:08 am

@Puk yes it works with Flash.

Breakmachine
22 Oct 2012, 8:33 am

Foreiro: Or the awesome drawcall by drawcall thingy?

Tim Cooper
22 Oct 2012, 8:44 am

@Foriero: We are working hard crushing all the bugs that have come in from our beta cycle. If you have preordered you should have access to the preorder beta which has the features that the release version of Unity 4.0 will have. You should consider looking at your project in the beta.

22 Oct 2012, 11:35 am

Great stuff Tim!

22 Oct 2012, 11:45 am

Nice feature!
Thanks guys.

Patrick Hogenboom
22 Oct 2012, 1:06 pm

Does this API also alllow us to position the cursor ?

22 Oct 2012, 2:47 pm

Excellent, much needed. Also good to know it works with flash deploy :)

Vaios Kalpias
22 Oct 2012, 11:58 pm

Thanks for the feature guys, it is greatly appreciated!

Lux
23 Oct 2012, 3:23 am

Nice!

23 Oct 2012, 6:21 am

As outlined by Patrick Hogenboom, while you’re at it, add cursor positioning, that’d be great ! ;)

27 Oct 2012, 9:08 am

My brother suggested I may like this blog. He was once totally right. This submit truly made my day. You cann’t consider simply how much time I had spent for this info! Thank you!

29 Oct 2012, 10:36 pm

So to make animated cursors we have to make multiple calls to SetCursor? Is that advisable?

1 Nov 2012, 9:28 am

Any chance that we will have the ability to set the position of the cursor, or cursor clipping area through Unity? I was surprised to find out that I needed to use a DLL and C# to do this (limiting cursor within a bounding box); I also had to create an editor script to reset the clipping area when paused, as modifying this system info for the cursor was still active. It works, thanks to a script on the forum, but it feels a little hack-ish and that this should be a simple function in Unity. I hope we see this soon!

2 Nov 2012, 8:33 am

Nice move toward a serious RIA system :)

Can’t wait to plug in my cursor management into it (http://edrivenunity.com/unity/cursors/ – old cursor demo made with Unity 3.5)

Even Flash had no hardware cursors until recently… so this is a great great move. Nice to see that it’s not all mobile-oriented.

9 Nov 2012, 1:45 am

Weren’t hardware cursors dropped in Direct3D 11? Are you using the standard Windows cursor with ClipCursor() or so in Unity 4.0?

Anyway, this is a nice change. Sprite cursors become really awkward to use if the frame rate drops :)

13 Nov 2012, 5:52 am

Nice feature Tim. Thanks for this wonderful article.

Hudson
6 Dec 2012, 2:16 am

Great feature!
How about the cursor movement limitation? Like ClipCursor.

29 Dec 2012, 9:31 am

Nice feature

Aubrey
10 Jan 2013, 2:41 am

Great work, but yeah, really agree with hudson. We have “snap cursor to center” or “free cursor”, but nothing in between. It can be frustrating for a cursor game if you have multiple screens and you move outside the first monitor… or… if you want to do a gesture heavy mouse game in web player, you’re kinda screwed: if you “fake” your own cursor, it completely changes how the mouse feels compared to your settings in the OS, which is really offputting.

Leave a Reply

Comments are closed.