Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: add Input guide (keyboard/mouse/touch/gamepad)

yhh75cdc59062b0
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 24c6fc948..f51558e33 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -48,6 +48,7 @@ export default defineConfig({
label: 'Guides',
translations: { 'zh-CN': '指南' },
items: [
+ { label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'guides/input' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
{ label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },
{ label: 'Tilemaps', translations: { 'zh-CN': '瓦片地图' }, slug: 'guides/tilemap' },
diff --git a/docs/astro/src/content/docs/guides/input.mdx b/docs/astro/src/content/docs/guides/input.mdx
new file mode 100644
index 000000000..5a5321cd9
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/input.mdx
@@ -0,0 +1,70 @@
+---
+title: Input
+description: Keyboard, mouse, touch, and gamepad via the Input resource.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Read input from a system through the `Input` resource. It tracks held state plus
+this-frame edges (pressed / released), so query it every frame.
+
+## Keyboard
+
+```typescript
+import { defineSystem, Res, Input } from 'esengine';
+
+const keys = defineSystem([Res(Input)], (input) => {
+ if (input.isKeyDown('KeyW')) { /* held down */ }
+ if (input.isKeyPressed('Space')) { /* pressed this frame */ }
+ if (input.isKeyReleased('Escape')) { /* released this frame */ }
+});
+```
+
+Keys use DOM code strings: `KeyW`, `KeyA`, `ArrowUp`, `Space`, `Escape`,
+`Digit1`, …
+
+## Mouse
+
+```typescript
+const mouse = defineSystem([Res(Input)], (input) => {
+ if (input.isMouseButtonPressed(0)) { /* left click this frame */ }
+ // buttons: 0 = left, 1 = middle, 2 = right
+ const screenX = input.mouseX, screenY = input.mouseY; // screen pixels
+ const wheel = input.scrollDeltaY;
+});
+```
+
+### Mouse in world space
+
+`input.mouseX` / `input.mouseY` are screen pixels. For world coordinates — to
+place or hit entities — read `UICameraInfo`, which exposes the cursor already
+projected into the world:
+
+```typescript
+import { defineSystem, Commands, Res, Input, UICameraInfo, Transform } from 'esengine';
+
+const spawnAtCursor = defineSystem(
+ [Res(Input), Res(UICameraInfo), Commands()],
+ (input, camera, cmds) => {
+ if (!camera.valid) return;
+ if (input.isMouseButtonPressed(0)) {
+ cmds.spawn().insert(Transform, {
+ position: { x: camera.worldMouseX, y: camera.worldMouseY, z: 0 },
+ });
+ }
+ }
+);
+```
+
+## Touch and gamepad
+
+- **Touch** — `input.isTouchActive(id)`, plus the `touches` map of active points.
+- **Gamepad** — `input.isGamepadConnected(pad)`,
+ `input.isGamepadButtonDown(button, pad)` (and `isGamepadButtonPressed` /
+ `Released`), with `GamepadAxis` for the sticks.
+
+<Aside type="tip">
+ `input.isPointerOverUI()` is `true` when the cursor is over a UI element —
+ check it before acting on a world click so clicks on buttons don't also hit the
+ game world.
+</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/input.mdx b/docs/astro/src/content/docs/zh-cn/guides/input.mdx
new file mode 100644
index 000000000..76e572c3a
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/input.mdx
@@ -0,0 +1,66 @@
+---
+title: 输入
+description: 通过 Input 资源读取键盘、鼠标、触摸与手柄。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+在系统里通过 `Input` 资源读取输入。它既跟踪按住状态,也跟踪当前帧的边沿(按下 /
+松开),所以每帧查询它。
+
+## 键盘
+
+```typescript
+import { defineSystem, Res, Input } from 'esengine';
+
+const keys = defineSystem([Res(Input)], (input) => {
+ if (input.isKeyDown('KeyW')) { /* 按住中 */ }
+ if (input.isKeyPressed('Space')) { /* 本帧按下 */ }
+ if (input.isKeyReleased('Escape')) { /* 本帧松开 */ }
+});
+```
+
+按键用 DOM code 字符串:`KeyW`、`KeyA`、`ArrowUp`、`Space`、`Escape`、`Digit1`……
+
+## 鼠标
+
+```typescript
+const mouse = defineSystem([Res(Input)], (input) => {
+ if (input.isMouseButtonPressed(0)) { /* 本帧左键点击 */ }
+ // 按键:0 = 左键,1 = 中键,2 = 右键
+ const screenX = input.mouseX, screenY = input.mouseY; // 屏幕像素
+ const wheel = input.scrollDeltaY;
+});
+```
+
+### 世界坐标下的鼠标
+
+`input.mouseX` / `input.mouseY` 是屏幕像素。要拿世界坐标——用于放置或命中实体——请读
+`UICameraInfo`,它已把光标投影到世界空间:
+
+```typescript
+import { defineSystem, Commands, Res, Input, UICameraInfo, Transform } from 'esengine';
+
+const spawnAtCursor = defineSystem(
+ [Res(Input), Res(UICameraInfo), Commands()],
+ (input, camera, cmds) => {
+ if (!camera.valid) return;
+ if (input.isMouseButtonPressed(0)) {
+ cmds.spawn().insert(Transform, {
+ position: { x: camera.worldMouseX, y: camera.worldMouseY, z: 0 },
+ });
+ }
+ }
+);
+```
+
+## 触摸与手柄
+
+- **触摸** —— `input.isTouchActive(id)`,以及记录活动触点的 `touches` map。
+- **手柄** —— `input.isGamepadConnected(pad)`、`input.isGamepadButtonDown(button, pad)`
+ (还有 `isGamepadButtonPressed` / `Released`),摇杆用 `GamepadAxis`。
+
+<Aside type="tip">
+ 当光标位于某个 UI 元素之上时,`input.isPointerOverUI()` 为 `true` —— 在处理世界点击
+ 前先检查它,这样点在按钮上的点击就不会同时命中游戏世界。
+</Aside>