Cursors

Important Attention Reminder

Coding Style wiki

---

Cursors is the static facade of CursorSystem that wraps all operations of the CursorManager singleton (the first call automatically finds or creates the [CursorManager] instance), providing cursor visibility/lock control, state switching, and render-reset APIs. Route all cursor operations through Cursors to keep state consistent.

Namespace	OxGKit.CursorSystem
Type	public static class Cursors
Source	Cursors.cs

using OxGKit.CursorSystem;

Quick Start

using OxGKit.CursorSystem;
using UnityEngine;

// Initialize the CursorManager instance (auto-finds the CursorManager Prefab placed in the scene)
Cursors.InitInstance();

// Switch the cursor state by name
Cursors.SetCursorState("Attack");

// Reset back to the default state (first element in the list)
Cursors.ResetCursorState();

// Visibility and lock control
Cursors.SetCursorVisible(true);
Cursors.SetCursorLockState(CursorLockMode.Confined);

General Rules

Singleton and Default State

1. The first call to any Cursors API automatically finds the CursorManager in the scene; if none exists, a [CursorManager] node is created automatically (parented under the OxGKit container node with DontDestroyOnLoad).
2. The first entry in the Cursor States list is the default state; ResetCursorState resets back to the first state.

Attention State names are data (defined by the Cursor States list in the Inspector), not constants; SetCursorState returns false for undefined names — check the return value during development.

---

Initialization

Methods Overview

Method	Description
InitInstance	Initializes the CursorManager instance.

---

InitInstance

public static void InitInstance()

Initializes the CursorManager instance (finds the instance in the scene, or creates one automatically). Recommended to call at game startup.

---

Visibility and Lock

Methods Overview

Method	Description
IsCursorVisible	Checks whether the cursor is visible.
SetCursorVisible	Sets the cursor visibility.
GetCurrentCursorLockState	Gets the current cursor lock mode.
SetCursorLockState	Sets the cursor lock mode.

---

IsCursorVisible

public static bool IsCursorVisible()

Checks whether the cursor is currently visible (i.e., Cursor.visible).

SetCursorVisible

public static void SetCursorVisible(bool visible)

Sets the cursor visibility (i.e., Cursor.visible).

GetCurrentCursorLockState

public static CursorLockMode GetCurrentCursorLockState()

Gets the current cursor lock mode (i.e., Cursor.lockState).

SetCursorLockState

public static void SetCursorLockState(CursorLockMode cursorLockMode)

Sets the cursor lock mode (None, Locked, Confined).

// FPS-style capture (hide and lock to the screen center)
Cursors.SetCursorVisible(false);
Cursors.SetCursorLockState(CursorLockMode.Locked);

// Release when opening a menu
Cursors.SetCursorLockState(CursorLockMode.None);
Cursors.SetCursorVisible(true);

Attention On WebGL, browser restrictions require a user gesture (e.g., a click) before the lock (Locked) takes effect.

---

State Management

Methods Overview

Method	Description
GetAllCursorStates	Gets all cursor states.
GetCursorState	Gets the cursor state with the given name.
GetCurrentCursorState	Gets the current cursor state.
SetCursorState	Switches the cursor state by name.
ResetCursorState	Resets back to the default state (first element).

---

GetAllCursorStates

public static CursorManager.CursorState[] GetAllCursorStates()

Gets all configured cursor states (CursorState).

GetCursorState

public static CursorManager.CursorState GetCursorState(string stateName)

Gets the cursor state with the given name; returns null if not found. Useful for adjusting state parameters at runtime (textures, hotspot, frame rate, etc.).

var cursorState = Cursors.GetCursorState("Default");
cursorState?.SetFrameRate(12);

GetCurrentCursorState

public static CursorManager.CursorState GetCurrentCursorState()

Gets the current cursor state.

SetCursorState

public static bool SetCursorState(string stateName)

Switches the cursor state by name and resets the rendering; returns true on success, or false if the name is not found.

// e.g., switch to the attack cursor when hovering an enemy
if (!Cursors.SetCursorState("Attack"))
    Debug.LogWarning("Cursor state not found!");

ResetCursorState

public static void ResetCursorState()

Resets the cursor state to the default state (first element in the list) and resets the rendering; also used to restore the cursor rendering after RemoveCursorRender.

---

Render Control

Methods Overview

Method	Description
SetIgnoreScale	Sets whether dynamic cursor animation ignores Time.timeScale.
SetScaleToAllCursors	Sets the scale for all cursor states and resets the rendering.
ResetRender	Resets the rendering of the current cursor state.
RemoveCursorRender	Removes the cursor rendering (restores the system cursor).

---

SetIgnoreScale

public static void SetIgnoreScale(bool ignore)

Sets whether the dynamic cursor animation update ignores Time.timeScale (default true, driven by Time.unscaledDeltaTime). Keep it true if the cursor animation must continue while the game is paused (Time.timeScale = 0).

SetScaleToAllCursors

public static void SetScaleToAllCursors(Vector2 scale)

Sets the scale for all cursor states and resets the rendering.

Attention Scaling only takes effect when the state has scalingEnabled on and cursorMode is ForceSoftware.

ResetRender

public static void ResetRender()

Resets the rendering of the current cursor state (a static cursor re-applies its texture; a dynamic cursor resets its animation parameters and replays).

RemoveCursorRender

public static void RemoveCursorRender()

Removes the cursor rendering (clears the current state and restores the system default cursor).

Reminder To restore the custom cursor rendering, call ResetCursorState to re-initialize and reset the rendering (not just SetCursorVisible).