60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# 窗口模块
|
|
|
|
**脚本入口：** `eve.Window()`
|
|
|
|
创建和配置单一游戏窗口。
|
|
|
|
## 基本用法
|
|
|
|
```squirrel
|
|
local window = eve.Window();
|
|
print(window.getWidth() + "x" + window.getHeight() + "\n");
|
|
```
|
|
|
|
## 对象关系与调用时机
|
|
|
|
`WindowSettings` 只是创建参数；`Window` 持有平台窗口；`Graphics` 必须先通过 `setGraphics()` 关联。窗口初始化放在引擎启动阶段，游戏逻辑通常直接使用全局 `win`，只在设置菜单中调用尺寸变更。
|
|
|
|
## 目标导向指南
|
|
|
|
### 按配置创建窗口
|
|
|
|
1. 在 `config.nut` 保存宽、高和标题等游戏配置。
|
|
2. 创建 `eve.WindowSettings()`，填写 `width`、`height`、`centered`。
|
|
3. 调用 `win.setGraphics(gfx)` 后再调用 `win.setWindowSettings(settings)`。
|
|
4. 用 `getWidth()` / `getHeight()` 回读真实尺寸；移动端可能不会采用请求尺寸。
|
|
|
|
### 在选项菜单切换分辨率
|
|
|
|
调用 `setSize(width, height)`，成功后重新读取窗口尺寸，并同步摄像机 viewport 与 UI 布局。退出按钮应调用 `close()`，不要直接终止进程。
|
|
|
|
### 适配高 DPI 编辑器布局
|
|
|
|
`getWidth()` / `getHeight()` 返回窗口的逻辑尺寸，适合游戏摄像机和普通 UI 坐标；
|
|
`getPixelWidth()` / `getPixelHeight()` 返回交换链使用的实际像素尺寸，适合截图、
|
|
离屏目标和像素级渲染。`getDPIScale()` 返回实际像素宽度与逻辑宽度的比例。
|
|
编辑器应只选择一种坐标空间完成布局，不要同时使用像素尺寸并再次乘以 DPI 比例。
|
|
|
|
## 常见问题
|
|
|
|
- `setWindowSettings()` 失败：通常是 Graphics 尚未关联，或平台不支持请求的模式。
|
|
- 移动端尺寸不同：必须信任 `getWidth/Height()` 的回读值。
|
|
- 调整窗口后画面拉伸：同步更新 camera viewport、Canvas 和 UI 布局。
|
|
|
|
## API 快查
|
|
|
|
下列方法名来自当前 Squirrel 绑定；同一模块创建的辅助对象（例如 `World`、`Body`、`Source`）的方法也列在这里。
|
|
|
|
- `close()`、`getDPIScale()`、`getHeight()`、`getName()`、`getPixelHeight()`、`getPixelWidth()`、`getWidth()`、`getWindowSettings()`、`hasFocus()`、`setGraphics()`、`setSize()`、`setWindowSettings()`
|
|
|
|
## 使用要点
|
|
|
|
- 模块对象和它创建的资源对象应保存在全局或实体状态中，不要在每帧重复创建。
|
|
- 带 `update(dt)` 的系统应在 `eve_update` 调用；绘制方法应在 `eve_render` 调用。
|
|
- 参数约束、默认值和返回类型以对应模块头文件及 `addFunc` 绑定为准；本文 API 快查与当前源码同步生成。
|
|
|
|
**源码：** [`src/modules/window/`](../../../src/modules/window/)
|
|
**相关测试：** 在 [`test/`](../../../test/) 中搜索 `window`。
|
|
|
|
`hasFocus()` 在窗口线程返回当前窗口是否拥有输入焦点，可用于限制边缘滚动等后台不应响应的输入。
|