跳到主要内容

Cursors

重要 注意 提醒

Coding Style wiki​

Cursors 是 CursorSystem 的静态门面 (Facade)，内部包装 CursorManager 单例的所有操作 (首次调用会自动查找或创建 [CursorManager] 实例)，提供游标显示/锁定控制、状态切换与渲染重置等 API；建议一律通过 Cursors 进行游标操作，保持状态一致。

命名空间OxGKit.CursorSystem
类型public static class Cursors
源码Cursors.cs
using OxGKit.CursorSystem;

快速上手​

using OxGKit.CursorSystem;
using UnityEngine;

// 初始 CursorManager 实例 (场景上已放置 CursorManager Prefab 则会自动查找)
Cursors.InitInstance();

// 按名称切换游标状态
Cursors.SetCursorState("Attack");

// 重置回默认状态 (列表第一条)
Cursors.ResetCursorState();

// 显示与锁定控制
Cursors.SetCursorVisible(true);
Cursors.SetCursorLockState(CursorLockMode.Confined);

通用规则​

单例与默认状态​

  1. 任一 Cursors API 首次被调用时，会自动查找场景上的 CursorManager；找不到则自动创建 [CursorManager] 节点 (整理至 OxGKit 容器节点下并 DontDestroyOnLoad 常驻)。
  2. Cursor States 列表第一条即为默认状态，ResetCursorState 会重置回第一条状态。

注意 状态名称属于数据 (依 Inspector 上的 Cursor States 配置)，并非常量；SetCursorState 传入未定义的名称会返回 false，开发时建议检查返回值。

初始​

方法总览​

方法说明
InitInstance初始 CursorManager 实例。

InitInstance​

public static void InitInstance()

初始 CursorManager 实例 (查找场景上的实例，找不到则自动创建)，建议在游戏启动时调用。

显示与锁定​

方法总览​

方法说明
IsCursorVisible检查游标是否显示。
SetCursorVisible设置游标显示开关。
GetCurrentCursorLockState获取当前游标锁定模式。
SetCursorLockState设置游标锁定模式。

IsCursorVisible​

public static bool IsCursorVisible()

检查返回游标当前是否显示 (即 Cursor.visible)。

SetCursorVisible​

public static void SetCursorVisible(bool visible)

设置游标显示开关 (即 Cursor.visible)。

GetCurrentCursorLockState​

public static CursorLockMode GetCurrentCursorLockState()

获取当前游标锁定模式 (即 Cursor.lockState)。

SetCursorLockState​

public static void SetCursorLockState(CursorLockMode cursorLockMode)

设置游标锁定模式 (None、Locked、Confined)。

// FPS 类操作 (隐藏并锁定于画面中心)
Cursors.SetCursorVisible(false);
Cursors.SetCursorLockState(CursorLockMode.Locked);

// 打开菜单时释放
Cursors.SetCursorLockState(CursorLockMode.None);
Cursors.SetCursorVisible(true);

注意 WebGL 平台受浏览器限制，锁定 (Locked) 需由用户手势 (点击等) 触发才会生效。

状态管理​

方法总览​

方法说明
GetAllCursorStates获取所有游标状态。
GetCursorState获取指定名称的游标状态。
GetCurrentCursorState获取当前游标状态。
SetCursorState按名称切换游标状态。
ResetCursorState重置回默认状态 (列表第一条)。

GetAllCursorStates​

public static CursorManager.CursorState[] GetAllCursorStates()

获取所有已配置的游标状态 (CursorState)。

GetCursorState​

public static CursorManager.CursorState GetCursorState(string stateName)

获取指定名称的游标状态，找不到返回 null；可用于运行时动态调整状态参数 (贴图、热点、速率等)。

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

GetCurrentCursorState​

public static CursorManager.CursorState GetCurrentCursorState()

获取当前游标状态。

SetCursorState​

public static bool SetCursorState(string stateName)

按名称切换游标状态并重置渲染，切换成功返回 true；找不到该名称返回 false。

// 例如滑入敌人时切换攻击游标
if (!Cursors.SetCursorState("Attack"))
    Debug.LogWarning("Cursor state not found!");

ResetCursorState​

public static void ResetCursorState()

重置游标状态为默认状态 (列表第一条) 并重置渲染；也可用于 RemoveCursorRender 后恢复游标渲染。

渲染控制​

方法总览​

方法说明
SetIgnoreScale设置动态游标动画是否忽略 Time.timeScale。
SetScaleToAllCursors设置所有游标状态的缩放比例并重置渲染。
ResetRender重置当前游标状态的渲染。
RemoveCursorRender移除游标渲染 (恢复系统游标)。

SetIgnoreScale​

public static void SetIgnoreScale(bool ignore)

设置动态游标动画更新是否忽略 Time.timeScale (默认 true，使用 Time.unscaledDeltaTime 驱动)；若需要游标动画在游戏暂停 (Time.timeScale = 0) 时持续播放，请保持为 true。

SetScaleToAllCursors​

public static void SetScaleToAllCursors(Vector2 scale)

设置所有游标状态的缩放比例并重置渲染。

注意 缩放仅在该状态启用 scalingEnabled 且 cursorMode 为 ForceSoftware 时才会生效。

ResetRender​

public static void ResetRender()

重置当前游标状态的渲染 (静态游标重新应用贴图；动态游标重置动画参数重新播放)。

RemoveCursorRender​

public static void RemoveCursorRender()

移除游标渲染 (将当前状态置空并恢复系统默认游标)。

提醒 若要恢复自定义游标渲染，请调用 ResetCursorState 重新初始并重置渲染 (而非仅调用 SetCursorVisible)。