melonjs 20.12.0 → 20.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/README.md +66 -22
  2. package/build/application/application.d.ts +6 -1
  3. package/build/application/application.d.ts.map +1 -1
  4. package/build/application/header.d.ts.map +1 -1
  5. package/build/application/resize.d.ts.map +1 -1
  6. package/build/application/settings.d.ts +13 -8
  7. package/build/application/settings.d.ts.map +1 -1
  8. package/build/audio/audio.d.ts +8 -4
  9. package/build/audio/audio.d.ts.map +1 -1
  10. package/build/audio/backend/engine.d.ts.map +1 -1
  11. package/build/audio/playback.d.ts +2 -2
  12. package/build/audio/playback.d.ts.map +1 -1
  13. package/build/audio/spatial.d.ts.map +1 -1
  14. package/build/audio/types.d.ts +15 -5
  15. package/build/audio/types.d.ts.map +1 -1
  16. package/build/camera/camera2d.d.ts +12 -9
  17. package/build/camera/camera2d.d.ts.map +1 -1
  18. package/build/camera/camera3d.d.ts +11 -8
  19. package/build/camera/camera3d.d.ts.map +1 -1
  20. package/build/camera/effects/fade_effect.d.ts.map +1 -1
  21. package/build/geometries/ellipse.d.ts +3 -0
  22. package/build/geometries/ellipse.d.ts.map +1 -1
  23. package/build/geometries/line.d.ts.map +1 -1
  24. package/build/geometries/path2d.d.ts +9 -8
  25. package/build/geometries/path2d.d.ts.map +1 -1
  26. package/build/geometries/polygon.d.ts +2 -1
  27. package/build/geometries/polygon.d.ts.map +1 -1
  28. package/build/index.d.ts +14 -3
  29. package/build/index.d.ts.map +1 -1
  30. package/build/index.js +50215 -45051
  31. package/build/index.js.map +4 -4
  32. package/build/input/gamepad.d.ts.map +1 -1
  33. package/build/input/keyboard.d.ts.map +1 -1
  34. package/build/input/pointerevent.d.ts.map +1 -1
  35. package/build/level/gltf/GLTFModel.d.ts.map +1 -1
  36. package/build/level/level.d.ts.map +1 -1
  37. package/build/level/tiled/TMXLayer.d.ts +50 -15
  38. package/build/level/tiled/TMXLayer.d.ts.map +1 -1
  39. package/build/level/tiled/TMXTileMap.d.ts +14 -4
  40. package/build/level/tiled/TMXTileMap.d.ts.map +1 -1
  41. package/build/level/tiled/TMXTileset.d.ts.map +1 -1
  42. package/build/level/tiled/TMXUtils.d.ts.map +1 -1
  43. package/build/level/tiled/renderer/TMXHexagonalRenderer.d.ts.map +1 -1
  44. package/build/level/tiled/renderer/TMXIsometricRenderer.d.ts.map +1 -1
  45. package/build/level/tiled/renderer/TMXObliqueRenderer.d.ts +1 -0
  46. package/build/level/tiled/renderer/TMXObliqueRenderer.d.ts.map +1 -1
  47. package/build/level/tiled/renderer/TMXOrthogonalRenderer.d.ts.map +1 -1
  48. package/build/level/tiled/renderer/TMXRenderer.d.ts +7 -3
  49. package/build/level/tiled/renderer/TMXRenderer.d.ts.map +1 -1
  50. package/build/level/tiled/renderer/TMXStaggeredRenderer.d.ts.map +1 -1
  51. package/build/lighting/light3d.d.ts +55 -0
  52. package/build/lighting/light3d.d.ts.map +1 -1
  53. package/build/loader/cache.d.ts +146 -97
  54. package/build/loader/cache.d.ts.map +1 -1
  55. package/build/loader/internal-types.d.ts +69 -0
  56. package/build/loader/internal-types.d.ts.map +1 -0
  57. package/build/loader/loader.d.ts +589 -253
  58. package/build/loader/loader.d.ts.map +1 -1
  59. package/build/loader/parsers/audio.d.ts.map +1 -1
  60. package/build/loader/parsers/fontface.d.ts.map +1 -1
  61. package/build/loader/parsers/gltf.d.ts.map +1 -1
  62. package/build/loader/parsers/tmx.d.ts.map +1 -1
  63. package/build/math/color.d.ts +4 -0
  64. package/build/math/color.d.ts.map +1 -1
  65. package/build/math/math.d.ts +6 -1
  66. package/build/math/math.d.ts.map +1 -1
  67. package/build/math/noise.d.ts +16 -16
  68. package/build/math/noise.d.ts.map +1 -1
  69. package/build/math/observableVector2d.d.ts +6 -6
  70. package/build/math/observableVector2d.d.ts.map +1 -1
  71. package/build/math/observableVector3d.d.ts +8 -8
  72. package/build/math/observableVector3d.d.ts.map +1 -1
  73. package/build/particles/emitter.d.ts +15 -3
  74. package/build/particles/emitter.d.ts.map +1 -1
  75. package/build/particles/particle.d.ts +6 -0
  76. package/build/particles/particle.d.ts.map +1 -1
  77. package/build/particles/settings.d.ts +22 -5
  78. package/build/particles/settings.d.ts.map +1 -1
  79. package/build/physics/adapter.d.ts +64 -25
  80. package/build/physics/adapter.d.ts.map +1 -1
  81. package/build/physics/builtin/body.d.ts +23 -4
  82. package/build/physics/builtin/body.d.ts.map +1 -1
  83. package/build/physics/builtin/builtin-adapter.d.ts +25 -3
  84. package/build/physics/builtin/builtin-adapter.d.ts.map +1 -1
  85. package/build/physics/builtin/detector.d.ts.map +1 -1
  86. package/build/physics/builtin/raycast.d.ts.map +1 -1
  87. package/build/physics/world.d.ts +40 -10
  88. package/build/physics/world.d.ts.map +1 -1
  89. package/build/renderable/container.d.ts +41 -6
  90. package/build/renderable/container.d.ts.map +1 -1
  91. package/build/renderable/draggable.d.ts.map +1 -1
  92. package/build/renderable/frameAnimation.d.ts.map +1 -1
  93. package/build/renderable/instanced_mesh.d.ts +16 -14
  94. package/build/renderable/instanced_mesh.d.ts.map +1 -1
  95. package/build/renderable/mesh.d.ts +62 -5
  96. package/build/renderable/mesh.d.ts.map +1 -1
  97. package/build/renderable/renderable.d.ts.map +1 -1
  98. package/build/renderable/sprite.d.ts +4 -2
  99. package/build/renderable/sprite.d.ts.map +1 -1
  100. package/build/renderable/text/bitmaptext.d.ts +12 -3
  101. package/build/renderable/text/bitmaptext.d.ts.map +1 -1
  102. package/build/renderable/text/text.d.ts +147 -4
  103. package/build/renderable/text/text.d.ts.map +1 -1
  104. package/build/renderable/text/textmetrics.d.ts +10 -2
  105. package/build/renderable/text/textmetrics.d.ts.map +1 -1
  106. package/build/renderable/text/textstyle.d.ts.map +1 -1
  107. package/build/renderable/trigger.d.ts +5 -0
  108. package/build/renderable/trigger.d.ts.map +1 -1
  109. package/build/renderable/ui/panelpaint.d.ts +5 -1
  110. package/build/renderable/ui/panelpaint.d.ts.map +1 -1
  111. package/build/renderable/ui/progressbar.d.ts +267 -95
  112. package/build/renderable/ui/progressbar.d.ts.map +1 -1
  113. package/build/renderable/ui/uibaseelement.d.ts +443 -50
  114. package/build/renderable/ui/uibaseelement.d.ts.map +1 -1
  115. package/build/renderable/ui/uicheckbox.d.ts +383 -0
  116. package/build/renderable/ui/uicheckbox.d.ts.map +1 -0
  117. package/build/renderable/ui/uifocus.d.ts +6 -0
  118. package/build/renderable/ui/uifocus.d.ts.map +1 -0
  119. package/build/renderable/ui/uilabel.d.ts +31 -0
  120. package/build/renderable/ui/uilabel.d.ts.map +1 -0
  121. package/build/renderable/ui/uipanel.d.ts +589 -116
  122. package/build/renderable/ui/uipanel.d.ts.map +1 -1
  123. package/build/renderable/ui/uiskin.d.ts +25 -0
  124. package/build/renderable/ui/uiskin.d.ts.map +1 -0
  125. package/build/renderable/ui/uislider.d.ts +518 -0
  126. package/build/renderable/ui/uislider.d.ts.map +1 -0
  127. package/build/renderable/ui/uispriteelement.d.ts +161 -85
  128. package/build/renderable/ui/uispriteelement.d.ts.map +1 -1
  129. package/build/renderable/ui/uitextbutton.d.ts +369 -63
  130. package/build/renderable/ui/uitextbutton.d.ts.map +1 -1
  131. package/build/state/stage.d.ts.map +1 -1
  132. package/build/system/device.d.ts +11 -2
  133. package/build/system/device.d.ts.map +1 -1
  134. package/build/system/fullscreen.d.ts.map +1 -1
  135. package/build/system/pool.d.ts.map +1 -1
  136. package/build/system/save.d.ts +2 -1
  137. package/build/system/save.d.ts.map +1 -1
  138. package/build/tweens/tween.d.ts +5 -2
  139. package/build/tweens/tween.d.ts.map +1 -1
  140. package/build/utils/fetchdata.d.ts.map +1 -1
  141. package/build/utils/utils.d.ts.map +1 -1
  142. package/build/video/canvas/canvas_renderer.d.ts +16 -19
  143. package/build/video/canvas/canvas_renderer.d.ts.map +1 -1
  144. package/build/video/canvas_factory.d.ts.map +1 -1
  145. package/build/video/effects/shadereffect.d.ts +127 -0
  146. package/build/video/effects/shadereffect.d.ts.map +1 -1
  147. package/build/video/renderer.d.ts +20 -4
  148. package/build/video/renderer.d.ts.map +1 -1
  149. package/build/video/renderstate.d.ts +26 -3
  150. package/build/video/renderstate.d.ts.map +1 -1
  151. package/build/video/utils/tessellation.d.ts +11 -0
  152. package/build/video/utils/tessellation.d.ts.map +1 -1
  153. package/build/video/webgl/batchers/lit_mesh_batcher.d.ts.map +1 -1
  154. package/build/video/webgl/webgl_renderer.d.ts +3 -6
  155. package/build/video/webgl/webgl_renderer.d.ts.map +1 -1
  156. package/build/video/webgpu/batchers/lit_mesh_batcher.d.ts.map +1 -1
  157. package/build/video/webgpu/batchers/primitive_batcher.d.ts.map +1 -1
  158. package/build/video/webgpu/webgpu_renderer.d.ts +3 -6
  159. package/build/video/webgpu/webgpu_renderer.d.ts.map +1 -1
  160. package/package.json +1 -1
  161. package/skills/melonjs/SKILL.md +41 -17
  162. package/skills/melonjs-20-migration/SKILL.md +50 -7
  163. package/skills/melonjs-3d/SKILL.md +138 -38
  164. package/skills/melonjs-3d-assets/SKILL.md +83 -33
  165. package/skills/melonjs-audio/SKILL.md +62 -19
  166. package/skills/melonjs-camera-and-drawing/SKILL.md +135 -8
  167. package/skills/melonjs-deployment/SKILL.md +92 -14
  168. package/skills/melonjs-display-and-scaling/SKILL.md +8 -3
  169. package/skills/melonjs-effects-and-shaders/SKILL.md +47 -15
  170. package/skills/melonjs-events/SKILL.md +6 -3
  171. package/skills/melonjs-getting-started/SKILL.md +6 -2
  172. package/skills/melonjs-input/SKILL.md +102 -16
  173. package/skills/melonjs-lighting/SKILL.md +13 -1
  174. package/skills/melonjs-loading-assets/SKILL.md +255 -39
  175. package/skills/melonjs-math/SKILL.md +26 -8
  176. package/skills/melonjs-particles-and-trails/SKILL.md +77 -9
  177. package/skills/melonjs-performance/SKILL.md +18 -8
  178. package/skills/melonjs-physics/SKILL.md +435 -128
  179. package/skills/melonjs-plugins/SKILL.md +50 -11
  180. package/skills/melonjs-renderables/SKILL.md +31 -7
  181. package/skills/melonjs-renderer-backends/SKILL.md +38 -17
  182. package/skills/melonjs-scenes-and-state/SKILL.md +45 -5
  183. package/skills/melonjs-sprites-and-animation/SKILL.md +37 -2
  184. package/skills/melonjs-tilemaps/SKILL.md +149 -17
  185. package/skills/melonjs-ui-and-text/SKILL.md +674 -42
