Setting custom mouse cursor images

Cursor icons are often used to indicate the nature of the interaction that can be done with the mouse. Zooming, for instance, might be illustrated by a magnifying glass. Shooting, on the other hand, is usually represented by a stylized target. In this recipe, we will learn how to implement custom mouse cursor icons to better illustrate your gameplay—or just to escape the Windows, OSX, and Linux default GUI. The following screenshot shows a custom magnifying glass mouse cursor when the use's mouse pointer hovers over a Button:

Getting ready

For this recipe, we have prepared the images that you'll need in a folder named IconsCursors in the 1362_01_13 folder.

How to do it...

To make a custom cursor appear when the mouse is over a GameObject, follow these steps:

1. Create a new Unity 2D project.
2. Add a Directional Light item to the scene by navigating to Create | Light | Directional light.
3. Add a 3D Cube to the scene, scaled to (5, 5, 5). Because it was created as a 2D project the cube will appear as a grey square in the Game panel (2D projects have an orthographic camera, so we won't see perspective effects).
4. Import the provided folder called IconsCursors.

   Tip

   Ensure that each image in this folder has been imported as Texture Type Cursor. If they are not, then select this type for each image and click on the Apply button in the Inspector view.

5. Create a C# script class called CustomCursorPointer, containing the following code, and add an instance as a scripted component to the Cube GameObject:

   using UnityEngine;
   using System.Collections;
   
   public class CustomCursorPointer : MonoBehaviour {
     public Texture2D cursorTexture2D;
   
     private CursorMode cursorMode = CursorMode.Auto;
     private Vector2 hotSpot = Vector2.zero;
   
     public void OnMouseEnter() {
       SetCustomCursor(cursorTexture2D);
     }
   
     public void OnMouseExit() {
       SetCustomCursor(null);
     }
   
     private void SetCustomCursor(Texture2D curText){
       Cursor.SetCursor(curText, hotSpot, cursorMode);
     }
   }

   Note

   Event methods OnMouseEnter() and OnMouseExit() have been purposely declared as public. This will allow these methods to also be called from UI GameObjects when they receive the OnPointerEnterExit events.

6. With the Cube item selected in the Hierarchy panel, drag the CursorTarget image into the public Cursor Texture 2D variable slot in the Inspector panel for the Customer Cursor Pointer (Script) component.
7. Save the current scene, and add it to the Build.

   Tip

   You will not be able to see the custom cursors in the Unity Editor. You must build your game application, and you'll see the custom cursors when you run the build app.

8. Build your project. Now, run your built application, and when the mouse pointer moves over the grey square of the Cube, it will change to the custom CursorTarget image that you chose.

How it works...

You have added a scripted object to a cube that will tell Unity to change the mouse pointer when an OnMouseEnter message is received—that is, when the user's mouse pointer moves over the part of the screen where the cube is being rendered. When an OnMouseExit event is received (the users mouse pointer is no longer over the cube part of the screen), the system is told to go back to the operating system default cursor. This event should be received within a few milliseconds of the user's mouse exiting from the collider.

There's more...

There are some details that you don't want to miss.

Custom cursors for mouse over UI controls

Unity 5 UI controls do not receive the OnMouseEnter and OnMouseExit events. They can respond to the PointerEnter/Exit events, but this requires adding the Event Trigger components. To change the mouse pointer when the mouse moves over a UI element, do the following:

1. Add a UI Button to the scene.
2. Add an instance of the C# script class called CustomCursorPointer to the button.
3. With Button selected in the Hierarchy panel, drag the CursorZoom image into the public Cursor Texture 2D variable slot in the Inspector panel for the Customer Cursor Pointer (Script) component.
4. In the Inspector view, add an Event Triggers component to the Button. Choose menu: Add Component | Event | Event Trigger.
5. Add a Pointer Enter event to your Event Trigger component, click on the plus (+) button to add an event handler slot, and drag the Button GameObject into the Object slot.
6. From the Function drop-down menu, choose CustomCursorPointer and then choose the OnMouseEnter method.

   Note

   We have added an Event Handler so that when the Button receives a Pointer Enter (mouse over) event, it will execute the OnMouseEnter() method of the CustomCursorPointer scripted object inside the Button.

7. Add a Pointer Exit event to your Event Trigger component, and make it call the OnMouseExit()method from CustomCursorPointer when this event is received.
8. Save the current scene.
9. Build your project. Now, run your built application and when the mouse pointer moves over the Button, it will change to the custom CursorZoom image that you chose.