thrunium 1.2.0-rc.2 → 1.2.0-rc.4

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.
@@ -1,5 +1,68 @@
1
+ import { Keys, Mouse } from './input';
2
+ import type { Sprite } from './sprite';
3
+ import { type Timer } from './timers';
4
+ import { type FontSpec, type FontStatus } from './fonts';
5
+ import { Debug } from './debug';
6
+ import { Button, type ButtonOptions } from './button';
1
7
  /** Handler signature shared by the user-assignable event fields without a more specific event type. */
2
8
  export type Handler = (evt: Event) => void;
9
+ /** Options for `Game.drawImage()`. */
10
+ export interface DrawImageOptions {
11
+ /** Width to draw at. Default is the image's (or sprite frame's) natural width. */
12
+ width?: number;
13
+ /** Height to draw at. Default is the image's (or sprite frame's) natural height. */
14
+ height?: number;
15
+ /** Rotation in radians, clockwise, around (x, y). Default is `0`. */
16
+ angle?: number;
17
+ /** Whether (x, y) is the image's `'center'` or its `'top-left'` corner. Default is `'top-left'`. */
18
+ anchor?: 'center' | 'top-left';
19
+ /** Opacity from `0` to `1`. Default is `1`. */
20
+ alpha?: number;
21
+ /** Mirror the image left to right. */
22
+ flipX?: boolean;
23
+ /** Mirror the image top to bottom. */
24
+ flipY?: boolean;
25
+ }
26
+ /** Options for `Game.drawText()`; anything left out uses the game's `font`, `textSize` and fill color. */
27
+ export interface DrawTextOptions {
28
+ /** Font size: a number of pixels, or a CSS size such as `'2em'`. */
29
+ size?: number | string;
30
+ /** Horizontal alignment of the text around x. */
31
+ align?: CanvasTextAlign;
32
+ /** Vertical alignment of the text around y. */
33
+ baseline?: CanvasTextBaseline;
34
+ /** Fill color for this text. */
35
+ color?: string;
36
+ /** Font family. */
37
+ font?: string;
38
+ /** Font weight, for example `'bold'` or `'700'`. */
39
+ weight?: string;
40
+ }
41
+ /**
42
+ * A game state as an object instead of a function. Every member is optional. While it is the current state, `enter()` runs once when the game switches to it, `update(dt)` and `draw()` run every frame (`update` not while `paused`), and `exit()` runs once when the game switches away. Timers made with `after()` or `every()` while it is current are cancelled when it exits.
43
+ *
44
+ * @category Scenes
45
+ * @example
46
+ * ```js
47
+ * var game = new THRUNIUM.Game(400, 400);
48
+ * game.states.play = {
49
+ * enter: function() { score = 0; },
50
+ * update: function(dt) { player.x += 100 * dt; },
51
+ * draw: function() { game.drawText('Score: ' + score, 10, 30); },
52
+ * exit: function() { saveScore(score); },
53
+ * };
54
+ * ```
55
+ */
56
+ export interface Scene {
57
+ /** Runs once when the game switches to this scene, before its first `update`. */
58
+ enter?(): void;
59
+ /** Runs every frame while not paused, with the seconds since the previous frame, capped at `0.1`. */
60
+ update?(dt: number): void;
61
+ /** Runs every frame, after `update`, paused or not. */
62
+ draw?(): void;
63
+ /** Runs once when the game switches away from this scene. */
64
+ exit?(): void;
65
+ }
3
66
  /** An asset given as an object: the file, the key to store it under and an optional sprite map. */