@@ -1,20 +1,166 @@
1
1
  import type Pointer from "./../../input/pointer.ts";
2
2
  import type { Vector2d } from "../../math/vector2d.ts";
3
+ import type Renderer from "../../video/renderer.js";
3
4
  import Container from "../container.js";
5
+ import type { UINavAction } from "./uifocus.ts";
4
6
  /**
5
- * This is a basic clickable and draggable container which you can use in your game UI.
6
- * Use this for example if you want to display a panel that contains text, images or other UI elements.
7
+ * The bounce settings every built-in widget takes in its settings object:
8
+ * a small grow under the pointer and a squash while held. Only the drawing
9
+ * scales; the hit area and the layout stay as they are. See
10
+ * {@link UIBaseElement#hoverScale}.
11
+ * @category UI
12
+ * @example
13
+ * // a button that grows 5% under the pointer and squashes while held
14
+ * const play = new UITextButton(100, 200, {
15
+ * text: "Play",
16
+ * hoverScale: 1.05,
17
+ * pressScale: 0.92,
18
+ * });
19
+ */
20
+ export interface UIJuiceSettings {
21
+ /**
22
+ * The scale the widget is drawn at under the pointer, or while it has
23
+ * the keyboard and gamepad focus, such as `1.05`. `1` turns it off.
24
+ * @default 1
25
+ */
26
+ hoverScale?: number;
27
+ /**
28
+ * The scale the widget is drawn at while held down, such as `0.92`.
29
+ * `1` turns it off.
30
+ * @default 1
31
+ */
32
+ pressScale?: number;
33
+ }
34
+ /**
35
+ * A clickable, draggable container: the base every UI widget builds on
36
+ * ({@link UITextButton}, {@link UICheckbox}, {@link UISlider},
37
+ * {@link UIPanel}, {@link UISpriteElement}). Extend it to make a widget of your own; it can hold
38
+ * other renderables as children.
39
+ *
40
+ * It uses screen coordinates (`floating` is `true`), so it stays put when
41
+ * the camera moves. Children added to it should keep `floating` at `false`.
42
+ *
43
+ * ## Pointer callbacks
44
+ * Override these in a subclass:
45
+ * - {@link UIBaseElement#onClick}: the pointer went DOWN on the element
46
+ * (or Enter / A with the focus here). It is a press, not a completed click.
47
+ * - {@link UIBaseElement#onRelease}: the press ended: the pointer came up,
48
+ * left the element while held, or the browser cancelled it.
49
+ * - {@link UIBaseElement#onOver} / {@link UIBaseElement#onOut}: the pointer
50
+ * came in / went out. `hover` is `true` in between. An element removed
51
+ * while hovered gets its `onOut` too.
52
+ * - {@link UIBaseElement#onHold}: held for `holdThreshold` ms, when
53
+ * `isHoldable` is set.
54
+ * - {@link UIBaseElement#onCancel}: the press was called off without a
55
+ * release (see {@link UIBaseElement#cancelPress}), as when the element is
56
+ * removed while held.
7
57
  *
8
- * Regions under the pointer are asked in the order they are drawn, topmost
9
- * first, and the walk carries on downwards until a handler returns `false`. An
10
- * element that can overlap another one is therefore not opaque until it says
11
- * so: by default a widget it covers still answers clicks and still lights up on
12
- * hover. {@link UIBaseElement#onClick}, {@link UIBaseElement#onRelease} and
13
- * {@link UIBaseElement#onOver} each consume by returning `false`.
58
+ * Elements under the pointer are asked topmost first, and the event carries
59
+ * on to the ones below until a handler returns `false`. `onClick` and
60
+ * `onRelease` return `false` by default, so a press on a UI element stops
61
+ * there: a button over the game does not also click the world behind it.
62
+ * Return `true` from them to let the press through as well. Hover is not
63
+ * stopped by default: return `false` from `onOver` for that.
64
+ *
65
+ * ## Turning it off
66
+ * Set {@link UIBaseElement#enabled} to `false`: it stops answering the
67
+ * pointer, the keys and the pad, and a press in progress is called off.
68
+ *
69
+ * ## Dragging
70
+ * Set {@link UIBaseElement#isDraggable}: the element then follows the
71
+ * pointer while held. `onClick` is the pick-up, {@link UIBaseElement#onMove}
72
+ * runs on each move, and `onRelease` is the drop. Inside a scrolling
73
+ * {@link UIPanel}, a drag that starts on a widget scrolls the panel instead;
74
+ * set {@link UIBaseElement#keepsDrag} on a widget that is dragged itself.
75
+ *
76
+ * ## Bounce
77
+ * {@link UIBaseElement#hoverScale} and {@link UIBaseElement#pressScale}
78
+ * scale the drawing under the pointer and while held, easing there and back.
79
+ * The hit area and the layout do not change.
80
+ *
81
+ * ## Keyboard and gamepad focus
82
+ * For a game played without a mouse or a touch screen. Nothing listens until
83
+ * a widget takes the focus with {@link UIBaseElement#focus}; until then the
84
+ * arrow keys and the pad are left to the game. With a widget focused:
85
+ * - the arrow keys or the D-pad move the focus to the nearest
86
+ * {@link UIBaseElement#focusable} widget that way, measured edge to edge;
87
+ * - Enter, Space or the pad's A button press the focused widget, as a click
88
+ * does;
89
+ * - a ring in {@link UIBaseElement.focusRingColor} shows the focus while the
90
+ * keyboard or a pad is used, and hides when the mouse moves;
91
+ * - a focused widget inside a scrolling {@link UIPanel} is scrolled into view;
92
+ * - {@link UIBaseElement#blur}, or removing the widget, gives the keys and
93
+ * the pad back to the game.
94
+ *
95
+ * The built-in widgets are focusable. A widget of your own sets `focusable`
96
+ * and can override {@link UIBaseElement#onNavigate} to use the arrows itself.
14
97
  * @category UI
15
98
  * @example
16
- * // a panel that is opaque to the pointer and comes to the front when picked
17
- * class Panel extends UIBaseElement {
99
+ * // a widget of your own: draws itself, bounces, and acts on release
100
+ * import { UIBaseElement } from "melonjs";
101
+ *
102
+ * class Card extends UIBaseElement {
103
+ * constructor(x, y) {
104
+ * super(x, y, 120, 160);
105
+ * this.focusable = true; // reachable with the arrow keys and the pad
106
+ * this.hoverScale = 1.05;
107
+ * this.pressScale = 0.95;
108
+ * }
109
+ * draw(renderer, viewport) {
110
+ * renderer.setColor(this.hover ? "#ffffff" : "#cccccc");
111
+ * renderer.fillRect(this.pos.x, this.pos.y, this.width, this.height);
112
+ * super.draw(renderer, viewport); // draws the children
113
+ * }
114
+ * onRelease() {
115
+ * console.log("card picked");
116
+ * return false; // stop the event here (the default)
117
+ * }
118
+ * }
119
+ *
120
+ * app.world.addChild(new Card(50, 50));
121
+ * @example
122
+ * // a token dragged around and snapped to a 32 pixel grid when dropped
123
+ * import { UIBaseElement, Sprite } from "melonjs";
124
+ *
125
+ * class Token extends UIBaseElement {
126
+ * constructor(x, y) {
127
+ * super(x, y, 64, 64);
128
+ * this.isDraggable = true;
129
+ * // a sprite is centred on its position by default
130
+ * this.addChild(new Sprite(32, 32, { image: "token" }));
131
+ * }
132
+ * onMove() {
133
+ * // runs on each move while dragged: this.pos follows the pointer
134
+ * }
135
+ * onRelease() {
136
+ * this.pos.x = Math.round(this.pos.x / 32) * 32;
137
+ * this.pos.y = Math.round(this.pos.y / 32) * 32;
138
+ * return false;
139
+ * }
140
+ * }
141
+ * @example
142
+ * // a menu played with the keyboard or a pad: start on the first button
143
+ * import { UITextButton, state } from "melonjs";
144
+ *
145
+ * const play = new UITextButton(100, 200, {
146
+ * text: "Play",
147
+ * onClick: () => state.change(state.PLAY),
148
+ * });
149
+ * const quit = new UITextButton(100, 260, {
150
+ * text: "Quit",
151
+ * onClick: () => state.change(state.MENU),
152
+ * });
153
+ * app.world.addChild(play);
154
+ * app.world.addChild(quit);
155
+ * // the arrows / D-pad now move between them, Enter / Space / A press;
156
+ * // the mouse still works as before
157
+ * play.focus();
158
+ * @example
159
+ * // a panel that is opaque to hover too, and comes to the front when picked
160
+ * // (UIPanel does this with its `blocking` setting)
161
+ * import { UIBaseElement, input } from "melonjs";
162
+ *
163
+ * class Dialog extends UIBaseElement {
18
164
  * onClick() {
19
165
  * this.ancestor.moveToTop(this);
20
166
  * return false;
@@ -27,107 +173,354 @@ import Container from "../container.js";
27
173
  * // `onOver` no longer fires
28
174
  * onActivateEvent() {
29
175
  * super.onActivateEvent();
30
- * me.input.registerPointerEvent("pointermove", this, () => false);
176
+ * input.registerPointerEvent("pointermove", this, () => false);
31
177
  * }
32
178
  * onDeactivateEvent() {
33
- * me.input.releasePointerEvent("pointermove", this);
179
+ * input.releasePointerEvent("pointermove", this);
34
180
  * super.onDeactivateEvent();
35
181
  * }
36
182
  * }
37
183
  */
