-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathtypes.d.ts
More file actions
714 lines (698 loc) · 21.1 KB
/
types.d.ts
File metadata and controls
714 lines (698 loc) · 21.1 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
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
type LitecanvasInstance = {
/** The game screen width */
W: number
/** The game screen height */
H: number
/** the amount of time (in seconds) since the game started */
T: number
/** The current mouse's horizontal (X) position or -1 (if the mouse was not used or detected) */
MX: number
/** The current mouse's vertical (Y) position or -1 (if the mouse was not used or detected) */
MY: number
/** MATH API */
/**
* The value of the mathematical constant PI (π).
* Approximately 3.14159
*/
PI?: number
/**
* Twice the value of the mathematical constant PI (π).
* Approximately 6.28318
*
* Note: TWO_PI radians equals 360°, PI radians equals 180°,
* HALF_PI radians equals 90°, and HALF_PI/2 radians equals 45°.
*/
TWO_PI: number
/**
* Half the value of the mathematical constant PI (π).
* Approximately 1.57079
*/
HALF_PI: number
/**
* Calculates a linear (interpolation) value over t%.
*
* @param start
* @param end
* @param t The progress in percentage, where 0 = 0% and 1 = 100%.
* @returns The unterpolated value
* @tutorial https://gamedev.net/tutorials/programming/general-and-gameplay-programming/a-brief-introduction-to-lerp-r4954/
*/
lerp(start: number, end: number, t: number): number
/**
* Convert degrees to radians
*
* @param degs
* @returns the value in radians
*/
deg2rad(degs: number): number
/**
* Convert radians to degrees
*
* @param rads
* @returns the value in degrees
*/
rad2deg(rads: number): number
/**
* Returns the rounded value of an number to optional precision (number of digits after the decimal point).
*
* @param n number to round.
* @param [precision] number of decimal digits to round to, default is 0.
* @returns the rounded number.
*/
round(n: number, precision?: number): number
/**
* Constrains a number between `min` and `max`.
*
* @param value
* @param min
* @param max
* @returns
*/
clamp(value: number, min: number, max: number): number
/**
* Wraps a number between `min` (inclusive) and `max` (exclusive).
*
* @param value
* @param min
* @param max
* @returns the wrapped number
*/
wrap(value: number, min: number, max: number): number
/**
* Re-maps a number from one range to another.
*
* @param value the value to be remapped.
* @param start1 lower bound of the value's current range.
* @param stop1 upper bound of the value's current range.
* @param start2 lower bound of the value's target range.
* @param stop2 upper bound of the value's target range.
* @param [withinBounds=false] constrain the value to the newly mapped range
* @returns the remapped number
*/
map(
value: number,
start1: number,
stop1: number,
start2: number,
stop2: number,
withinBounds?: boolean
): number
/**
* Maps a number from one range to a value between 0 and 1.
* Identical to `map(value, min, max, 0, 1)`.
* Note: Numbers outside the range are not clamped to 0 and 1.
*
* @param value
* @param start
* @param stop
* @returns the normalized number.
*/
norm(value: number, start: number, stop: number): number
/**
* Calculates the distance between a point (x1, y1) to another (x2, y2).
*
* @param x1
* @param y1
* @param x2
* @param y2
* @returns the distance
*/
dist(x1: number, y1: number, x2: number, y2: number): number
/**
* Returns the sine of a number in radians
*/
sin?(n: number): number
/**
* Returns the cosine of a number in radians
*/
cos?(n: number): number
/**
* Returns the angle in the plane (in radians) between the positive x-axis and the ray from (0, 0) to the point (x, y)
*/
atan2?(y: number, x: number): number
/**
* Returns the square root of the sum of squares of its arguments.
*/
hypot?(...ns: number[]): number
/**
* Returns the tangent of a number in radians.
*/
tan?(n: number): number
/**
* Returns the absolute value of a number.
*/
abs?(n: number): number
/**
* Always rounds up and returns the smallest integer greater than or equal to a given number.
*/
ceil?(n: number): number
/**
* Always rounds down and returns the largest integer less than or equal to a given number.
*/
floor?(n: number): number
/**
* Returns the integer part of a number by removing any fractional digits.
*/
trunc?(n: number): number
/**
* Returns the smallest of the numbers given as input parameters, or `Infinity` if there are no parameters.
*/
min?(...ns: number[]): number
/**
* Returns the largest of the numbers given as input parameters, or `-Infinity` if there are no parameters.
*/
max?(...ns: number[]): number
/**
* Returns the value of a base raised to a power.
*/
pow?(base: number, exponent: number): number
/**
* Returns the square root of a number.
*/
sqrt?(n: number): number
/**
* Returns 1 or -1, indicating the sign of the number passed as argument.
* If the input is 0 or -0, it will be returned as-is.
*/
sign?(n: number): number
/**
* Returns the Euler's number raised to the power of a number.
*/
exp?(exponent: number): number
/** RNG API */
/**
* Generates a pseudorandom float between min (inclusive) and max (exclusive)
*
* @param [min=0.0]
* @param [max=1.0]
* @returns the random number
*/
rand(min?: number, max?: number): number
/**
* Generates a pseudorandom integer between min (inclusive) and max (inclusive)
*
* @param [min=0]
* @param [max=1]
* @returns the random number
*/
randi(min?: number, max?: number): number
/**
* Initializes the random number generator with an explicit seed value.
*
* Note: The seed should be a integer number greater than or equal to zero.
*
* @param value
*/
rseed(value: number): void
/** BASIC GRAPHICS API */
/**
* Clear the game screen with an optional color
*
* @param color The background color index or `null`
*/
cls(color: number | null): void
/**
* Draw a rectangle outline
*
* @param x
* @param y
* @param width
* @param height
* @param [color=0] the color index
* @param [radii] A number or list specifying the radii used to draw a rounded-borders rectangle
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/roundRect
*/
rect(
x: number,
y: number,
width: number,
height: number,
color?: number,
radii?: number | number[]
): void
/**
* Draw a color-filled rectangle
*
* @param x
* @param y
* @param width
* @param height
* @param [color=0] the color index
* @param [radii] A number or list specifying the radii used to draw a rounded-borders rectangle
*/
rectfill(
x: number,
y: number,
width: number,
height: number,
color?: number,
radii?: number | number[]
): void
/**
* Draw a circle outline
*
* @param x
* @param y
* @param radius
* @param [color=0] the color index
*/
circ(x: number, y: number, radius: number, color?: number): void
/**
* Draw a color-filled circle
*
* @param x
* @param y
* @param radius
* @param [color=0] the color index
*/
circfill(x: number, y: number, radius: number, color?: number): void
/**
* Draw a ellipse outline
*
* @param x
* @param y
* @param radiusX
* @param radiusY
* @param [color=0] the color index
*/
oval(x: number, y: number, radiusX: number, radiusY: number, color?: number): void
/**
* Draw a color-filled ellipse
*
* @param x
* @param y
* @param radiusX
* @param radiusY
* @param [color=0] the color index
*/
ovalfill(x: number, y: number, radiusX: number, radiusY: number, color?: number): void
/**
* Make a custom shape in the canvas context.
* Then, just use `fill` or `stroke` to draw the shape.
*
* @param points an array of Xs and Ys coordinates
*/
shape(points: number[]): void
/**
* Draw a line
*
* @param x1
* @param y1
* @param x2
* @param y2
* @param [color=0] the color index
*/
line(x1: number, y1: number, x2: number, y2: number, color?: number): void
/**
* Sets the thickness of lines
*
* @param value
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineWidth
*/
linewidth(value: number): void
/**
* Sets the line dash pattern used when drawing lines
*
* @param segments the line dash pattern
* @param [offset=0] the line dash offset, or "phase".
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
*/
linedash(segments: number[], offset?: number): void
/** TEXT RENDERING API */
/**
* Draw text. You can use `\n` to break lines.
*
* @param x
* @param y
* @param message the text message
* @param [color=3] the color index
* @param [fontStyle="normal"] can be "normal" (default), "italic" and/or "bold"
*/
text(x: number, y: number, message: string, color?: number, fontStyle?: string): void
/**
* Set the font family
*
* @param fontFamily
*/
textfont(fontFamily: string): void
/**
* Set the font size
*
* @param size
*/
textsize(size: number): void
/**
* Sets the alignment used when drawing texts
*
* @param align the horizontal alignment. Possible values: "left", "right", "center", "start" or "end"
* @param baseline the vertical alignment. Possible values: "top", "bottom", "middle", "hanging" or "ideographic"
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign
*/
textalign(align: CanvasTextAlign, baseline: CanvasTextBaseline): void
/**
* Sets the height ratio of the text lines based on current text size.
*
* Default = `1.2`
*
* @param value
*/
textgap(value: number): void
/** BASIC GRAPHICS API */
/**
* Draw an image
*
* @param x
* @param y
* @param source
*/
image(x: number, y: number, source: CanvasImageSource): void
/**
* Draw a sprite pixel by pixel represented by a string. Each pixel must be a base 36 number or a dot:
*
* - A base 36 number (`0-9` or `a-z`) represent a pixel color (supporting color palettes with max 36 colors).
* - A dot (`.`) represent a transparent pixel.
* - Spaces are ignored and can be used to improve the visualization.
*
* @param x the position X of the first pixel
* @param y the position Y of the first pixel
* @param pixels
*/
spr(x: number, y: number, pixels: string): void
/**
* Draw in an OffscreenCanvas and returns its image.
*
* @param width
* @param height
* @param callback
* @param [options]
* @see https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
*/
paint(
width: number,
height: number,
callback: drawCallback,
options?: {
scale?: number
canvas?: OffscreenCanvas
}
): ImageBitmap
/** ADVANCED GRAPHICS API */
/**
* Get or set the canvas context 2D
*
* @param [context] an new canvas context
* @returns the current canvas context
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D
*/
ctx(
context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
/**
* saves the current drawing style settings and transformations
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
*/
push(): void
/**
* restores the drawing style settings and transformations
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/restore
*/
pop(): void
/**
* Adds a translation transformation to the current matrix
*
* @param x
* @param y
*/
translate(x: number, y: number): void
/**
* Adds a scaling transformation to the canvas units horizontally and/or vertically.
*
* @param x
* @param [y]
*/
scale(x: number, y?: number): void
/**
* Adds a rotation to the transformation matrix
*
* @param radians
*/
rotate(radians: number): void
/**
* Sets the alpha (transparency) value to apply when drawing new shapes and images
*
* @param value float from 0 to 1 (e.g: 0.5 = 50% transparent)
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalAlpha
*/
alpha(value: number): void
/**
* Fills the current path with a given color.
*
* @param color
*/
fill(color: number): void
/**
* Outlines the current path with a given color.
*
* @param color
*/
stroke(color: number): void
/**
* Turns a path (in the callback) into the current clipping region.
*
* @param callback
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/clip
*/
clip(callback: clipCallback): void
/** SOUND API */
/**
* Play a sound effects using ZzFX library.
* If the first argument is omitted, plays an default sound.
*
* @param [zzfxParams] a ZzFX array of params
* @param [pitchSlide=0] a value to increment/decrement the pitch
* @param [volumeFactor=1] the volume factor
* @returns The sound that was played or `false`
*
* @see https://github.com/KilledByAPixel/ZzFX
*/
sfx(zzfxParams?: number[], pitchSlide?: number, volumeFactor?: number): number[] | boolean
/**
* Set the ZzFX's global volume factor.
* Note: use 0 to mute all sound effects.
*
* @param value
*/
volume(value: number): void
/** KEYBOARD API */
/**
* Checks if a which key is pressed on the keyboard.
* Note: use `iskeydown()` to check for any key pressed.
*
* @param key
* @returns `true` if the which key is down
*/
iskeydown?(key: string): boolean
/**
* Checks if a which key just got pressed on the keyboard.
* Note: use `iskeypressed()` to check for any key.
*
* @param [key]
* @returns `true` if the which key was pressed
*/
iskeypressed?(key: string): boolean
/**
* Returns the last pressed.
*
* @returns {string}
*/
lastkey?(): string
/** PLUGINS API */
/**
* Returns the canvas
*/
canvas(): HTMLCanvasElement
/**
* Prepares a plugin to be loaded
*
* @param callback
*/
use(callback: pluginCallback): void
/**
* Add a game loop event listener.
*
* @param event The game event type
* @param callback the function that is called when the event occurs
*/
listen(event: string, callback: Function): void
/**
* Remove a game loop event listener.
*
* @param event The game event type
* @param callback the function that is called when the event occurs
*/
unlisten(event: string, callback: Function): void
/**
* Call all listeners attached to a game event.
*
* Note: when the `litecanvas()` "loop" option is `null` (default),
* `emit()` will first call a global function matching the event name (if it exists).
* E.g: `emit("boom", 10)` calls `window.boom(10)`.
*
* @param event The game event type
* @param [arg1] any data to be passed over the listeners
* @param [arg2] any data to be passed over the listeners
* @param [arg3] any data to be passed over the listeners
* @param [arg4] any data to be passed over the listeners
*/
emit(event: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any): void
/**
* Define or update a instance property.
*
* Note: when the `litecanvas()` option "global" is `true` (default),
* `def()` with set/update a global property.
* E.g: `def('ONE', 1)` also do `window.ONE = 1`.
*
* @param key the property name
* @param value the property value
*/
def(key: string, value: any): void
/**
* Set new palette colors or restore the default palette.
*
* @param colors an array of colors
* @param textColor the new default text color (default: 3)
*/
pal(colors?: string[], textColor?: number): void
/**
* Replace the color "a" with color "b".
*
* If called without arguments, reset the current palette.
*
* Note: `palc()` don't affect drawings made with `image()`.
*
* @param a
* @param b
*/
palc(a?: number, b?: number): void
/**
* The scale of the game's delta time (dt).
* Values higher than 1 increase the speed of time, while values smaller than 1 decrease it.
* A value of 0 freezes time and is effectively equivalent to pausing.
*
* @param value
*/
timescale(value: number): void
/**
* Set the target FPS (frames per second).
*
* @param fps
*/
framerate(fps: number): void
/**
* Returns information about the engine instance.
*
* - n = 0: the settings passed to this instance
* - n = 1: returns true if the "init" event has already been emitted
* - n = 2: the current delta time (dt)
* - n = 3: the current canvas element scale (not the context 2D scale)
* - n = 4: the attached event callbacks
* - n = 5: the current color palette
* - n = 6: the default sound used by `sfx()`
* - n = 7: the current time scale
* - n = 8: the current volume used by ZzFX
* - n = 9: the current RNG state
* - n = 10: the current font size
* - n = 11: the current font family
* - n = 12: the current state of the color palette
* - n = 13: the current font gap
* - n = *any other value*: probably returns undefined
*
* @param index
*/
stat(index: number | string): any
/**
* Pauses the engine loop (update & draw).
*/
pause(): void
/**
* Resumes (if paused) the engine loop.
*/
resume(): void
/**
* Returns `true` if the engine loop is paused.
*/
paused(): boolean
/**
* Shutdown the litecanvas instance and remove all event listeners.
*/
quit(): void
}
type LitecanvasOptions = {
/**
* The game screen width. If not set, the canvas will have the size of the webpage.
*/
width?: number
/**
* The game screen height.
*/
height?: number
/**
* Used to specify the selector of a custom canvas element
*/
canvas?: HTMLCanvasElement | string
/**
* If `true` (default) scales the canvas to fill the screen, but preserving the aspect ratio.
* Instead of `true`, you can pass a number to determine the maximum scale.
*
* Note: Only works if the option "width" was specified.
*/
autoscale?: boolean | number
/**
* If `true` (default), all methods and properties of the engine will be exposed to the global scope (window).
*/
global?: boolean
/**
* Specify your game loop listener callbacks.
*
* By default, it uses global functions with the same name as the events (if they exist).
*
* Example: `window.init`, `window.update`, `window.draw`, etc
*/
loop?: LitecanvasGameLoop
/**
* default: `true`
*
* if `false` disable the click/touch events handling.
*
* Useful when you want to implement your own input handler.
*/
tapEvents?: boolean
/**
* default: `true`
*
* if `false` disable the `iskeydown()` method.
*
* Useful when you want to implement your keyboard handler.
*/
keyboardEvents?: boolean
}
type LitecanvasGameLoop = {
init?: () => void
update?: (dt: number) => void
draw?: () => void
resized?: () => void
tap?: (tapX: number, tapY: number, touchId: number) => void
untap?: (tapX: number, tapY: number, touchId: number) => void
tapped?: (tapX: number, tapY: number, touchId: number) => void
tapping?: (tapX: number, tapY: number, touchId: number) => void
}
type drawCallback = (context: OffscreenCanvasRenderingContext2D) => void
type pluginCallback = (instance: LitecanvasInstance, config?: any) => any
type clipCallback = (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => void
interface Window {
zzfxV: number
ENGINE: LitecanvasInstance | undefined
}