-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathinput.html
More file actions
385 lines (339 loc) · 16.8 KB
/
Copy pathinput.html
File metadata and controls
385 lines (339 loc) · 16.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>输入系统 - Ruin 语言文档</title>
<link rel="stylesheet" href="assets/style.css">
</head>
<body>
<div class="container">
<header>
<h1>🎮 Ruin 输入系统</h1>
<div class="version">v0.1.2 | Input System</div>
<div class="tagline">全局输入管理系统</div>
</header>
<nav>
<ul>
<li><a href="index.html">首页</a></li>
<li><a href="getting-started.html">快速开始</a></li>
<li><a href="syntax.html">语法</a></li>
<li><a href="types.html">类型系统</a></li>
<li><a href="function.html">函数系统</a></li>
<li><a href="builtin.html">内置模块</a></li>
<li><a href="string.html">String 模块</a></li>
<li><a href="object.html">Object 模块</a></li>
<li><a href="this.html">this 关键字</a></li>
<li><a href="fs.html">文件系统</a></li>
<li><a href="http.html">HTTP 模块</a></li>
<li><a href="json.html">JSON 处理</a></li>
<li><a href="system.html">System 模块</a></li>
<li><a href="gui.html">GUI系统</a></li>
<li><a href="window.html">窗口管理</a></li>
<li><a href="canvas.html">Canvas 绘图</a></li>
<li><a href="input.html" class="active">输入系统</a></li>
<li><a href="lifecycle.html">生命周期</a></li>
<li><a href="async.html">异步编程</a></li>
<li><a href="gpu.html">GPU计算</a></li>
<li><a href="cv.html">计算机视觉</a></li>
<li><a href="examples.html">示例</a></li>
</ul>
</nav>
<main>
<div class="breadcrumb">
<a href="index.html">首页</a> <span>></span> 输入系统
</div>
<section id="intro">
<h2>📖 概述</h2>
<p>
Ruin 的输入系统提供了全局 <code>input</code> 对象，
用于统一处理键盘、鼠标输入。系统支持动作映射、轴输入，让游戏输入处理变得简单优雅。
</p>
<div class="info-box">
<h4>💡 核心特点</h4>
<ul>
<li>全局单例 - 整个应用只有一个输入管理器</li>
<li>动作映射 - 将物理输入映射到逻辑动作</li>
<li>帧状态追踪 - 区分"刚按下"、"持续按下"、"刚释放"</li>
<li>轴输入 - 组合输入形成轴值（-1.0 到 1.0）</li>
<li>预配置动作 - 20+ 常用动作开箱即用</li>
</ul>
</div>
</section>
<section id="import">
<h2>📦 导入</h2>
<pre><code><span class="keyword">import</span> input <span class="keyword">from</span> <span class="string">"input"</span>;</code></pre>
</section>
<section id="api">
<h2>🔧 核心 API</h2>
<h3>1. 动作查询</h3>
<h4>isActionPressed(action: string): boolean</h4>
<p>检查动作是否持续按下（包括本帧）。</p>
<pre><code><span class="keyword">if</span> (input.isActionPressed(<span class="string">"move_left"</span>)) {
playerX = playerX - speed;
}</code></pre>
<h4>isActionJustPressed(action: string): boolean</h4>
<p>检查动作是否在<strong>本帧刚刚按下</strong>（上一帧未按下，本帧按下）。</p>
<pre><code><span class="keyword">if</span> (input.isActionJustPressed(<span class="string">"jump"</span>)) {
console.log(<span class="string">"Jump!"</span>);
player.velocityY = jumpForce;
}</code></pre>
<h4>isActionJustReleased(action: string): boolean</h4>
<p>检查动作是否在<strong>本帧刚刚释放</strong>（上一帧按下，本帧释放）。</p>
<pre><code><span class="keyword">if</span> (input.isActionJustReleased(<span class="string">"attack"</span>)) {
console.log(<span class="string">"Attack released!"</span>);
}</code></pre>
<h3>2. 轴输入</h3>
<h4>getAxis(negativeAction, positiveAction): number</h4>
<p>获取轴值（-1.0 到 1.0）。</p>
<pre><code><span class="comment">// 水平移动轴</span>
<span class="keyword">let</span> number horizontal = input.getAxis(<span class="string">"move_left"</span>, <span class="string">"move_right"</span>);
playerX = playerX + (horizontal * speed);
<span class="comment">// 垂直移动轴</span>
<span class="keyword">let</span> number vertical = input.getAxis(<span class="string">"move_up"</span>, <span class="string">"move_down"</span>);
playerY = playerY + (vertical * speed);</code></pre>
<h4>getVector(...): object</h4>
<p>获取 2D 向量，返回 <code>{x, y}</code> 对象，对角线移动会自动归一化。</p>
<pre><code><span class="keyword">let</span> vector move = input.getVector(
<span class="string">"move_left"</span>, <span class="string">"move_right"</span>,
<span class="string">"move_up"</span>, <span class="string">"move_down"</span>
);
playerX = playerX + (move.x * speed);
playerY = playerY + (move.y * speed);</code></pre>
<h3>3. 原始输入查询</h3>
<h4>键盘</h4>
<pre><code><span class="comment">// 检查键是否按下（使用键码）</span>
<span class="keyword">if</span> (input.isKeyPressed(input.KeyCode.W)) {
console.log(<span class="string">"W key is pressed"</span>);
}
<span class="comment">// 检查键是否刚按下</span>
<span class="keyword">if</span> (input.isKeyJustPressed(input.KeyCode.SPACE)) {
console.log(<span class="string">"Space just pressed"</span>);
}</code></pre>
<h4>鼠标</h4>
<pre><code><span class="comment">// 检查鼠标按钮</span>
<span class="keyword">if</span> (input.isMouseButtonPressed(input.MouseButton.LEFT)) {
console.log(<span class="string">"Left mouse button pressed"</span>);
}
<span class="comment">// 获取鼠标位置</span>
<span class="keyword">let</span> number mouseX = input.getMouseX();
<span class="keyword">let</span> number mouseY = input.getMouseY();</code></pre>
</section>
<section id="predefined-actions">
<h2>📋 预定义动作</h2>
<h3>UI 相关动作</h3>
<table>
<thead>
<tr>
<th>动作名</th>
<th>键盘映射</th>
<th>鼠标映射</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ui_accept</code></td>
<td>Enter, Space</td>
<td>鼠标左键</td>
<td>确认/接受</td>
</tr>
<tr>
<td><code>ui_cancel</code></td>
<td>ESC</td>
<td>-</td>
<td>取消</td>
</tr>
<tr>
<td><code>ui_touch</code></td>
<td>-</td>
<td>鼠标左键</td>
<td>触摸/点击</td>
</tr>
<tr>
<td><code>ui_select</code></td>
<td>Space</td>
<td>鼠标左键</td>
<td>选择</td>
</tr>
<tr>
<td><code>ui_left/right/up/down</code></td>
<td>方向键, WASD</td>
<td>-</td>
<td>UI导航</td>
</tr>
</tbody>
</table>
<h3>移动相关动作</h3>
<table>
<thead>
<tr>
<th>动作名</th>
<th>键盘映射</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>move_left/right/up/down</code></td>
<td>WASD, 方向键</td>
<td>移动</td>
</tr>
<tr>
<td><code>jump</code></td>
<td>Space</td>
<td>跳跃</td>
</tr>
<tr>
<td><code>sprint</code></td>
<td>Shift</td>
<td>奔跑</td>
</tr>
<tr>
<td><code>interact</code></td>
<td>E</td>
<td>交互</td>
</tr>
</tbody>
</table>
<h3>战斗相关动作</h3>
<table>
<thead>
<tr>
<th>动作名</th>
<th>鼠标映射</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>attack</code></td>
<td>鼠标左键</td>
<td>主要攻击</td>
</tr>
<tr>
<td><code>secondary_attack</code></td>
<td>鼠标右键</td>
<td>次要攻击/瞄准</td>
</tr>
</tbody>
</table>
</section>
<section id="examples">
<h2>📚 完整示例</h2>
<h3>示例 1：简单角色移动</h3>
<pre><code><span class="keyword">import</span> input <span class="keyword">from</span> <span class="string">"input"</span>;
<span class="keyword">import</span> gui <span class="keyword">from</span> <span class="string">"gui"</span>;
<span class="keyword">import</span> director <span class="keyword">from</span> <span class="string">"director"</span>;
<span class="keyword">let</span> sprite player = gui.createSprite({
width: <span class="number">50</span>,
height: <span class="number">50</span>,
backgroundColor: {r: <span class="number">0.2</span>, g: <span class="number">0.8</span>, b: <span class="number">0.2</span>, a: <span class="number">1.0</span>}
});
<span class="keyword">let</span> number playerX = <span class="number">400.0</span>;
<span class="keyword">let</span> number playerY = <span class="number">300.0</span>;
<span class="keyword">let</span> number speed = <span class="number">5.0</span>;
player.update = (number delta) => {
<span class="comment">// 使用轴输入 - 推荐方式</span>
<span class="keyword">let</span> number horizontal = input.getAxis(<span class="string">"move_left"</span>, <span class="string">"move_right"</span>);
<span class="keyword">let</span> number vertical = input.getAxis(<span class="string">"move_up"</span>, <span class="string">"move_down"</span>);
playerX = playerX + (horizontal * speed);
playerY = playerY + (vertical * speed);
player.x = playerX;
player.y = playerY;
};
director.getScene().canvas.addChild(player);</code></pre>
<h3>示例 2：带跳跃和攻击</h3>
<pre><code>player.update = (number delta) => {
<span class="comment">// 移动</span>
<span class="keyword">if</span> (input.isActionPressed(<span class="string">"move_left"</span>)) {
playerX = playerX - speed;
}
<span class="keyword">if</span> (input.isActionPressed(<span class="string">"move_right"</span>)) {
playerX = playerX + speed;
}
<span class="comment">// 跳跃（只在刚按下时触发）</span>
<span class="keyword">if</span> (input.isActionJustPressed(<span class="string">"jump"</span>)) {
console.log(<span class="string">"Jump!"</span>);
}
<span class="comment">// 攻击</span>
<span class="keyword">if</span> (input.isActionJustPressed(<span class="string">"attack"</span>)) {
console.log(<span class="string">"Attack!"</span>);
}
player.x = playerX;
player.y = playerY;
};</code></pre>
<h3>示例 3：鼠标交互</h3>
<pre><code>sprite.update = (number delta) => {
<span class="comment">// 获取鼠标位置</span>
<span class="keyword">let</span> number mouseX = input.getMouseX();
<span class="keyword">let</span> number mouseY = input.getMouseY();
<span class="comment">// 点击鼠标</span>
<span class="keyword">if</span> (input.isActionJustPressed(<span class="string">"ui_touch"</span>)) {
console.log(<span class="string">"Mouse clicked at: "</span> + mouseX + <span class="string">", "</span> + mouseY);
}
};</code></pre>
</section>
<section id="best-practices">
<h2>💡 最佳实践</h2>
<div class="success-box">
<h4>✅ 推荐做法</h4>
<ul>
<li>优先使用动作而非原始输入（便于重新映射）</li>
<li>连续动作（移动）使用 <code>isActionPressed</code></li>
<li>单次触发（跳跃）使用 <code>isActionJustPressed</code></li>
<li>使用轴输入简化移动代码</li>
</ul>
</div>
<div class="danger-box">
<h4>❌ 避免</h4>
<ul>
<li>不要在 update 外检测输入（不会工作）</li>
<li>不要混用 Pressed 和 JustPressed（逻辑混乱）</li>
<li>不要硬编码键码（使用动作映射）</li>
</ul>
</div>
</section>
<section id="keycodes">
<h2>⌨️ 键码常量</h2>
<p>使用 <code>input.KeyCode</code> 访问键码常量：</p>
<table>
<thead>
<tr>
<th>常量</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr><td><code>input.KeyCode.A-Z</code></td><td>字母键</td></tr>
<tr><td><code>input.KeyCode.SPACE</code></td><td>空格</td></tr>
<tr><td><code>input.KeyCode.ENTER</code></td><td>回车</td></tr>
<tr><td><code>input.KeyCode.ESCAPE</code></td><td>ESC</td></tr>
<tr><td><code>input.KeyCode.LEFT/RIGHT/UP/DOWN</code></td><td>方向键</td></tr>
<tr><td><code>input.MouseButton.LEFT/RIGHT/MIDDLE</code></td><td>鼠标按钮</td></tr>
</tbody>
</table>
</section>
<section id="related">
<h2>🔗 相关文档</h2>
<ul>
<li><a href="lifecycle.html">生命周期系统</a> - 在 update 中使用输入</li>
<li><a href="gui.html">GUI 系统</a> - 创建游戏界面</li>
<li><a href="examples.html">示例代码</a> - 更多实战示例</li>
</ul>
<div class="info-box">
<p>
完整的 API 参考请查看：
<a href="../INPUT-SYSTEM.md" target="_blank">docs/INPUT-SYSTEM.md</a>
</p>
</div>
</section>
</main>
<footer>
<p>© 2025 Ruin 语言项目 | <a href="https://github.com/naichabaobao/ruin">GitHub</a></p>
</footer>
</div>
<a href="#" class="back-to-top" id="backToTop">↑ 返回顶部</a>
<script src="assets/nav.js"></script>
</body>
</html>