4
67
  export type AssetEntry = {
5
68
  src: string;
@@ -17,6 +80,7 @@ export type AssetEntry = {
17
80
  * mouse, touch, keyboard and device events.
18
81
  */
19
82
  export declare class Game {
83
+ #private;
20
84
  [Symbol.toStringTag]: string;
21
85
  /**
22
86
  * Width of the game in pixels, as passed to the constructor. Read-only: changing it does not resize the canvas.
@@ -97,6 +161,28 @@ export declare class Game {
97
161
  * ```
98
162
  */
99
163
  delta: number;
164
+ /**
165
+ * Seconds the scenes advanced by in the last frame: `delta` capped at `0.1`, so a long hitch does not make things jump. Scenes get it as `update(dt)`; timers and `time` use it too. Updated every frame; if your code assigns its own value, the engine leaves it alone from then on and keeps its own count.
166
+ *
167
+ * @category Scenes
168
+ * @example
169
+ * ```js
170
+ * var game = new THRUNIUM.Game(400, 400);
171
+ * game.dt;
172
+ * ```
173
+ */
174
+ dt: number;
175
+ /**
176
+ * Game time in seconds: the sum of `dt` over the frames that were not paused, from the end of the loading screen. Timers run on the same clock. Updated every frame; if your code assigns its own value (a game written before 1.2.0 may keep its own `time`), the engine leaves it alone from then on, and its timers keep their own clock.
177
+ *
178
+ * @category Scenes
179
+ * @example
180
+ * ```js
181
+ * var game = new THRUNIUM.Game(400, 400);
182
+ * game.drawText('Time: ' + Math.floor(game.time), 10, 30);
183
+ * ```
184
+ */
185
+ time: number;
100
186
  /**
101
187
  * Frames per second of the game loop. Updated every frame. Read-only: an overwritten value is replaced on the next frame.
102
188
  *
@@ -109,7 +195,7 @@ export declare class Game {
109
195
  */
110
196
  fps: number;
111
197
  /**
112
- * Current frames per second divided by 60, as a number with two decimals (for example `1`). Use it to correct game speed on devices that run below 60 fps. Updated every frame. Read-only.
198
+ * Current frames per second divided by 60, as a number with two decimals (for example `1`). Use it to correct game speed on devices that run below 60 fps. Starts at `1`, so it is safe to use from the first frame, and is updated every frame from the second. Read-only.
113
199
  *
114
200
  * @category Variables
115
201
  * @example
@@ -152,6 +238,18 @@ export declare class Game {
152
238
  * ```
153
239
  */
154
240
  showFPS: boolean;
241
+ /**
242
+ * The debug menu: a panel over the page with fps, a frame-time graph, state, timers, assets, fonts, input and your own `watch` lines. It is off unless you set `game.debug.enabled = true`, except under `thrunium dev` where it starts on. Press the backquote key to show or hide it.
243
+ *
244
+ * @category Variables
245
+ * @example
246
+ * ```js
247
+ * var game = new THRUNIUM.Game(400, 400);
248
+ * game.debug.enabled = true;
249
+ * game.debug.watch('score', function() { return score; });
250
+ * ```
251
+ */
252
+ debug: Debug;
155
253
  /**
156
254
  * Free-form name for the game. The engine does not use it, so it is available for your own bookkeeping, for example to prefix saved data. Default is an empty string.
157
255
  *
@@ -186,16 +284,49 @@ export declare class Game {
186
284
  */
187
285
  mouseY: number;
188
286
  /**
189
- * Name of the state the game loop is currently running (a key of `states`). It starts as the built-in loading screen, `"startup"`, and switches to `startState` once everything has loaded. Assign a new name to change state.
287
+ * The keyboard: which keys are held, and which went down or up since the previous frame. Keys are `KeyboardEvent.code` values such as `'KeyW'`. The engine listens for you, and your `keydown` and `keyup` handlers still run.
288
+ *
289
+ * @category Input
290
+ * @example
291
+ * ```js
292
+ * var game = new THRUNIUM.Game(400, 400);
293
+ * game.states.play = function() {
294
+ * if (game.keys.isDown('KeyW')) player.y -= 2;
295
+ * };
296
+ * ```
297
+ */
298
+ keys: Keys;
299
+ /**
300
+ * The mouse: pointer position in game coordinates, and which buttons are held or went down or up since the previous frame. A touch counts as button 0.
301
+ *
302
+ * @category Input
303
+ * @example
304
+ * ```js
305
+ * var game = new THRUNIUM.Game(400, 400);
306
+ * game.states.play = function() {
307
+ * if (game.mouse.wasPressed()) fireAt(game.mouse.x, game.mouse.y);
308
+ * };
309
+ * ```
310
+ */
311
+ mouse: Mouse;
312
+ /**
313
+ * Name of the state the game is in (a key of `states`). It starts as the built-in loading screen, `"startup"`, and switches to `startState` once everything has loaded. Assign a new name to change state: the switch happens at the start of the next frame (the rest of this frame stays in the old state), but reading `state` returns the new name straight away. On the switch the old scene's `exit()` runs, then the new scene's `enter()`. If the name is still not in `states` when the switch happens, the next frame throws an error listing the names that are.
190
314
  *
191
315
  * @category Variables
192
316
  * @example
193
317
  * ```js
194
318
  * var game = new THRUNIUM.Game(400, 400);
195
- * game.state = 'game'; // run game.states['game'] each frame
319
+ * game.state = 'game'; // run game.states['game'] from the next frame
196
320
  * ```
197
321
  */
198
- state: string;
322
+ get state(): string;
323
+ set state(name: string);
324
+ /** The last name assigned to `state`; the loop switches to it at the start of the next frame. */
325
+ private _requestedState;
326
+ /** The state the loop is running this frame. */
327
+ private _runningState;
328
+ /** The scene whose `enter()` has started and whose `exit()` has not; timers made now belong to it. */
329
+ private _scene;
199
330
  /**
200
331
  * Name of the state to run after the loading screen. Used once, so set it before `init()`. Default is `null`, so you have to set it.
201
332
  *
@@ -208,7 +339,7 @@ export declare class Game {
208
339
  */
209
340
  startState: string | null;
210
341
  /**
211
- * Your game states: an object of functions keyed by name. The function named by `state` is called every frame. Change `state` to switch between them.
342
+ * Your game states, keyed by name. Each is a function, called every frame while it is the current state, or a `Scene` object with optional `enter`, `update`, `draw` and `exit`. Change `state` to switch between them.
212
343
  *
213
344
  * @category Variables
214
345
  * @example
@@ -217,9 +348,26 @@ export declare class Game {
217
348
  * game.states['game'] = function() {
218
349
  * // your code, run every frame
219
350
  * };
351
+ * game.states['play'] = {
352
+ * update: function(dt) { player.x += 100 * dt; },
353
+ * draw: function() { game.drawImage(game.image('player.png'), player.x, 100); },
354
+ * };
355
+ * ```
356
+ */
357
+ states: Record<string, (() => void) | (Scene & object)>;
358
+ /**
359
+ * Set to `true` to pause the game: scenes stop getting `update`, and timers and `time` stop, while `draw` keeps running. A function state is still called every frame, since it is its own update and draw. Default is `false`.
360
+ *
361
+ * @category Scenes
362
+ * @example
363
+ * ```js
364
+ * var game = new THRUNIUM.Game(400, 400);
365
+ * game.keydown = function(e) {
366
+ * if (e.code === 'KeyP') game.paused = !game.paused;
367
+ * };
220
368
  * ```
221
369
  */
222
- states: Record<string, () => void>;
370
+ paused: boolean;
223
371
  /**
224
372
  * Background color drawn behind every frame. Accepts any CSS color (hex, rgb, rgba, hsl, hsla). Default is `"#fff"`.
225
373
  *
@@ -267,6 +415,40 @@ export declare class Game {
267
415
  * ```
268
416
  */
269
417
  assets: Array<string | AssetEntry> & Record<string, any>;
418
+ /**
419
+ * Fonts to load on the loading screen. Set it before `init()`. Each entry is a Google Fonts URL (a string, or `{ url, cdn? }`), or a font file `{ family, src, weight?, style? }`. `thrunium build` and `thrunium dev` ship Google Fonts with the game; `cdn: true` always loads from Google instead. The loading bar counts the fonts and the start state only runs once every font has loaded or failed; a failed font logs a warning and the game uses the fallback font.
420
+ *
421
+ * @category Assets
422
+ * @example
423
+ * ```js
424
+ * var game = new THRUNIUM.Game(400, 400);
425
+ * game.fonts = [
426
+ * 'https://fonts.googleapis.com/css2?family=Lobster',
427
+ * { family: 'Pixel', src: 'fonts/pixel.woff2' }
428
+ * ];
429
+ * game.startState = 'game';
430
+ * game.states['game'] = function() {
431
+ * game.ctx.font = '30px Lobster';
432
+ * game.ctx.fillText('Hello', 20, 50);
433
+ * };
434
+ * game.init();
435
+ * game.start();
436
+ * ```
437
+ */
438
+ fonts: FontSpec[];
439
+ /**
440
+ * Progress of the declared `fonts`, or `null` before `init()`: `total`, `loaded()`, `done` and the `sources` of each font.
441
+ *
442
+ * @category Variables
443
+ * @example
444
+ * ```js
445
+ * var game = new THRUNIUM.Game(400, 400);
446
+ * game.fonts = ['https://fonts.googleapis.com/css2?family=Lobster'];
447
+ * game.init();
448
+ * game.fontStatus.total; // 1
449
+ * ```
450
+ */
451
+ fontStatus: FontStatus | null;
270
452
  /**
271
453
  * Whether `loadAssets()` has run, so the entries of `assets` have been turned into loadable elements. Use `loadedAssets` to see how many have actually finished loading.
272
454
  *
@@ -300,6 +482,17 @@ export declare class Game {
300
482
  * ```
301
483
  */
302
484
  assetsToLoad: number;
485
+ /**
486
+ * Number of assets whose load failed (a missing file or a network error). A failed asset is not counted in `loadedAssets`, so the loading screen stays up, as it always has. Read-only.
487
+ *
488
+ * @category Variables
489
+ * @example
490
+ * ```js
491
+ * var game = new THRUNIUM.Game(400, 400);
492
+ * if (game.failedAssets > 0) console.log('some assets did not load');
493
+ * ```
494
+ */
495
+ get failedAssets(): number;
303
496
  /**
304
497
  * Font family used by `drawText`. Default is `"Arial"`.
305
498
  *
@@ -543,6 +736,53 @@ export declare class Game {
543
736
  * ```
544
737
  */
545
738
  loadAssets(): void;
739
+ /**
740
+ * Returns a loaded image asset. It throws an `Error` naming the path when the path is unknown (listing what is loaded), still loading, failed to load, or not an image. Use it instead of `game.assets[path]` to get the right type and a clear error.
741
+ *
742
+ * @category Assets
743
+ * @param path The path of the image, as given in `assets`.
744
+ * @example
745
+ * ```js
746
+ * var game = new THRUNIUM.Game(400, 400);
747
+ * game.assets = ['images/ship.png'];
748
+ * game.startState = 'play';
749
+ * game.states.play = function() {
750
+ * game.drawImage(game.image('images/ship.png'), 100, 100);
751
+ * };
752
+ * ```
753
+ */
754
+ image(path: string): HTMLImageElement;
755
+ /**
756
+ * Returns a loaded sound asset. It throws an `Error` naming the path when the path is unknown (listing what is loaded), still loading, failed to load, or not a sound.
757
+ *
758
+ * @category Assets
759
+ * @param path The path of the sound, as given in `assets`.
760
+ * @example
761
+ * ```js
762
+ * var game = new THRUNIUM.Game(400, 400);
763
+ * game.assets = ['sounds/laser.wav'];
764
+ * game.click = function() {
765
+ * game.sound('sounds/laser.wav').play();
766
+ * };
767
+ * ```
768
+ */
769
+ sound(path: string): HTMLAudioElement;
770
+ /**
771
+ * Returns a loaded sprite: an `assets` entry that has a `spriteMap`, by its `index`. It throws an `Error` naming the index when it is unknown (listing what is loaded), still loading, failed to load, or not a sprite.
772
+ *
773
+ * @category Assets
774
+ * @param index The `index` of the assets entry.
775
+ * @example
776
+ * ```js
777
+ * var game = new THRUNIUM.Game(400, 400);
778
+ * game.assets = [{ src: 'images/tiles.png', index: 'tiles', spriteMap: { width: 32, height: 32 } }];
779
+ * game.startState = 'play';
780
+ * game.states.play = function() {
781
+ * game.sprite('tiles').draw(0, 100, 100);
782
+ * };
783
+ * ```
784
+ */
785
+ sprite(index: string): Sprite;
546
786
  /**
547
787
  * Sets the fill color used by `fill()` and `drawText`.
548
788
  *
@@ -614,19 +854,21 @@ export declare class Game {
614
854
  */
615
855
  drawLine(x1: number, y1: number, x2: number, y2: number, width?: number): void;
616
856
  /**
617
- * Draws text at (x, y) using `font` and `textSize` and the fill color.
857
+ * Draws text at (x, y) using `font` and `textSize` and the fill color. Pass `options` to change the size, alignment, baseline, color or font for this one call; the canvas state is restored afterwards.
618
858
  *
619
859
  * @category Drawing
620
860
  * @param text The text to draw.
621
861
  * @param x X coordinate of the text.
622
862
  * @param y Y coordinate of the text.
863
+ * @param options Optional settings for this call only.
623
864
  * @example
624
865
  * ```js
625
866
  * var game = new THRUNIUM.Game(400, 400);
626
867
  * game.drawText('Hello World!', 100, 100);
868
+ * game.drawText('Score', 200, 50, { size: 24, align: 'center', color: '#fff' });
627
869
  * ```
628
870
  */
629
- drawText(text: string, x: number, y: number): void;
871
+ drawText(text: string, x: number, y: number, options?: DrawTextOptions): void;
630
872
  /**
631
873
  * Traces a rectangle path, with rounded corners if `radius` is given. It only builds the path: call `fill()` or `stroke()` afterwards to draw it.
632
874
  *
@@ -660,14 +902,14 @@ export declare class Game {
660
902
  */
661
903
  drawCircle(x: number, y: number, radius: number): void;
662
904
  /**
663
- * Draws an image at (x, y), scaled to `width` by `height` when both are given.
905
+ * Draws an image or sprite at (x, y). Give `width` and `height` to scale it, or an options object to also rotate, flip, fade or centre it. A sprite draws the frame `drawAnim()` is showing (frame 0 when idle). The canvas state is restored afterwards.
664
906
  *
665
907
  * @category Drawing
666
- * @param img The image to draw, for example a loaded entry of `assets`.
667
- * @param x X coordinate of the left edge.
668
- * @param y Y coordinate of the top edge.
669
- * @param width Width to draw at. Needs `height` as well; leave out for the natural size.
670
- * @param height Height to draw at. Needs `width` as well; leave out for the natural size.
908
+ * @param img The image to draw, for example a loaded entry of `assets`, or a `Sprite`.
909
+ * @param x X coordinate of the left edge, or of the centre with `anchor: 'center'`.
910
+ * @param y Y coordinate of the top edge, or of the centre with `anchor: 'center'`.
911
+ * @param widthOrOptions Width to draw at (needs `height` as well; leave out for the natural size), or a `DrawImageOptions` object.
912
+ * @param height Height to draw at. Needs `width` as well; ignored when an options object is given.
671
913
  * @example
672
914
  * ```js
673
915
  * var game = new THRUNIUM.Game(400, 400);
@@ -675,9 +917,76 @@ export declare class Game {
675
917
  * game.init();
676
918
  * game.drawImage(game.assets['image.png'], 100, 100);
677
919
  * game.drawImage(game.assets['image.png'], 100, 100, 200, 200);
920
+ * game.drawImage(game.assets['image.png'], 100, 100, { angle: Math.PI / 4, anchor: 'center', alpha: 0.5 });
921
+ * ```
922
+ */
923
+ drawImage(img: CanvasImageSource | Sprite, x: number, y: number, widthOrOptions?: number | null | DrawImageOptions, height?: number | null): void;
924
+ /**
925
+ * Makes a clickable text button. Create it once, then call its `draw()` every frame (in a scene's `draw`, for example): it counts as hovered or clicked only if it was drawn in the previous frame too, so a button made anew each frame is never clickable. It keeps working while the game is `paused`.
926
+ *
927
+ * @category Drawing
928
+ * @param text The label.
929
+ * @param x X coordinate of the label, placed by `options.align`.
930
+ * @param y Y coordinate of the label, placed by `options.baseline`.
931
+ * @param options Text options for `drawText`, plus `hoverColor`, `padding` and `onHover`.
932
+ * @returns The button; read `hovered` and `clicked` from it.
933
+ * @example
934
+ * ```js
935
+ * var game = new THRUNIUM.Game(400, 400);
936
+ * var play = game.button('Play', 200, 200, { size: 28, align: 'center', baseline: 'middle', hoverColor: '#ff0' });
937
+ * game.states.menu = {
938
+ * draw: function() {
939
+ * play.draw();
940
+ * if (play.clicked) game.state = 'level1';
941
+ * }
942
+ * };
943
+ * ```
944
+ */
945
+ button(text: string, x: number, y: number, options?: ButtonOptions): Button;
946
+ /**
947
+ * Calls `fn` once, after `seconds` of game time. Game time stops while `paused`, and a long frame counts as at most 0.1 seconds. A timer made while a scene is the current state belongs to it and is cancelled when the scene exits; others run until they fire or are cancelled.
948
+ * @param seconds Game seconds to wait.
949
+ * @param fn The function to call.
950
+ * @returns The timer, with `cancel()` and `active`.
951
+ *
952
+ * @category Timers
953
+ * @example
954
+ * ```js
955
+ * var game = new THRUNIUM.Game(400, 400);
956
+ * game.states.play = {
957
+ * enter: function() {
958
+ * game.after(3, function() { game.state = 'gameover'; });
959
+ * },
960
+ * };
961
+ * ```
962
+ */
963
+ after(seconds: number, fn: () => void): Timer;
964
+ /**
965
+ * Calls `fn` every `seconds` of game time, until cancelled. It fires at most once per frame: calls missed in a long frame are dropped, not caught up. Like `after()`, a timer made while a scene is current is cancelled when that scene exits.
966
+ * @param seconds Game seconds between calls.
967
+ * @param fn The function to call.
968
+ * @returns The timer, with `cancel()` and `active`.
969
+ *
970
+ * @category Timers
971
+ * @example
972
+ * ```js
973
+ * var game = new THRUNIUM.Game(400, 400);
974
+ * var spawner = game.every(2, function() { enemies.push(newEnemy()); });
975
+ * spawner.cancel(); // stop spawning
976
+ * ```
977
+ */
978
+ every(seconds: number, fn: () => void): Timer;
979
+ /**
980
+ * Number of active timers made with `after()` and `every()`: ones that have not fired (for `after`) or been cancelled. Read-only.
981
+ *
982
+ * @category Timers
983
+ * @example
984
+ * ```js
985
+ * var game = new THRUNIUM.Game(400, 400);
986
+ * console.log(game.timerCount + ' timers running');
678
987
  * ```
679
988
  */
680
- drawImage(img: CanvasImageSource, x: number, y: number, width?: number | null, height?: number | null): void;
989
+ get timerCount(): number;
681
990
  /**
682
991
  * Starts the game loop. Each frame it clears the canvas, fills the background and runs the current state.
683
992
  * @example
@@ -699,4 +1008,16 @@ export declare class Game {
699
1008
  stop(): void;
700
1009
  /** Prefers the legacy window.requestAnimFrame alias, else requestAnimationFrame. */
701
1010
  private requestFrame;
1011
+ /** The state named `name`; throws an error listing the known names if there is none. */
1012
+ private stateNamed;
1013
+ /** Switches to the requested state if it changed: the old scene's `exit()`, then the new scene's `enter()`. */
1014
+ private switchState;
1015
+ /**
1016
+ * Runs one frame of the current state. A scene gets `update(dt)` and the timers advance unless paused (or a `stepOnce` advances both by 1/60); then it draws. A function state is called as it is, and timers advance unless paused.
1017
+ */
1018
+ private runState;
1019
+ /** Moves game time and the timers on by `dt` seconds. */
1020
+ private advanceTime;
1021
+ /** End-of-frame bookkeeping, after the game and the debug menu have drawn. Other per-frame sets reset here, before the input. */
1022
+ private endFrame;
702
1023
  }
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Shared bookkeeping for held inputs: what is down now, and what went down or
3
+ * up since the previous frame. `K` is the key type (a code string or a button number).
4
+ */
5
+ declare class InputSet<K> {
6
+ private readonly down;
7
+ /**
8
+ * What is down right now. Read-only.
9
+ *
10
+ * @example
11
+ * ```js
12
+ * var game = new THRUNIUM.Game(400, 400);
13
+ * game.keys.held.has('KeyW');
14
+ * game.mouse.held.has(0);
15
+ * ```
16
+ */
17
+ get held(): ReadonlySet<K>;
18
+ /** What went down since the previous frame. */
19
+ protected readonly pressed: Set<K>;
20
+ /** What came up since the previous frame. */
21
+ protected readonly released: Set<K>;
22
+ }
23
+ /**
24
+ * The keyboard, as read from `game.keys`. Keys are `KeyboardEvent.code` values such as
25
+ * `'KeyW'`, `'Space'` or `'ArrowLeft'`, so W, A, S and D sit in the same place on any keyboard layout.
26
+ *
27
+ * @category Input
28
+ * @example
29
+ * ```js
30
+ * var game = new THRUNIUM.Game(400, 400);
31
+ * game.states.play = function() {
32
+ * if (game.keys.isDown('KeyW')) player.y -= 2;
33
+ * if (game.keys.wasPressed('Space')) shoot();
34
+ * };
35
+ * ```
36
+ */
37
+ export declare class Keys extends InputSet<string> {
38
+ /**
39
+ * Returns `true` while the key is held. All held keys are released when the window loses focus, so a key never sticks after alt-tab.
40
+ * @param code The `KeyboardEvent.code` of the key.
41
+ * @example
42
+ * ```js
43
+ * if (game.keys.isDown('ArrowLeft')) player.x -= 3;
44
+ * ```
45
+ */
46
+ isDown(code: string): boolean;
47
+ /**
48
+ * Returns `true` for the one frame after the key went down. Holding the key does not repeat it.
49
+ * @param code The `KeyboardEvent.code` of the key.
50
+ * @example
51
+ * ```js
52
+ * if (game.keys.wasPressed('Space')) shoot();
53
+ * ```
54
+ */
55
+ wasPressed(code: string): boolean;
56
+ /**
57
+ * Returns `true` for the one frame after the key came up.
58
+ * @param code The `KeyboardEvent.code` of the key.
59
+ * @example
60
+ * ```js
61
+ * if (game.keys.wasReleased('Space')) stopCharging();
62
+ * ```
63
+ */
64
+ wasReleased(code: string): boolean;
65
+ }
66
+ /**
67
+ * The mouse, as read from `game.mouse`. A touch counts as button 0 at the touch position.
68
+ *
69
+ * @category Input
70
+ * @example
71
+ * ```js
72
+ * var game = new THRUNIUM.Game(400, 400);
73
+ * game.states.play = function() {
74
+ * if (game.mouse.wasPressed()) fireAt(game.mouse.x, game.mouse.y);
75
+ * };
76
+ * ```
77
+ */
78
+ export declare class Mouse extends InputSet<number> {
79
+ /**
80
+ * Pointer x in game coordinates, the same as `game.mouseX`.
81
+ *
82
+ * @example
83
+ * ```js
84
+ * var game = new THRUNIUM.Game(400, 400);
85
+ * game.mouse.x;
86
+ * ```
87
+ */
88
+ x: number;
89
+ /**
90
+ * Pointer y in game coordinates, the same as `game.mouseY`.
91
+ *
92
+ * @example
93
+ * ```js
94
+ * var game = new THRUNIUM.Game(400, 400);
95
+ * game.mouse.y;
96
+ * ```
97
+ */
98
+ y: number;
99
+ /**
100
+ * Returns `true` while the button is held.
101
+ * @param button The button number, `0` (left, and touch) by default.
102
+ * @example
103
+ * ```js
104
+ * if (game.mouse.isDown()) drag(game.mouse.x, game.mouse.y);
105
+ * ```
106
+ */
107
+ isDown(button?: number): boolean;
108
+ /**
109
+ * Returns `true` for the one frame after the button went down.
110
+ * @param button The button number, `0` (left, and touch) by default.
111
+ * @example
112
+ * ```js
113
+ * if (game.mouse.wasPressed()) fireAt(game.mouse.x, game.mouse.y);
114
+ * ```
115
+ */
116
+ wasPressed(button?: number): boolean;
117
+ /**
118
+ * Returns `true` for the one frame after the button came up.
119
+ * @param button The button number, `0` (left, and touch) by default.
120
+ * @example
121
+ * ```js
122
+ * if (game.mouse.wasReleased()) drop();
123
+ * ```
124
+ */
125
+ wasReleased(button?: number): boolean;
126
+ }
127
+ export {};
@@ -0,0 +1,14 @@
1
+ import type { Keys, Mouse } from './input';
2
+ /** What the engine's modules read about a Game instead of its public properties. */
3
+ export interface GameInternals {
4
+ keys: Keys;
5
+ mouse: Mouse;
6
+ /** Engine game time in seconds (the sum of unpaused `dt`). */
7
+ time(): number;
8
+ /** Seconds the scenes advanced by in the last frame. */
9
+ dt(): number;
10
+ }
11
+ /** Registers the engine's objects of `game`. Called once by the Game constructor. */
12
+ export declare function setInternals(game: object, value: GameInternals): void;
13
+ /** The engine's objects of `game`. */
14
+ export declare function getInternals(game: object): GameInternals;
@@ -2,6 +2,7 @@ import type { Game } from './game';
2
2
  import type { Sprite } from './sprite';
3
3
  import type { elemApi } from './elem';
4
4
  import type { Vector } from './vector';
5
+ import type { Button } from './button';
5
6
  import type { Collider } from './collider';
6
7
  import type { AjaxOptions } from './ajax';
7
8
  import type { storage } from './storage';
@@ -22,6 +23,7 @@ export interface Thrunium {
22
23
  Game: typeof Game;
23
24
  Elem?: typeof elemApi;
24
25
  Sprite?: typeof Sprite;
26
+ Button: typeof Button;
25
27
  Vector: typeof Vector;
26
28
  Collider: typeof Collider;
27
29
  ajax: (data: AjaxOptions) => XMLHttpRequest;
@@ -13,6 +13,8 @@ import * as tokenFlow from './storage-token';
13
13
  export { Game } from './game';
14
14
  export { Vector } from './vector';
15
15
  export { Sprite } from './sprite';
16
+ export { Button } from './button';
17
+ export type { ButtonOptions } from './button';
16
18
  export { Collider } from './collider';
17
19
  export { elemApi as Elem } from './elem';
18
20
  export { ajax } from './ajax';
@@ -46,7 +48,11 @@ export declare const version: string;
46
48
  /** The THRUNIUM global; docs-reference.mjs checks each public key has a page. */
47
49
  export type { Thrunium };
48
50
  export { ElemElem } from './elem';
51
+ export type { Keys, Mouse } from './input';
49
52
  export type { AjaxOptions } from './ajax';
50
53
  export type { StorageOptions } from './storage-token';
51
- export type { AssetEntry, Handler } from './game';
54
+ export type { AssetEntry, Handler, DrawImageOptions, DrawTextOptions, Scene } from './game';
55
+ export type { Debug } from './debug';
56
+ export type { Timer } from './timers';
52
57
  export type { StyleMap } from './elem';
58
+ export type { FontSpec, FontManifestEntry, FontManifest } from './fonts';
@@ -302,6 +302,28 @@ export declare class Sprite {
302
302
  * ```
303
303
  */
304
304
  setSpriteMap(width: number, height: number): void;
305
+ /**
306
+ * The source rectangle of a frame within the image, as used by `game.drawImage()` when it is given a sprite. Frames are laid out left to right, wrapping to the next row.
307
+ * @param frame Number of the frame, counting from 0. Default is the frame `drawAnim()` is showing, or `0` when no animation is running.
308
+ * @returns The frame's `sx`, `sy`, `sw` and `sh` in image pixels.
309
+ * @example
310
+ * ```js
311
+ * var game = new THRUNIUM.Game(400, 400);
312
+ * game.assets = [{ src: 'images/tiles.png', index: 'tiles', spriteMap: { width: 40, height: 40 } }];
313
+ * game.startState = 'game';
314
+ * game.states['game'] = function() {
315
+ * game.assets['tiles'].frameRect(2); // { sx: 80, sy: 0, sw: 40, sh: 40 } on a wide image
316
+ * };
317
+ * game.init();
318
+ * game.start();
319
+ * ```
320
+ */
321
+ frameRect(frame?: number): {
322
+ sx: number;
323
+ sy: number;
324
+ sw: number;
325
+ sh: number;
326
+ };
305
327
  /**
306
328
  * Draws one frame centred on (`x`, `y`), rotated by `angle`. The frame is drawn at its own size unless you pass `width` and `height`.
307
329
  * @param imgNum Number of the frame to draw, counting from 0 left to right, then row by row. Default is `0`.