跳到主要内容

模块介绍

重要 注意 提醒

Coding Style wiki​

基本说明​

Cursor 游标管理器，支持静态与动态游标与各种状态行为切换 (例如经营模拟类的游戏，需要有各种游标状态等...)。

  • 版本：v1.0.1 (com.michaelo.oxgkit.cursorsystem)
  • 命名空间：OxGKit.CursorSystem

应用说明​

CursorManager 配置界面​

  • 通过 Package Manager -> Samples 导入 CursorManager Prefab，再拖拽至启动场景上 (也可以不放置 Prefab，首次调用 Cursors API 时，会自动查找或创建 [CursorManager] 节点)，CursorManager 会自动整理至 OxGKit 容器节点下并 DontDestroyOnLoad 常驻。
  • 在 Inspector 上编辑 Cursor States 列表，每条 CursorState 可配置以下：
    • stateName：状态名称 (运行时切换的依据)。
    • renderType：Static (静态游标) 或 Dynamic (动态游标序列帧)。
    • cursorMode：Cursor 渲染模式 (Auto 或 ForceSoftware)。
    • scalingEnabled、scale：缩放开关与缩放比例。
    • hotspot：游标热点位置。
    • staticCursorTexture：静态游标贴图。
    • dynamicCursorTextures、isLoop、playMode、frameRate：动态游标序列帧、是否循环、播放模式、播放速率。

注意 Cursor States 列表中的第一条状态即为默认状态 (Default)，ResetCursorState 会重置回第一条状态。

播放模式 (PlayMode)​

动态游标支持以下播放模式：

  • Normal (顺放)
  • Reverse (倒放)
  • PingPong (顺放 -> 倒放)
  • PingPongReverse (倒放 -> 顺放)

重要 动态游标需设置 frameRate 大于 0 才会播放动画；缩放功能需启用 scalingEnabled 并将 cursorMode 设为 ForceSoftware 才会生效。

提醒 游标贴图建议将 Texture Type 设为 Cursor，确保渲染清晰；WebGL 平台浏览器对自定义游标有尺寸限制，建议使用小尺寸贴图。

简单使用​

切换游标状态​

using OxGKit.CursorSystem;

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

// 按名称切换游标状态 (返回 bool 表示是否切换成功)
Cursors.SetCursorState("Loading");

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

显示与锁定控制​

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

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

运行时动态指定贴图​

// 按需自行加载 Texture2D (例如 Resources 或 AssetBundle)
Texture2D tex = Resources.Load<Texture2D>("Cursors/cursor_default");

// 获取指定状态，运行时动态替换游标贴图
var cursorState = Cursors.GetCursorState("Default");
cursorState.SetStaticCursor(tex);

// 动态游标序列帧替换与参数调整
Texture2D[] texture2ds = Resources.LoadAll<Texture2D>("Cursors/Loading");
cursorState.SetDynamicCursor(texture2ds);
cursorState.SetFrameRate(12);
cursorState.SetLoop(true);
cursorState.ResetRender();

[参考 Example]

Installation​

Install via git URL
Add https://github.com/michael811125/OxGKit.git?path=Assets/OxGKit/CursorSystem/Scripts to Package Manager

无第三方依赖

Samples (Package Manager -> Samples)

  • AI Agent Skills (参考 AI Agent Skills)
  • CursorManager Prefab
  • CursorManager Demo

模块 API​

Demo​

CursorSystem Demo