跳到主要内容

CursorManager

重要 注意 提醒

Coding Style wiki​

CursorManager 是 CursorSystem 的游标管理器 (MonoBehaviour 单例)，管理 Inspector 上配置的 CursorState 状态列表，并在 Update 驱动动态游标的序列帧动画；可通过 Samples 导入 CursorManager Prefab 拖拽至启动场景，或由 Cursors 门面自动创建。

命名空间OxGKit.CursorSystem
类型[DisallowMultipleComponent] public class CursorManager : MonoBehaviour
源码CursorManager.cs
using OxGKit.CursorSystem;

提醒 CursorManager 的实例方法与 Cursors 静态门面一一对应 (单例的获取方法为 internal)，建议一律通过 Cursors 调用，无需自行持有实例引用。

快速上手​

using OxGKit.CursorSystem;

// CursorManager 由 Cursors 门面自动查找或创建 (单例)
Cursors.InitInstance();

// 在 Inspector 配置 Cursor States 后，即可按名称切换
Cursors.SetCursorState("Loading");

通用规则​

单例与生命周期​

  1. 首次通过 Cursors 访问时，会自动查找场景上的 CursorManager；找不到则自动创建 [CursorManager] 节点。
  2. Awake 时会自动整理至 OxGKit 容器节点下并 DontDestroyOnLoad 常驻，同时将当前状态初始为列表第一条。
  3. Start 时会重置渲染 (应用默认状态)；Update 依 Ignore Time Scale 设置驱动当前状态的动态游标动画。
  4. OnEnable 会重置回默认状态；OnDisable 会移除游标渲染 (恢复系统游标)。

Inspector 成员​

成员说明
Ignore Time Scale动态游标动画是否忽略 Time.timeScale (默认 true，使用 Time.unscaledDeltaTime 驱动)。
List Cursor StatesCursorState 状态列表，第一条即为默认状态 (内置一条 Default 状态，frameRate 为 30)。

方法总览​

方法说明
SetIgnoreScale设置动态游标动画是否忽略 Time.timeScale。
GetCurrentCursorLockState获取当前游标锁定模式。
SetCursorLockState设置游标锁定模式。
IsCursorVisible检查游标是否显示。
SetCursorVisible设置游标显示开关。
SetScaleToAllCursors设置所有游标状态的缩放比例并重置渲染。
GetAllCursorStates获取所有游标状态。
GetCursorState获取指定名称的游标状态。
GetCurrentCursorState获取当前游标状态。
SetCursorState按名称切换游标状态。
ResetCursorState重置回默认状态 (列表第一条)。
ResetRender重置当前游标状态的渲染。
RemoveCursorRender移除游标渲染 (恢复系统游标)。

SetIgnoreScale​

public void SetIgnoreScale(bool ignore)

设置动态游标动画更新是否忽略 Time.timeScale (默认 true，使用 Time.unscaledDeltaTime 驱动)。

GetCurrentCursorLockState​

public CursorLockMode GetCurrentCursorLockState()

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

SetCursorLockState​

public void SetCursorLockState(CursorLockMode cursorLockMode)

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

IsCursorVisible​

public bool IsCursorVisible()

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

SetCursorVisible​

public void SetCursorVisible(bool visible)

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

SetScaleToAllCursors​

public void SetScaleToAllCursors(Vector2 scale)

设置所有游标状态的缩放比例并重置渲染 (缩放仅在 scalingEnabled + ForceSoftware 时生效)。

GetAllCursorStates​

public CursorState[] GetAllCursorStates()

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

GetCursorState​

public CursorState GetCursorState(string stateName)

获取指定名称的游标状态，找不到返回 null。

GetCurrentCursorState​

public CursorState GetCurrentCursorState()

获取当前游标状态。

SetCursorState​

public bool SetCursorState(string stateName)

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

ResetCursorState​

public void ResetCursorState()

重置游标状态为默认状态 (列表第一条) 并重置渲染。

ResetRender​

public void ResetRender()

重置当前游标状态的渲染。

RemoveCursorRender​

public void RemoveCursorRender()

移除游标渲染 (将当前状态置空并恢复系统默认游标)；若要恢复自定义游标渲染，请调用 ResetCursorState 重新初始并重置渲染。

CursorState​

游标状态 (可序列化，嵌套于 CursorManager)，定义单一游标状态的渲染类型、贴图、热点与动画参数；可在 Inspector 上配置，也可通过 Cursors.GetCursorState 获取后在运行时动态调整 (例如指定从 AssetBundle 加载的贴图)。