38
184
  export default class UIBaseElement extends Container {
39
185
  /**
40
- * UI base elements use screen coordinates by default
41
- * (Note: any child elements added to a UIBaseElement should have their floating property to false)
186
+ * UI elements use screen coordinates by default, so they stay put when
187
+ * the camera moves. Children added to a UIBaseElement should keep their
188
+ * own `floating` at `false`.
42
189
  * @see Renderable.floating
43
190
  * @default true
44
191
  */
45
192
  floating: boolean;
46
193
  /**
47
- * object can be clicked or not
194
+ * Whether the pointer can press the element. The low-level flag under
195
+ * {@link UIBaseElement#enabled}: prefer `enabled`, which also calls off a
196
+ * press in progress, blocks the keys and the pad, and draws a built-in
197
+ * widget disabled.
48
198
  * @default true
49
199
  */
50
200
  isClickable: boolean;
51
201
  /**
52
- * object can be dragged or not
202
+ * Whether the element follows the pointer while held. `onClick` runs on
203
+ * the pick-up, {@link UIBaseElement#onMove} on each move and `onRelease`
204
+ * on the drop.
53
205
  * @default false
54
206
  */
55
207
  isDraggable: boolean;
56
208
  /**
57
- * Tap and hold threshold timeout in ms
209
+ * How long a press must be held before {@link UIBaseElement#onHold}
210
+ * runs, in milliseconds. Needs `isHoldable`.
58
211
  * @default 250
59
212
  */
60
213
  holdThreshold: number;
61
214
  /**
62
- * object can be tap and hold
215
+ * Whether a press held for `holdThreshold` ms calls
216
+ * {@link UIBaseElement#onHold}.
63
217
  * @default false
64
218
  */
65
219
  isHoldable: boolean;
66
220
  /**
67
- * true if the pointer is over the object
221
+ * `true` while the pointer is over the element. A tap on a touch screen
222
+ * does not set it. Cleared when the element is removed, so one added back
223
+ * later is not drawn lit until the pointer comes over it again.
68
224
  * @default false
69
225
  */
70
226
  hover: boolean;
71
227
  /**
72
- * false if the pointer is down, or true when the pointer status is up
228
+ * `false` while the element is held down (by the pointer, or by Enter /
229
+ * A with the focus), `true` otherwise. Removing a held element calls the
230
+ * press off (see {@link UIBaseElement#cancelPress}), so it is `true` again
231
+ * once out of the scene.
73
232
  * @default true
74
233
  */
75
234
  released: boolean;
235
+ /**
236
+ * the tap-and-hold timer of a press in progress, or -1
237
+ * @ignore
238
+ */
76
239
  holdTimeout: number;
240
+ /**
241
+ * While dragged: where the element was grabbed, relative to its
242
+ * position. `undefined` otherwise.
243
+ */
77
244
  grabOffset: Vector2d | undefined;
78
245
  /**
79
- * @param x - The x position of the container
80
- * @param y - The y position of the container
81
- * @param w - width of the container
82
- * @param h - height of the container
246
+ * @param x - the x position of the element, in screen pixels
247
+ * @param y - the y position of the element, in screen pixels
248
+ * @param w - the width of the element, in pixels
249
+ * @param h - the height of the element, in pixels
83
250
  */
84
251
  constructor(x: number, y: number, w?: number, h?: number);
85
252
  /**
86
- * function called when the object is pressed (to be extended)
87
- * @param _event - the event object
88
- * @returns return false if we need to stop propagating the event
253
+ * Whether a drag that starts on this element belongs to it.
254
+ *
255
+ * When `false`, a drag that starts on the element inside a scrolling
256
+ * {@link UIPanel} scrolls the panel and calls off the press. Set it on a
257
+ * widget that handles its own drags, such as a knob or a colour picker,
258
+ * as {@link UISlider} does. An `isDraggable` element keeps its drags
259
+ * anyway.
260
+ * @default false
261
+ * @example
262
+ * // a colour wheel that reads drags itself, inside a scrolling panel
263
+ * class ColourWheel extends UIBaseElement {
264
+ * constructor(x, y) {
265
+ * super(x, y, 128, 128);
266
+ * this.keepsDrag = true;
267
+ * }
268
+ * }
269
+ */
270
+ keepsDrag: boolean;
271
+ /**
272
+ * The scale the widget is drawn at under the pointer, or while it shows
273
+ * the focus ring: a little bounce, such as `1.05`. `1` turns it off.
274
+ *
275
+ * Only the drawing scales, about the widget's centre. Its hit area and
276
+ * its place in a layout stay the same, so the widgets around it do not
277
+ * move. The scale eases there and back by itself (about 0.2 s). A
278
+ * disabled widget does not grow.
279
+ * @default 1
280
+ * @example
281
+ * button.hoverScale = 1.05;
282
+ * button.pressScale = 0.92;
283
+ */
284
+ hoverScale: number;
285
+ /**
286
+ * The scale the widget is drawn at while held down, such as `0.92`.
287
+ * `1` turns it off. Drawing only, as {@link UIBaseElement#hoverScale}.
288
+ * @default 1
289
+ */
290
+ pressScale: number;
291
+ /**
292
+ * Whether this element can take the keyboard and gamepad focus: see
293
+ * {@link UIBaseElement#focus}. The built-in buttons, checkboxes and
294
+ * sliders set it; set it on a widget of your own to make it reachable.
295
+ * A disabled or hidden element is skipped.
296
+ * @default false
297
+ */
298
+ focusable: boolean;
299
+ /**
300
+ * The colour of the ring drawn around the element with the focus, for
301
+ * every element. Any CSS colour.
302
+ * @default "#ffcc33"
303
+ * @example
304
+ * UIBaseElement.focusRingColor = "#00e0ff";
305
+ */
306
+ static focusRingColor: string;
307
+ /**
308
+ * The element with the keyboard and gamepad focus, or `undefined` when
309
+ * none has it.
310
+ * @example
311
+ * // give the focus back to the menu if nothing has it
312
+ * if (UIBaseElement.focusOwner === undefined) {
313
+ * playButton.focus();
314
+ * }
315
+ */
316
+ static get focusOwner(): UIBaseElement | undefined;
317
+ /** `true` while this element has the keyboard and gamepad focus */
318
+ get focused(): boolean;
319
+ /**
320
+ * Take the keyboard and gamepad focus, for a game played without a mouse
321
+ * or a touch screen. Call it once the element is in the scene.
322
+ *
323
+ * Nothing has the focus until a game gives it to an element, and until
324
+ * then the arrow keys and the pad are left to the game. From then on:
325
+ * the arrows or the D-pad move the focus to the nearest focusable element
326
+ * that way; Enter, Space or the pad's A button press the focused one as a
327
+ * click does (a slider steps on left and right instead). The focus ring
328
+ * shows, and hides again while the mouse is used. A focused element in a
329
+ * scrolling panel is scrolled into view.
330
+ *
331
+ * Does nothing on an element that is not `focusable`.
332
+ * @example
333
+ * // a menu played with the keyboard or a pad: start on Play
334
+ * app.world.addChild(playButton);
335
+ * app.world.addChild(optionsButton);
336
+ * playButton.focus();
337
+ * @example
338
+ * // a pause menu in a panel: focus its first button when it opens
339
+ * panel.addChild(resumeButton);
340
+ * panel.addChild(quitButton);
341
+ * app.world.addChild(panel);
342
+ * resumeButton.focus();
343
+ */
344
+ focus(): void;
345
+ /**
346
+ * Give up the focus, if this element has it. With nothing focused, the
347
+ * arrow keys and the pad go back to the game. Removing the element from
348
+ * the scene does the same.
349
+ * @example
350
+ * // leaving the menu for the game: the arrows move the player again
351
+ * UIBaseElement.focusOwner?.blur();
352
+ */
353
+ blur(): void;
354
+ /**
355
+ * Called for an arrow key or a D-pad direction while this element has
356
+ * the focus. Return `true` to handle it yourself (the focus stays here),
357
+ * as a slider does to step. Return `false`, the default, to move the
358
+ * focus to the nearest widget that way.
359
+ *
360
+ * Enter, Space and A do not come here: they press the widget through
361
+ * {@link UIBaseElement#focusPress} and {@link UIBaseElement#focusRelease}.
362
+ * @param _action - which way: `"up"`, `"down"`, `"left"` or `"right"`
363
+ * @returns `true` when handled
364
+ * @example
365
+ * // a picker: left and right change the choice, up and down move on
366
+ * class Picker extends UIBaseElement {
367
+ * constructor(x, y, choices) {
368
+ * super(x, y, 160, 32);
369
+ * this.focusable = true;
370
+ * this.choices = choices;
371
+ * this.index = 0;
372
+ * }
373
+ * onNavigate(action) {
374
+ * if (action === "left" || action === "right") {
375
+ * const step = action === "right" ? 1 : -1;
376
+ * const n = this.choices.length;
377
+ * this.index = (this.index + step + n) % n;
378
+ * this.isDirty = true;
379
+ * return true;
380
+ * }
381
+ * return false;
382
+ * }
383
+ * }
384
+ */
385
+ onNavigate(_action: UINavAction): boolean;
386
+ /**
387
+ * Called when Enter, Space or A is pressed with the focus here: the
388
+ * widget goes down, as under the pointer, and `onClick` runs with no
389
+ * event. Override it only to change what accept does.
390
+ * @returns whether it went down: not when disabled, or already held
391
+ */
392
+ focusPress(): boolean;
393
+ /**
394
+ * Called when Enter, Space or A is let go after
395
+ * {@link UIBaseElement#focusPress}: the widget comes back up and
396
+ * `onRelease` runs with no event. The built-in widgets complete their
397
+ * action here, as on a click: a button calls its `onClick` setting, a
398
+ * checkbox toggles.
399
+ */
400
+ focusRelease(): void;
401
+ /**
402
+ * Ease the bounce.
403
+ * @param dt - time since the last frame, in milliseconds
404
+ * @returns whether it needs redrawing
405
+ */
406
+ update(dt: number): boolean;
407
+ /**
408
+ * Apply the bounce, and draw the focus ring, behind the widget.
409
+ *
410
+ * Here and not in `draw`: a container translates to its own position in
411
+ * `draw`, so from `preDraw` on, the widget and the ring share the
412
+ * parent's coordinates, whatever the widget does in its own `draw`.
413
+ * @param renderer - the renderer to draw with
414
+ */
415
+ preDraw(renderer: Renderer): void;
416
+ /**
417
+ * Whether the widget answers input: the switch to turn a widget off.
418
+ *
419
+ * Turning it off clears `isClickable`, calls off a press in progress
420
+ * (see {@link UIBaseElement#cancelPress}), and skips it in keyboard and
421
+ * gamepad navigation. The built-in widgets draw themselves disabled:
422
+ * their `disabled` skin region, or at half opacity. A widget of your own
423
+ * reads `enabled` in its `draw`.
424
+ *
425
+ * `isClickable` is the low-level flag underneath; setting it alone does
426
+ * not change `enabled` or the look.
427
+ * @default true
428
+ * @example
429
+ * // greyed out until a save exists
430
+ * continueButton.enabled = false;
431
+ * // ... later
432
+ * continueButton.enabled = true;
433
+ */
434
+ get enabled(): boolean;
435
+ set enabled(value: boolean);
436
+ /**
437
+ * Call off a press in progress, without calling `onRelease`:
438
+ * {@link UIBaseElement#onCancel} runs instead.
439
+ *
440
+ * The element goes back to its released look, and the pointer-up that
441
+ * follows does nothing. A scrolling {@link UIPanel} calls this when a drag
442
+ * that started on the element turns out to be a scroll, so a button
443
+ * dragged to scroll its list is not clicked. Setting `enabled` to `false`,
444
+ * losing the focus or the window losing focus while Enter or A is held,
445
+ * and removing the element while it is held call it too.
446
+ */
447
+ cancelPress(): void;
448
+ /**
449
+ * Called when a press is called off rather than completed: see
450
+ * {@link UIBaseElement#cancelPress}. Override it to undo what `onClick`
451
+ * started, such as a charge-up effect.
452
+ */
453
+ onCancel(): void;
454
+ /**
455
+ * Called when the element is pressed: the pointer went down on it, or
456
+ * Enter / Space / A with the focus here (then with no event). Override it
457
+ * in a subclass.
458
+ *
459
+ * This is the press, not a completed click: see
460
+ * {@link UIBaseElement#onRelease} for the end of it.
461
+ * @param _event - the pointer event, or `undefined` from the keyboard or
462
+ * the pad
463
+ * @returns `false`, the default, to stop the event here; `true` to let
464
+ * elements below get it too
89
465
  */
90
466
  onClick(_event?: Pointer): boolean;
91
467
  /**
92
- * function called when the pointer is moved over the object
93
- * @param _event - the event object
468
+ * Called on each pointer move while the element is dragged (see
469
+ * {@link UIBaseElement#isDraggable}), after `pos` has followed the
470
+ * pointer. Override it in a subclass.
471
+ * @param _event - the pointer event
94
472
  */
95
473
  onMove(_event?: Pointer): void;
96
474
  /**
97
- * function called when the pointer is over the object.
475
+ * Called when the pointer comes over the element. Override it in a
476
+ * subclass.
98
477
  *
99
478
  * Fires once, on the frame the pointer crosses into the element. To stay
100
- * opaque for as long as the pointer rests on it, an element also wants a
101
- * `"pointermove"` callback registered through
102
- * {@link input.registerPointerEvent} returning `false`, since by then the
103
- * pointer is already inside and this no longer runs.
104
- * @param _event - the event object
105
- * @returns return false if we need to stop propagating the event, so that an
106
- * element covered by this one does not also light up on hover
479
+ * opaque to hover for as long as the pointer rests on it, also register a
480
+ * `"pointermove"` callback through {@link input.registerPointerEvent}
481
+ * that returns `false` (see the class example).
482
+ * @param _event - the pointer event
483
+ * @returns `false` to stop the event here, so an element covered by this
484
+ * one does not also light up
107
485
  */
108
486
  onOver(_event?: Pointer): boolean | void;
109
487
  /**
110
- * function called when the pointer is leaving the object area.
488
+ * Called when the pointer leaves the element. Override it in a subclass.
111
489
  *
112
- * Fires when the pointer leaves the element's bounds, and also when it is
113
- * still inside them but something drawn above has consumed the move, since
114
- * the pointer is then over that instead.
490
+ * Also fires when the pointer is still inside but something drawn above
491
+ * has stopped the move, since the pointer is then over that instead. A
492
+ * press in progress ends first, through `onRelease`.
115
493
  *
116
- * Unlike {@link UIBaseElement#onOver} this one cannot consume the event, on
117
- * purpose: an element that suppressed its own leave would stay in its hover
118
- * state after the pointer had gone.
119
- * @param _event - the event object
494
+ * It also fires, with no event, when the element is removed from the
495
+ * world while the pointer is on it (on its own, with a panel or container
496
+ * holding it, or with the scene), after a press in progress was called
497
+ * off through `onCancel`: undo there whatever `onOver` set up, and it
498
+ * cannot be left behind.
499
+ *
500
+ * Unlike {@link UIBaseElement#onOver} it cannot stop the event: an
501
+ * element that skipped its own leave would stay lit after the pointer
502
+ * had gone.
503
+ * @param _event - the pointer event
120
504
  */
121
505
  onOut(_event?: Pointer): void;
122
506
  /**
123
- * function called when the object is pressed and released (to be extended)
124
- * @param _event - the event object
125
- * @returns return false if we need to stop propagating the event
507
+ * Called when a press ends. Override it in a subclass.
508
+ *
509
+ * It runs when the pointer comes up, but also when the pointer leaves the
510
+ * element while held, or the browser cancels the press: it is the end
511
+ * of a press, not proof of a completed click. (For a click that only
512
+ * counts when completed, use a {@link UITextButton} and its `onClick`
513
+ * setting.) A press called off by {@link UIBaseElement#cancelPress} does
514
+ * not come here.
515
+ * @param _event - the pointer event, or `undefined` from the keyboard or
516
+ * the pad
517
+ * @returns `false`, the default, to stop the event here; `true` to let
518
+ * elements below get it too
126
519
  */
127
520
  onRelease(_event?: Pointer): boolean;
128
521
  /**
129
- * function called when the object is pressed and held<br>
130
- * to be extended <br>
522
+ * Called once a press has been held for `holdThreshold` milliseconds,
523
+ * when `isHoldable` is set. Override it in a subclass.
131
524
  */
132
525
  onHold(): void;
133
526
  }
@@ -1 +1 @@
1
- {"version":3,"file":"uibaseelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uibaseelement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIvD,OAAO,SAAS,MAAM,iBAAiB,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,SAAS;IACnD;;;;;OAKG;IACM,QAAQ,UAAQ;IAEzB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAGlB,WAAW,EAAE,MAAM,CAAC;IAGpB,UAAU,EAAE,QAAQ,GAAG,SAAS,CAAC;IAEjC;;;;;OAKG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM;IA+CxD;;;;OAIG;IAEH,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAuClC;;;OAGG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAI9B;;;;;;;;;;;OAWG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;IAuBxC;;;;;;;;;;;OAWG;IAEH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAmB7B;;;;OAIG;IAEH,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAkBpC;;;OAGG;IACH,MAAM,IAAI,IAAI;CA4Dd"}
1
+ {"version":3,"file":"uibaseelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uibaseelement.ts"],"names":[],"mappings":"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"}