65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
# 鼠标模块
|
|
|
|
**脚本入口：** `eve.Mouse()`
|
|
|
|
查询鼠标位置、按键、相对模式与可见性。
|
|
|
|
## 基本用法
|
|
|
|
```squirrel
|
|
local mx = mouse.getX();
|
|
local my = mouse.getY();
|
|
if (mouse.isDown(1)) fireAt(mx, my);
|
|
```
|
|
|
|
## 对象关系与调用时机
|
|
|
|
`Mouse` 脚本绑定提供坐标、按键、可见性、抓取与相对模式。坐标位于窗口空间；世界命中测试需要用当前相机反变换。
|
|
|
|
## 目标导向指南
|
|
|
|
### 点击屏幕坐标中的对象
|
|
|
|
在更新阶段用 `getX()` / `getY()` 取得坐标，用 `isDown(button)` 判断按键；若摄像机有缩放或平移，先将窗口坐标反变换到世界坐标再做命中测试。
|
|
|
|
### 显示或隐藏游戏光标
|
|
|
|
用 `setVisible(bool)` / `isVisible()` 控制并查询光标可见性。
|
|
|
|
### 第一人称视角（相对模式）
|
|
|
|
```squirrel
|
|
mouse.setRelativeMode(true); // 光标锁定并隐藏，只报告相对移动
|
|
mouse.setRelativeMode(false); // 恢复绝对坐标
|
|
```
|
|
|
|
相对模式下不要用 `setPosition` 回中再对 `getX()` 求差：Windows 上 warp 会注入反向位移，视角会先转再弹回。
|
|
每帧在 `eve_update` 里先调 `getMovementX()` 再调 `getMovementY()`（前者从 SDL 取相对位移并锁存 Y）。
|
|
`setGrabbed(bool)` / `isGrabbed()` 控制窗口鼠标抓取（平台行为差异见 `mouse/sdl/Mouse.cpp`）。
|
|
|
|
## 常见问题
|
|
|
|
- 把按钮编号与键盘名混用：鼠标按钮使用整数编号。
|
|
- UI 已捕获鼠标仍触发游戏点击：先检查 `ui.wantCaptureMouse()`。
|
|
- 相对模式请求失败：SDL 在无聚焦窗口等情况下可能拒绝，`setRelativeMode()` 返回 `false`，调用方应检查返回值。
|
|
|
|
## API 快查
|
|
|
|
下列方法名来自当前 Squirrel 绑定；同一模块创建的辅助对象（例如 `World`、`Body`、`Source`）的方法也列在这里。
|
|
|
|
- `getName()`、`getX()`、`getY()`、`getMovementX()`、`getMovementY()`、`setX()`、`setY()`、`setPosition()`、`isDown()`、
|
|
`setVisible()`、`isVisible()`、`setGrabbed()`、`isGrabbed()`、`setRelativeMode()`、`getRelativeMode()`
|
|
|
|
## 使用要点
|
|
|
|
- 模块对象和它创建的资源对象应保存在全局或实体状态中，不要在每帧重复创建。
|
|
- 带 `update(dt)` 的系统应在 `eve_update` 调用；绘制方法应在 `eve_render` 调用。
|
|
- 参数约束、默认值和返回类型以对应模块头文件及 `addFunc` 绑定为准；本文 API 快查与当前源码同步生成。
|
|
|
|
**源码：** [`src/modules/mouse/`](../../../src/modules/mouse/)
|
|
**相关测试：** 在 [`test/`](../../../test/) 中搜索 `mouse`。
|
|
|
|
### 滚轮快照
|
|
|
|
`getWheelX()` / `getWheelY()` 返回最近一次完成的事件泵累计滚轮增量（浮点返回值，已统一 flipped 方向；SDL 2.0.18 及以上保留精细滚动，旧版只有整数滚轮事件）。同帧多次读取不消费输入；下一次无滚轮事件的泵完成后归零。仅在事件线程的更新阶段读取，UI 捕获的事件不进入游戏输入快照。
|