类型[Serializable] public class CursorState
源码CursorManager.cs

成员​

成员说明
public string stateName状态名称 (运行时切换的依据)。
public RenderType renderType静态或动态游标类型，默认 Static。
public CursorMode cursorModeCursor 渲染模式 (Auto / ForceSoftware)，默认 Auto。
public bool scalingEnabled缩放开关，默认 false (缩放仅支持 ForceSoftware 渲染模式)。
public Vector2 scale缩放比例，默认 (1, 1) (需启用 scalingEnabled 才会生效)。
public Vector2 hotspot游标热点位置，默认 (0, 0)。
public Texture2D staticCursorTexture静态游标贴图。
public List<Texture2D> dynamicCursorTextures动态游标序列帧。
public bool isLoop动态游标是否循环播放，默认 false。
public PlayMode playMode动态游标播放模式，默认 Normal。
public int frameRate动态游标播放速率 (FPS)，字段默认 0 (需大于 0 动画才会播放)。

RenderType​

定义静态或动态游标类型。

public enum RenderType
{
    Static, // 静态游标
    Dynamic // 动态游标 (序列帧动画)
}

PlayMode​

定义动画的播放模式。

public enum PlayMode
{
    Normal,         // 顺放
    Reverse,        // 倒放
    PingPong,       // 顺放 -> 倒放
    PingPongReverse // 倒放 -> 顺放
}

注意 未开启 isLoop 时，Normal / Reverse 播放至最后一帧即停止；PingPong / PingPongReverse 则完成一次来回后停止。

方法总览​

方法说明
GetStateName获取状态名称。
SetStateName设置状态名称。
SetRenderType设置渲染类型 (静态/动态)。
SetCursorMode设置 Cursor 渲染模式。
SetCursorScale设置缩放比例。
SetCursorOffset设置游标热点位置。
SetStaticCursor设置静态游标贴图并立即应用渲染。
SetDynamicCursor替换动态游标序列帧并重置动画。
SetFrameRate设置播放速率。
SetLoop设置循环开关。
ResetRender按渲染类型重置渲染。
DriveUpdate驱动动态游标动画更新 (由 CursorManager 自动调用)。

GetStateName​

public string GetStateName()

获取状态名称。

SetStateName​

public void SetStateName(string stateName)

设置状态名称。

SetRenderType​

public void SetRenderType(RenderType renderType)

设置渲染类型 (RenderType 静态/动态)。

SetCursorMode​

public void SetCursorMode(CursorMode cursorMode)

设置 Cursor 渲染模式 (Auto / ForceSoftware)。

SetCursorScale​

public void SetCursorScale(Vector2 scale)

设置缩放比例 (需启用 scalingEnabled 且 ForceSoftware 模式才会生效)。

SetCursorOffset​

public void SetCursorOffset(Vector2 offset)

设置游标热点位置 (hotspot)。

SetStaticCursor​

public void SetStaticCursor(Texture2D t2d = null)

设置静态游标贴图并立即应用渲染；t2d 传入 null 时，直接以当前 staticCursorTexture 重新应用 (ForceSoftware 模式下若启用缩放，会应用缩放后的贴图)。

// 运行时动态指定贴图 (例如从 AssetBundle 加载)
var cursorState = Cursors.GetCursorState("Default");
cursorState.SetStaticCursor(tex);

SetDynamicCursor​

public void SetDynamicCursor(Texture2D[] t2ds)

替换动态游标序列帧并重置动画参数 (从头播放)。

// 运行时替换序列帧与参数调整
var cursorState = Cursors.GetCursorState("Loading");
cursorState.SetDynamicCursor(texture2ds);
cursorState.SetFrameRate(12);
cursorState.SetLoop(true);
cursorState.ResetRender();

注意 SetStaticCursor / SetDynamicCursor 不会变更 renderType；若要切换该状态的渲染类型，请调用 SetRenderType 后再 ResetRender。

SetFrameRate​

public void SetFrameRate(int frameRate)

设置动态游标播放速率 (FPS)。

SetLoop​

public void SetLoop(bool isLoop)

设置动态游标循环开关。

ResetRender​

public void ResetRender()

按渲染类型重置渲染 (Static 重新应用静态贴图；Dynamic 重置动画参数重新播放)。

DriveUpdate​

public void DriveUpdate(float dt)

驱动动态游标的序列帧动画更新，由 CursorManager 的 Update 自动调用 (一般无需自行调用)。