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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs: add Input guide (keyboard/mouse/touch/gamepad)
yhh75cdc59062b0
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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>