星火 2.0 开发文档

主题

GameGraph.InputSystem ​

CursorShape 仅客户端 ​

命名空间 GameGraph.InputSystem

csharp
public enum CursorShape

标准鼠标光标形状。

枚举值 ​

  • Normal
  • IBeam
  • Cross
  • ResizeVertical
  • ResizeDiagonalTopRight
  • ResizeHorizontal
  • ResizeDiagonalTopLeft
  • ResizeAll
  • AcceptDrop
  • RejectDrop
  • Busy
  • BusyArrow

GameCursor 仅客户端 ​

命名空间 GameGraph.InputSystem

csharp
public static class GameCursor

客户端鼠标光标控制。

属性 ​

Visible 仅客户端 ​

csharp
public static bool Visible { get; set; }

获取或设置系统鼠标是否可见。

UseSystemShapes 仅客户端 ​

csharp
public static bool UseSystemShapes { get; set; }

获取或设置是否使用系统默认光标形状。

Shape 仅客户端 ​

csharp
public static CursorShape Shape { get; set; }

当前标准光标形状。

ShapeName 仅客户端 ​

csharp
public static string ShapeName { get; }

当前光标形状名。

方法 ​

SetShape 仅客户端 ​

csharp
public static void SetShape(CursorShape shape)

设置标准光标形状。

SetShape 仅客户端 ​

csharp
public static bool SetShape(string shapeName)

按名称设置光标形状，可用于标准形状名或已定义的自定义形状名。

DefineShape 仅客户端 ​

csharp
public static bool DefineShape(string shapeName, string imagePath, int left = 0, int top = 0, int right = 0, int bottom = 0, int hotSpotX = 0, int hotSpotY = 0)

定义一个图片光标形状。

SetImageShape 仅客户端 ​

csharp
public static bool SetImageShape(string shapeName, string imagePath, int left = 0, int top = 0, int right = 0, int bottom = 0, int hotSpotX = 0, int hotSpotY = 0)

定义并立即使用一个图片光标形状。

HideTemporarily 仅客户端 ​

csharp
public static IDisposable HideTemporarily()

临时隐藏鼠标，并在释放返回对象时恢复原可见状态。

SetVisibleTemporarily 仅客户端 ​

csharp
public static IDisposable SetVisibleTemporarily(bool visible)

临时设置鼠标可见性，并在释放返回对象时恢复原可见状态。

GamePointerCapture 仅客户端 ​

命名空间 GameGraph.InputSystem

csharp
public static class GamePointerCapture

为当前客户端游戏视口提供鼠标捕获和相对移动事件。

备注

需要客户端能力版本 5。调用主动 API 前，请在游戏初始化时通过 ClientRuntimeFeature) 检查 RelativeMouseCapture。 框架在旧客户端初始化时跳过内部事件注册；新 API 不会自动回退为绝对光标输入。 打开背包或菜单时调用 ReleaseCapture，关闭后调用 RequestCapture。

属性 ​

State 仅客户端 ​

csharp
public static PointerCaptureState State { get; }

获取当前游戏的实际捕获状态。

方法 ​

RequestCapture 仅客户端 ​

csharp
public static bool RequestCapture()

请求捕获鼠标；接受请求后等待用户下一次在当前游戏视口内按下左键。

返回： 请求是否被当前宿主接受。返回 true 不表示鼠标已立即捕获；请读取 State。

备注

用于开始捕获的点击由宿主消费，不应同时触发攻击或普通界面点击。 Esc 或失焦会释放实际捕获并保留等待点击状态，恢复焦点不会自动重新捕获。 捕获期间系统光标隐藏；释放时由宿主恢复进入捕获前的光标状态。

ReleaseCapture 仅客户端 ​

csharp
public static void ReleaseCapture()

释放当前游戏持有的鼠标捕获，并取消等待点击；重复调用无副作用。

事件 ​

RelativeMoved 仅客户端 ​

csharp
public static event Action<Vector2>? RelativeMoved

捕获生效时收到鼠标相对移动量；X 向右为正，Y 向下为正。

备注

参数是本次派发累计的视口输入位移，不是绝对位置或速度，不应再次乘以帧时间。 使用宿主的视口输入坐标单位，不承诺原始硬件计数；宿主可能应用系统指针加速或缩放。 未捕获时不触发；事件仅在本客户端派发，不会自动同步到服务端。

StateChanged 仅客户端 ​

csharp
public static event Action<PointerCaptureState, PointerCaptureChangeReason>? StateChanged

当前游戏的捕获状态变化时触发，参数分别为新状态和变化原因。

备注

通知在帧末派发。游戏结束后不保证再收到 GameEnded 通知，请在 Game.OnGameEnd 或控制器销毁路径清理订阅。

PointerCaptureChangeReason 仅客户端 ​

命名空间 GameGraph.InputSystem

csharp
public enum PointerCaptureChangeReason

鼠标捕获状态变化的原因。

枚举值 ​

  • Requested — 游戏请求捕获，开始等待用户点击。
  • Captured — 用户点击当前游戏视口，捕获生效。
  • ExplicitRelease — 游戏主动释放捕获，并取消等待点击。
  • Escape — 用户按下 Esc，释放捕获并等待重新点击。
  • FocusLost — 窗口失去焦点，释放捕获并等待重新点击。
  • HostUnavailable — 游戏视口或宿主当前不可用。
  • GameEnded — 游戏结束，捕获请求已取消。
  • CaptureFailed — 底层窗口系统未能捕获鼠标。

PointerCaptureState 仅客户端 ​

命名空间 GameGraph.InputSystem

csharp
public enum PointerCaptureState

当前游戏视口的鼠标捕获状态。

枚举值 ​

  • Released — 未请求捕获，鼠标可用于普通界面交互。
  • WaitingForClick — 等待用户在当前游戏视口内按下鼠标左键。
  • Captured — 正在捕获鼠标，并向当前游戏发送相对移动量。