@defold-typescript/types 0.38.0 → 0.40.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 (109) hide show
  1. package/api-availability.json +117 -0
  2. package/api-signatures.json +586 -480
  3. package/examples/translations.json +356 -180
  4. package/generated/b2d_body.d.ts +7 -4
  5. package/generated/b2d_shape.d.ts +23 -1
  6. package/generated/buffer.d.ts +34 -19
  7. package/generated/camera.d.ts +3 -2
  8. package/generated/collectionfactory.d.ts +17 -12
  9. package/generated/collectionproxy.d.ts +2 -2
  10. package/generated/compute.d.ts +1 -1
  11. package/generated/factory.d.ts +2 -1
  12. package/generated/go.d.ts +150 -91
  13. package/generated/graphics.d.ts +54 -0
  14. package/generated/gui.d.ts +117 -71
  15. package/generated/html5.d.ts +4 -2
  16. package/generated/http.d.ts +8 -2
  17. package/generated/image.d.ts +24 -15
  18. package/generated/kinds/gui-script.d.ts +1 -0
  19. package/generated/kinds/render-script.d.ts +1 -0
  20. package/generated/kinds/script.d.ts +1 -0
  21. package/generated/material.d.ts +1 -1
  22. package/generated/model.d.ts +41 -7
  23. package/generated/particlefx.d.ts +1 -1
  24. package/generated/physics.d.ts +29 -20
  25. package/generated/profiler.d.ts +10 -3
  26. package/generated/render.d.ts +293 -111
  27. package/generated/resource.d.ts +243 -226
  28. package/generated/socket.d.ts +33 -18
  29. package/generated/sound.d.ts +6 -5
  30. package/generated/sprite.d.ts +9 -1
  31. package/generated/sys.d.ts +44 -27
  32. package/generated/tilemap.d.ts +25 -19
  33. package/generated/timer.d.ts +33 -24
  34. package/generated/versions/defold-1.12.4/buffer.d.ts +34 -19
  35. package/generated/versions/defold-1.12.4/camera.d.ts +3 -2
  36. package/generated/versions/defold-1.12.4/collectionfactory.d.ts +17 -12
  37. package/generated/versions/defold-1.12.4/collectionproxy.d.ts +1 -1
  38. package/generated/versions/defold-1.12.4/factory.d.ts +2 -1
  39. package/generated/versions/defold-1.12.4/go.d.ts +150 -91
  40. package/generated/versions/defold-1.12.4/graphics.d.ts +2 -0
  41. package/generated/versions/defold-1.12.4/gui.d.ts +109 -69
  42. package/generated/versions/defold-1.12.4/html5.d.ts +4 -2
  43. package/generated/versions/defold-1.12.4/http.d.ts +8 -2
  44. package/generated/versions/defold-1.12.4/image.d.ts +24 -15
  45. package/generated/versions/defold-1.12.4/index.d.ts +1 -0
  46. package/generated/versions/defold-1.12.4/model.d.ts +41 -7
  47. package/generated/versions/defold-1.12.4/particlefx.d.ts +1 -1
  48. package/generated/versions/defold-1.12.4/physics.d.ts +29 -20
  49. package/generated/versions/defold-1.12.4/profiler.d.ts +10 -3
  50. package/generated/versions/defold-1.12.4/render.d.ts +292 -110
  51. package/generated/versions/defold-1.12.4/resource.d.ts +243 -226
  52. package/generated/versions/defold-1.12.4/socket.d.ts +33 -18
  53. package/generated/versions/defold-1.12.4/sound.d.ts +6 -5
  54. package/generated/versions/defold-1.12.4/sprite.d.ts +9 -1
  55. package/generated/versions/defold-1.12.4/sys.d.ts +44 -27
  56. package/generated/versions/defold-1.12.4/tilemap.d.ts +25 -19
  57. package/generated/versions/defold-1.12.4/timer.d.ts +33 -24
  58. package/generated/versions/defold-1.12.4/vmath.d.ts +18 -10
  59. package/generated/versions/defold-1.12.4/window.d.ts +5 -3
  60. package/generated/versions/defold-1.13.0/b2d_body.d.ts +7 -4
  61. package/generated/versions/defold-1.13.0/b2d_shape.d.ts +23 -1
  62. package/generated/versions/defold-1.13.0/buffer.d.ts +34 -19
  63. package/generated/versions/defold-1.13.0/camera.d.ts +3 -2
  64. package/generated/versions/defold-1.13.0/collectionfactory.d.ts +17 -12
  65. package/generated/versions/defold-1.13.0/collectionproxy.d.ts +1 -1
  66. package/generated/versions/defold-1.13.0/compute.d.ts +1 -1
  67. package/generated/versions/defold-1.13.0/factory.d.ts +2 -1
  68. package/generated/versions/defold-1.13.0/go.d.ts +150 -91
  69. package/generated/versions/defold-1.13.0/graphics.d.ts +50 -0
  70. package/generated/versions/defold-1.13.0/gui.d.ts +109 -69
  71. package/generated/versions/defold-1.13.0/html5.d.ts +4 -2
  72. package/generated/versions/defold-1.13.0/http.d.ts +8 -2
  73. package/generated/versions/defold-1.13.0/image.d.ts +24 -15
  74. package/generated/versions/defold-1.13.0/index.d.ts +1 -0
  75. package/generated/versions/defold-1.13.0/material.d.ts +1 -1
  76. package/generated/versions/defold-1.13.0/model.d.ts +41 -7
  77. package/generated/versions/defold-1.13.0/particlefx.d.ts +1 -1
  78. package/generated/versions/defold-1.13.0/physics.d.ts +29 -20
  79. package/generated/versions/defold-1.13.0/profiler.d.ts +10 -3
  80. package/generated/versions/defold-1.13.0/render.d.ts +293 -111
  81. package/generated/versions/defold-1.13.0/resource.d.ts +243 -226
  82. package/generated/versions/defold-1.13.0/socket.d.ts +33 -18
  83. package/generated/versions/defold-1.13.0/sound.d.ts +6 -5
  84. package/generated/versions/defold-1.13.0/sprite.d.ts +9 -1
  85. package/generated/versions/defold-1.13.0/sys.d.ts +44 -27
  86. package/generated/versions/defold-1.13.0/tilemap.d.ts +25 -19
  87. package/generated/versions/defold-1.13.0/timer.d.ts +33 -24
  88. package/generated/versions/defold-1.13.0/vmath.d.ts +18 -10
  89. package/generated/versions/defold-1.13.0/window.d.ts +5 -3
  90. package/generated/vmath.d.ts +18 -10
  91. package/generated/window.d.ts +5 -3
  92. package/index.d.ts +1 -0
  93. package/package.json +2 -1
  94. package/scripts/generate-api-signatures.ts +2 -1
  95. package/scripts/prose-constants.ts +96 -0
  96. package/scripts/regen.ts +6 -2
  97. package/src/api-doc.ts +8 -0
  98. package/src/component-properties.d.ts +33 -0
  99. package/src/core-types.ts +4 -2
  100. package/src/custom-messages.d.ts +4 -3
  101. package/src/doc-comment.ts +247 -43
  102. package/src/emit-dts.ts +958 -57
  103. package/src/engine-globals.d.ts +2 -2
  104. package/src/example-store.ts +26 -0
  105. package/src/go-overloads.d.ts +11 -10
  106. package/src/index.ts +9 -0
  107. package/src/param-correction-provenance.ts +67 -0
  108. package/src/render-overloads.d.ts +15 -17
  109. package/src/script-api.ts +3 -1
package/generated/go.d.ts CHANGED
@@ -6,6 +6,8 @@ declare global {
6
6
  * Game object API documentation
7
7
  */
8
8
  namespace go {
9
+ export type Easing = typeof go.EASING_INBACK | typeof go.EASING_INBOUNCE | typeof go.EASING_INCIRC | typeof go.EASING_INCUBIC | typeof go.EASING_INELASTIC | typeof go.EASING_INEXPO | typeof go.EASING_INOUTBACK | typeof go.EASING_INOUTBOUNCE | typeof go.EASING_INOUTCIRC | typeof go.EASING_INOUTCUBIC | typeof go.EASING_INOUTELASTIC | typeof go.EASING_INOUTEXPO | typeof go.EASING_INOUTQUAD | typeof go.EASING_INOUTQUART | typeof go.EASING_INOUTQUINT | typeof go.EASING_INOUTSINE | typeof go.EASING_INQUAD | typeof go.EASING_INQUART | typeof go.EASING_INQUINT | typeof go.EASING_INSINE | typeof go.EASING_LINEAR | typeof go.EASING_OUTBACK | typeof go.EASING_OUTBOUNCE | typeof go.EASING_OUTCIRC | typeof go.EASING_OUTCUBIC | typeof go.EASING_OUTELASTIC | typeof go.EASING_OUTEXPO | typeof go.EASING_OUTINBACK | typeof go.EASING_OUTINBOUNCE | typeof go.EASING_OUTINCIRC | typeof go.EASING_OUTINCUBIC | typeof go.EASING_OUTINELASTIC | typeof go.EASING_OUTINEXPO | typeof go.EASING_OUTINQUAD | typeof go.EASING_OUTINQUART | typeof go.EASING_OUTINQUINT | typeof go.EASING_OUTINSINE | typeof go.EASING_OUTQUAD | typeof go.EASING_OUTQUART | typeof go.EASING_OUTQUINT | typeof go.EASING_OUTSINE;
10
+ export type Playback = typeof go.PLAYBACK_ONCE_FORWARD | typeof go.PLAYBACK_ONCE_BACKWARD | typeof go.PLAYBACK_ONCE_PINGPONG | typeof go.PLAYBACK_LOOP_FORWARD | typeof go.PLAYBACK_LOOP_BACKWARD | typeof go.PLAYBACK_LOOP_PINGPONG;
9
11
  /**
10
12
  * in-back
11
13
  */
@@ -241,14 +243,15 @@ declare global {
241
243
  *
242
244
  * hash The id of the animated property.
243
245
  * @example
246
+ * Animate the position of a game object to x = 10 during 1 second, then y = 20 during 1 second:
244
247
  * ```ts
245
- * // Animate the position of a game object to x = 10 during 1 second, then
246
- * // y = 20 during 1 second:
247
248
  * go.animate(go.get_id(), "position.x", go.PLAYBACK_ONCE_FORWARD, 10, go.EASING_LINEAR, 1, 0, () => {
248
249
  * go.animate(go.get_id(), "position.y", go.PLAYBACK_ONCE_FORWARD, 20, go.EASING_LINEAR, 1);
249
250
  * });
250
- *
251
- * // Animate the y position of a game object using a crazy custom easing curve:
251
+ * ```
252
+ * @example
253
+ * Animate the y position of a game object using a crazy custom easing curve:
254
+ * ```ts
252
255
  * const values = [
253
256
  * 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
254
257
  * 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
@@ -259,7 +262,7 @@ declare global {
259
262
  * go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, vec, 2.0);
260
263
  * ```
261
264
  */
262
- export function animate(url: SceneAddress | Hash | Url, property: string | Hash, playback: number & { readonly __brand: "go.PLAYBACK_ONCE_FORWARD" } | number & { readonly __brand: "go.PLAYBACK_ONCE_BACKWARD" } | number & { readonly __brand: "go.PLAYBACK_ONCE_PINGPONG" } | number & { readonly __brand: "go.PLAYBACK_LOOP_FORWARD" } | number & { readonly __brand: "go.PLAYBACK_LOOP_BACKWARD" } | number & { readonly __brand: "go.PLAYBACK_LOOP_PINGPONG" }, to: number | Vector3 | Vector4 | Quaternion, easing: Vector | number & { readonly __brand: "go.EASING_INBACK" } | number & { readonly __brand: "go.EASING_INBOUNCE" } | number & { readonly __brand: "go.EASING_INCIRC" } | number & { readonly __brand: "go.EASING_INCUBIC" } | number & { readonly __brand: "go.EASING_INELASTIC" } | number & { readonly __brand: "go.EASING_INEXPO" } | number & { readonly __brand: "go.EASING_INOUTBACK" } | number & { readonly __brand: "go.EASING_INOUTBOUNCE" } | number & { readonly __brand: "go.EASING_INOUTCIRC" } | number & { readonly __brand: "go.EASING_INOUTCUBIC" } | number & { readonly __brand: "go.EASING_INOUTELASTIC" } | number & { readonly __brand: "go.EASING_INOUTEXPO" } | number & { readonly __brand: "go.EASING_INOUTQUAD" } | number & { readonly __brand: "go.EASING_INOUTQUART" } | number & { readonly __brand: "go.EASING_INOUTQUINT" } | number & { readonly __brand: "go.EASING_INOUTSINE" } | number & { readonly __brand: "go.EASING_INQUAD" } | number & { readonly __brand: "go.EASING_INQUART" } | number & { readonly __brand: "go.EASING_INQUINT" } | number & { readonly __brand: "go.EASING_INSINE" } | number & { readonly __brand: "go.EASING_LINEAR" } | number & { readonly __brand: "go.EASING_OUTBACK" } | number & { readonly __brand: "go.EASING_OUTBOUNCE" } | number & { readonly __brand: "go.EASING_OUTCIRC" } | number & { readonly __brand: "go.EASING_OUTCUBIC" } | number & { readonly __brand: "go.EASING_OUTELASTIC" } | number & { readonly __brand: "go.EASING_OUTEXPO" } | number & { readonly __brand: "go.EASING_OUTINBACK" } | number & { readonly __brand: "go.EASING_OUTINBOUNCE" } | number & { readonly __brand: "go.EASING_OUTINCIRC" } | number & { readonly __brand: "go.EASING_OUTINCUBIC" } | number & { readonly __brand: "go.EASING_OUTINELASTIC" } | number & { readonly __brand: "go.EASING_OUTINEXPO" } | number & { readonly __brand: "go.EASING_OUTINQUAD" } | number & { readonly __brand: "go.EASING_OUTINQUART" } | number & { readonly __brand: "go.EASING_OUTINQUINT" } | number & { readonly __brand: "go.EASING_OUTINSINE" } | number & { readonly __brand: "go.EASING_OUTQUAD" } | number & { readonly __brand: "go.EASING_OUTQUART" } | number & { readonly __brand: "go.EASING_OUTQUINT" } | number & { readonly __brand: "go.EASING_OUTSINE" }, duration: number, delay?: number, complete_function?: (self: unknown, url: unknown, property: unknown) => void): void;
265
+ export function animate(url: SceneAddress | Hash | Url, property: string | Hash, playback: go.Playback, to: number | Vector3 | Vector4 | Quaternion, easing: Vector | go.Easing, duration: number, delay?: number, complete_function?: (self: unknown, url: unknown, property: unknown) => void): void;
263
266
  /**
264
267
  * By calling this function, all or specified stored property animations of the game object or component will be canceled.
265
268
  * See the properties guide for which properties can be animated and the animation guide for how to animate them.
@@ -267,14 +270,18 @@ declare global {
267
270
  * @param url - url of the game object or component
268
271
  * @param property - optional id of the property to cancel
269
272
  * @example
273
+ * Cancel the animation of the position of a game object:
270
274
  * ```ts
271
- * // Cancel the animation of the position of a game object:
272
275
  * go.cancel_animations(go.get_id(), "position");
273
- *
274
- * // Cancel all property animations of the current game object:
276
+ * ```
277
+ * @example
278
+ * Cancel all property animations of the current game object:
279
+ * ```ts
275
280
  * go.cancel_animations(".");
276
- *
277
- * // Cancel all property animations of the sprite component of the current game object:
281
+ * ```
282
+ * @example
283
+ * Cancel all property animations of the sprite component of the current game object:
284
+ * ```ts
278
285
  * go.cancel_animations("#sprite");
279
286
  * ```
280
287
  */
@@ -290,8 +297,8 @@ declare global {
290
297
  * @param id - optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by default
291
298
  * @param recursive - optional boolean, set to true to recursively delete child hiearchy in child to parent order
292
299
  * @example
300
+ * This example demonstrates how to delete game objects
293
301
  * ```ts
294
- * // This example demonstrates how to delete game objects:
295
302
  * // Delete the script's own game object.
296
303
  * go.delete();
297
304
  * // Delete a game object with the id "my_game_object".
@@ -300,20 +307,21 @@ declare global {
300
307
  * // Delete a list of game objects.
301
308
  * const ids = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
302
309
  * go.delete(ids);
303
- *
304
- * // This example demonstrates how to delete game objects and their children
305
- * // (child-to-parent order):
310
+ * ```
311
+ * @example
312
+ * This example demonstrates how to delete a game objects and their children (child to parent order)
313
+ * ```ts
306
314
  * // Delete the script's own game object and its children.
307
315
  * go.delete(true);
308
316
  * // Delete a game object with the id "my_game_object" and its children.
309
- * const id2 = go.get_id("my_game_object");
310
- * go.delete(id2, true);
317
+ * const id = go.get_id("my_game_object");
318
+ * go.delete(id, true);
311
319
  * // Delete a list of game objects and their children.
312
- * const ids2 = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
313
- * go.delete(ids2, true);
320
+ * const ids = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
321
+ * go.delete(ids, true);
314
322
  * ```
315
323
  */
316
- function _delete(id?: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[], recursive?: boolean): void;
324
+ function _delete(id?: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | boolean, recursive?: boolean): void;
317
325
  /**
318
326
  * This function can check for game objects in any collection by specifying
319
327
  * the collection name in the URL.
@@ -321,11 +329,13 @@ declare global {
321
329
  * @param url - url of the game object to check
322
330
  * @returns true if the game object exists
323
331
  * @example
332
+ * Check if game object "my_game_object" exists in the current collection
324
333
  * ```ts
325
- * // Check if game object "my_game_object" exists in the current collection:
326
334
  * go.exists("/my_game_object");
327
- *
328
- * // Check if game object exists in another collection:
335
+ * ```
336
+ * @example
337
+ * Check if game object exists in another collection
338
+ * ```ts
329
339
  * go.exists("other_collection:/my_game_object");
330
340
  * ```
331
341
  */
@@ -339,6 +349,10 @@ declare global {
339
349
  * @example
340
350
  * ```ts
341
351
  * export default defineScript({
352
+ * init() {
353
+ * return { some_value: 0 };
354
+ * },
355
+ *
342
356
  * final(self) {
343
357
  * // report finalization
344
358
  * msg.post("my_friend_instance", "im_dead", { my_stats: self.some_value });
@@ -388,12 +402,14 @@ declare global {
388
402
  * @param id - optional id of the game object instance to get parent for, defaults to the instance containing the calling script
389
403
  * @returns parent instance or `nil`
390
404
  * @example
405
+ * Get parent of the instance containing the calling script:
391
406
  * ```ts
392
- * // Get parent of the instance containing the calling script:
393
407
  * const parent_id = go.get_parent();
394
- *
395
- * // Get parent of the instance with id "x":
396
- * const parent_id2 = go.get_parent("x");
408
+ * ```
409
+ * @example
410
+ * Get parent of the instance with id "x":
411
+ * ```ts
412
+ * const parent_id = go.get_parent("x");
397
413
  * ```
398
414
  */
399
415
  export function get_parent(id?: SceneGameObjectAddress | Hash | Url): Hash | undefined;
@@ -403,11 +419,13 @@ declare global {
403
419
  * @param id - optional id of the game object instance to get the position for, by default the instance of the calling script
404
420
  * @returns instance position
405
421
  * @example
422
+ * Get the position of the game object instance the script is attached to:
406
423
  * ```ts
407
- * // Get the position of the game object the script is attached to:
408
424
  * const p = go.get_position();
409
- *
410
- * // Get the position of another game object "my_gameobject":
425
+ * ```
426
+ * @example
427
+ * Get the position of another game object instance "my_gameobject":
428
+ * ```ts
411
429
  * const pos = go.get_position("my_gameobject");
412
430
  * ```
413
431
  */
@@ -418,12 +436,14 @@ declare global {
418
436
  * @param id - optional id of the game object instance to get the rotation for, by default the instance of the calling script
419
437
  * @returns instance rotation
420
438
  * @example
439
+ * Get the rotation of the game object instance the script is attached to:
421
440
  * ```ts
422
- * // Get the rotation of the game object the script is attached to:
423
441
  * const r = go.get_rotation();
424
- *
425
- * // Get the rotation of another game object with id "x":
426
- * const r2 = go.get_rotation("x");
442
+ * ```
443
+ * @example
444
+ * Get the rotation of another game object instance with id "x":
445
+ * ```ts
446
+ * const r = go.get_rotation("x");
427
447
  * ```
428
448
  */
429
449
  export function get_rotation(id?: SceneGameObjectAddress | Hash | Url): Quaternion;
@@ -433,12 +453,14 @@ declare global {
433
453
  * @param id - optional id of the game object instance to get the scale for, by default the instance of the calling script
434
454
  * @returns instance scale factor
435
455
  * @example
456
+ * Get the scale of the game object instance the script is attached to:
436
457
  * ```ts
437
- * // Get the scale of the game object the script is attached to:
438
458
  * const s = go.get_scale();
439
- *
440
- * // Get the scale of another game object with id "x":
441
- * const s2 = go.get_scale("x");
459
+ * ```
460
+ * @example
461
+ * Get the scale of another game object instance with id "x":
462
+ * ```ts
463
+ * const s = go.get_scale("x");
442
464
  * ```
443
465
  */
444
466
  export function get_scale(id?: SceneGameObjectAddress | Hash | Url): Vector3;
@@ -448,12 +470,14 @@ declare global {
448
470
  * @param id - optional id of the game object instance to get the uniform scale for, by default the instance of the calling script
449
471
  * @returns uniform instance scale factor
450
472
  * @example
473
+ * Get the scale of the game object instance the script is attached to:
451
474
  * ```ts
452
- * // Get the uniform scale of the game object the script is attached to:
453
475
  * const s = go.get_scale_uniform();
454
- *
455
- * // Get the uniform scale of another game object with id "x":
456
- * const s2 = go.get_scale_uniform("x");
476
+ * ```
477
+ * @example
478
+ * Get the uniform scale of another game object instance with id "x":
479
+ * ```ts
480
+ * const s = go.get_scale_uniform("x");
457
481
  * ```
458
482
  */
459
483
  export function get_scale_uniform(id?: SceneGameObjectAddress | Hash | Url): number;
@@ -465,12 +489,15 @@ declare global {
465
489
  * @param id - optional id of the game object instance to get the world position for, by default the instance of the calling script
466
490
  * @returns instance world position
467
491
  * @example
492
+ * Get the world position of the game object instance the script is attached to:
468
493
  * ```ts
469
- * // Get the world position of the game object the script is attached to:
470
494
  * const p = go.get_world_position();
471
- *
472
- * // Reach a sibling game object by its id — relative addressing, no socket prefix:
473
- * const p2 = go.get_world_position("x");
495
+ * ```
496
+ * @example
497
+ * Get the world position of another game object instance with id "x":
498
+ * ```ts
499
+ * // Relative addressing by id — no socket prefix:
500
+ * const p = go.get_world_position("x");
474
501
  * ```
475
502
  */
476
503
  export function get_world_position(id?: SceneGameObjectAddress | Hash | Url): Vector3;
@@ -482,12 +509,14 @@ declare global {
482
509
  * @param id - optional id of the game object instance to get the world rotation for, by default the instance of the calling script
483
510
  * @returns instance world rotation
484
511
  * @example
512
+ * Get the world rotation of the game object instance the script is attached to:
485
513
  * ```ts
486
- * // Get the world rotation of the game object the script is attached to:
487
514
  * const r = go.get_world_rotation();
488
- *
489
- * // Get the world rotation of another game object with id "x":
490
- * const r2 = go.get_world_rotation("x");
515
+ * ```
516
+ * @example
517
+ * Get the world rotation of another game object instance with id "x":
518
+ * ```ts
519
+ * const r = go.get_world_rotation("x");
491
520
  * ```
492
521
  */
493
522
  export function get_world_rotation(id?: SceneGameObjectAddress | Hash | Url): Quaternion;
@@ -501,12 +530,14 @@ declare global {
501
530
  * @param id - optional id of the game object instance to get the world scale for, by default the instance of the calling script
502
531
  * @returns instance world 3D scale factor
503
532
  * @example
533
+ * Get the world 3D scale of the game object instance the script is attached to:
504
534
  * ```ts
505
- * // Get the world 3D scale of the game object the script is attached to:
506
535
  * const s = go.get_world_scale();
507
- *
508
- * // Get the world scale of another game object "x":
509
- * const s2 = go.get_world_scale("x");
536
+ * ```
537
+ * @example
538
+ * Get the world scale of another game object instance "x":
539
+ * ```ts
540
+ * const s = go.get_world_scale("x");
510
541
  * ```
511
542
  */
512
543
  export function get_world_scale(id?: SceneGameObjectAddress | Hash | Url): Vector3;
@@ -518,12 +549,14 @@ declare global {
518
549
  * @param id - optional id of the game object instance to get the world scale for, by default the instance of the calling script
519
550
  * @returns instance world scale factor
520
551
  * @example
552
+ * Get the world scale of the game object instance the script is attached to:
521
553
  * ```ts
522
- * // Get the world uniform scale of the game object the script is attached to:
523
554
  * const s = go.get_world_scale_uniform();
524
- *
525
- * // Get the world uniform scale of another game object with id "x":
526
- * const s2 = go.get_world_scale_uniform("x");
555
+ * ```
556
+ * @example
557
+ * Get the world scale of another game object instance with id "x":
558
+ * ```ts
559
+ * const s = go.get_world_scale_uniform("x");
527
560
  * ```
528
561
  */
529
562
  export function get_world_scale_uniform(id?: SceneGameObjectAddress | Hash | Url): number;
@@ -534,12 +567,14 @@ declare global {
534
567
  * @param id - optional id of the game object instance to get the world transform for, by default the instance of the calling script
535
568
  * @returns instance world transform
536
569
  * @example
570
+ * Get the world transform of the game object instance the script is attached to:
537
571
  * ```ts
538
- * // Get the world transform of the game object the script is attached to:
539
572
  * const m = go.get_world_transform();
540
- *
541
- * // Get the world transform of another game object with id "x":
542
- * const m2 = go.get_world_transform("x");
573
+ * ```
574
+ * @example
575
+ * Get the world transform of another game object instance with id "x":
576
+ * ```ts
577
+ * const m = go.get_world_transform("x");
543
578
  * ```
544
579
  */
545
580
  export function get_world_transform(id?: SceneGameObjectAddress | Hash | Url): Matrix4;
@@ -760,7 +795,7 @@ declare global {
760
795
  * self.velocity = vmath.vector3();
761
796
  * } else {
762
797
  * // update velocity
763
- * self.velocity = vmath.vector3(action.value * self.max_speed, 0, 0);
798
+ * self.velocity = vmath.vector3((action.value ?? 0) * self.max_speed, 0, 0);
764
799
  * }
765
800
  * }
766
801
  * },
@@ -779,6 +814,9 @@ declare global {
779
814
  * @param message - a table containing the message data
780
815
  * @param sender - address of the sender
781
816
  * @example
817
+ * This example demonstrates how a game object instance, called "a", can communicate with another instance, called "b". It
818
+ * is assumed that both script components of the instances has id "script".
819
+ * Script of instance "a":
782
820
  * ```ts
783
821
  * // This example demonstrates how a game object instance, called "a", can communicate with another instance, called "b". It
784
822
  * // is assumed that both script components of the instances has id "script".
@@ -790,18 +828,21 @@ declare global {
790
828
  * msg.post("b#script", "my_data", { important_value: 1 });
791
829
  * },
792
830
  * });
793
- *
831
+ * ```
832
+ * @example
833
+ * Script of instance "b":
834
+ * ```ts
794
835
  * // b.script — Script of instance "b":
795
836
  * export default defineScript({
796
837
  * init() {
797
838
  * // store the url of instance "a" for later use, by specifying undefined as socket we
798
839
  * // automatically use our own socket
799
- * return { a_url: msg.url(undefined, go.get_id("a"), "script") };
840
+ * return { a_url: msg.url(undefined, go.get_id("a"), "script"), important_value: 0 };
800
841
  * },
801
842
  *
802
843
  * on_message(self, message_id, message, sender) {
803
844
  * // check message and sender
804
- * if (message_id === hash("my_data") && sender === self.a_url) {
845
+ * if (message_id === hash("my_data") && sender === self.a_url && typeof message.important_value === "number") {
805
846
  * // use the data in some way
806
847
  * self.important_value = message.important_value;
807
848
  * }
@@ -843,7 +884,7 @@ declare global {
843
884
  * self.velocity = vmath.vector3();
844
885
  * } else {
845
886
  * // update velocity
846
- * self.velocity = vmath.vector3(action.value * self.max_speed, 0, 0);
887
+ * self.velocity = vmath.vector3((action.value ?? 0) * self.max_speed, 0, 0);
847
888
  * }
848
889
  * }
849
890
  * },
@@ -868,14 +909,18 @@ declare global {
868
909
  * @param parent_id - optional id of the new parent game object, defaults to detaching game object from its parent
869
910
  * @param keep_world_transform - optional boolean, set to true to maintain the world transform when changing spaces. Defaults to false.
870
911
  * @example
912
+ * Attach myself to another instance "my_parent":
871
913
  * ```ts
872
- * // Attach myself to another instance "my_parent":
873
914
  * go.set_parent(go.get_id(), go.get_id("my_parent"));
874
- *
875
- * // Attach an instance "my_instance" to another instance "my_parent":
915
+ * ```
916
+ * @example
917
+ * Attach an instance "my_instance" to another instance "my_parent":
918
+ * ```ts
876
919
  * go.set_parent(go.get_id("my_instance"), go.get_id("my_parent"));
877
- *
878
- * // Detach an instance "my_instance" from its parent (if any):
920
+ * ```
921
+ * @example
922
+ * Detach an instance "my_instance" from its parent (if any):
923
+ * ```ts
879
924
  * go.set_parent(go.get_id("my_instance"));
880
925
  * ```
881
926
  */
@@ -886,14 +931,19 @@ declare global {
886
931
  * @param position - position to set
887
932
  * @param id - optional id of the game object instance to set the position for, by default the instance of the calling script
888
933
  * @example
934
+ * Set the position of the game object instance the script is attached to:
889
935
  * ```ts
890
936
  * // `p` is the desired position (a Vector3).
891
937
  * const p = vmath.vector3();
892
- *
893
- * // Set the position of the game object the script is attached to:
894
938
  * go.set_position(p);
939
+ * ```
940
+ * @example
941
+ * Set the position of another game object instance with id "x":
942
+ * ```ts
943
+ * // `p` is the desired position (a Vector3).
944
+ * const p = vmath.vector3();
895
945
  *
896
- * // Reach a sibling game object by its id — relative addressing, no socket prefix:
946
+ * // Relative addressing by id — no socket prefix:
897
947
  * go.set_position(p, "x");
898
948
  * ```
899
949
  */
@@ -904,14 +954,17 @@ declare global {
904
954
  * @param rotation - rotation to set
905
955
  * @param id - optional id of the game object instance to get the rotation for, by default the instance of the calling script
906
956
  * @example
957
+ * Set the rotation of the game object instance the script is attached to:
907
958
  * ```ts
908
959
  * // `r` is the desired rotation (a Quaternion).
909
960
  * const r = vmath.quat();
910
- *
911
- * // Set the rotation of the game object the script is attached to:
912
961
  * go.set_rotation(r);
913
- *
914
- * // Set the rotation of another game object with id "x":
962
+ * ```
963
+ * @example
964
+ * Set the rotation of another game object instance with id "x":
965
+ * ```ts
966
+ * // `r` is the desired rotation (a Quaternion).
967
+ * const r = vmath.quat();
915
968
  * go.set_rotation(r, "x");
916
969
  * ```
917
970
  */
@@ -923,14 +976,16 @@ declare global {
923
976
  * @param scale - vector or uniform scale factor, must be greater than 0
924
977
  * @param id - optional id of the game object instance to get the scale for, by default the instance of the calling script
925
978
  * @example
979
+ * Set the scale of the game object instance the script is attached to:
926
980
  * ```ts
927
- * // Set the scale of the game object the script is attached to:
928
981
  * const s = vmath.vector3(2.0, 1.0, 1.0);
929
982
  * go.set_scale(s);
930
- *
931
- * // Set the scale of another game object with id "obj_id":
932
- * const s2 = 1.2;
933
- * go.set_scale(s2, "obj_id");
983
+ * ```
984
+ * @example
985
+ * Set the scale of another game object instance with id "obj_id":
986
+ * ```ts
987
+ * const s = 1.2;
988
+ * go.set_scale(s, "obj_id");
934
989
  * ```
935
990
  */
936
991
  export function set_scale(scale: number | Vector3, id?: SceneGameObjectAddress | Hash | Url): void;
@@ -941,14 +996,16 @@ declare global {
941
996
  * @param scale - vector or uniform scale factor, must be greater than 0
942
997
  * @param id - optional id of the game object instance to get the scale for, by default the instance of the calling script
943
998
  * @example
999
+ * Set the scale of the game object instance the script is attached to:
944
1000
  * ```ts
945
- * // Set the scale of the game object the script is attached to:
946
1001
  * const s = vmath.vector3(2.0, 1.0, 5.0);
947
1002
  * go.set_scale_xy(s); // z will not be set here, only x and y
948
- *
949
- * // Set the scale of another game object with id "obj_id":
950
- * const s2 = 1.2;
951
- * go.set_scale_xy(s2, "obj_id"); // z will not be set here, only x and y
1003
+ * ```
1004
+ * @example
1005
+ * Set the scale of another game object instance with id "obj_id":
1006
+ * ```ts
1007
+ * const s = 1.2;
1008
+ * go.set_scale_xy(s, "obj_id"); // z will not be set here, only x and y
952
1009
  * ```
953
1010
  */
954
1011
  export function set_scale_xy(scale: number | Vector3, id?: SceneGameObjectAddress | Hash | Url): void;
@@ -986,11 +1043,13 @@ declare global {
986
1043
  *
987
1044
  * @param id - optional id of the game object instance to update
988
1045
  * @example
1046
+ * Update this game object's world transform:
989
1047
  * ```ts
990
- * // Update this game object's world transform:
991
1048
  * go.update_world_transform();
992
- *
993
- * // Update another game object's world transform:
1049
+ * ```
1050
+ * @example
1051
+ * Update another game object's world transform:
1052
+ * ```ts
994
1053
  * go.update_world_transform("/other");
995
1054
  * ```
996
1055
  */
@@ -4,6 +4,8 @@ declare global {
4
4
  * Graphics functions and constants.
5
5
  */
6
6
  namespace graphics {
7
+ type BufferType = typeof graphics.BUFFER_TYPE_COLOR0_BIT | typeof graphics.BUFFER_TYPE_COLOR1_BIT | typeof graphics.BUFFER_TYPE_COLOR2_BIT | typeof graphics.BUFFER_TYPE_COLOR3_BIT | typeof graphics.BUFFER_TYPE_DEPTH_BIT | typeof graphics.BUFFER_TYPE_STENCIL_BIT;
8
+ type State = typeof graphics.STATE_DEPTH_TEST | typeof graphics.STATE_STENCIL_TEST | typeof graphics.STATE_BLEND | typeof graphics.STATE_ALPHA_TEST | typeof graphics.STATE_CULL_FACE | typeof graphics.STATE_POLYGON_OFFSET_FILL;
7
9
  const BLEND_EQUATION_ADD: number & { readonly __brand: "graphics.BLEND_EQUATION_ADD" };
8
10
  const BLEND_EQUATION_MAX: number & { readonly __brand: "graphics.BLEND_EQUATION_MAX" };
9
11
  const BLEND_EQUATION_MIN: number & { readonly __brand: "graphics.BLEND_EQUATION_MIN" };
@@ -93,6 +95,58 @@ declare global {
93
95
  const FACE_TYPE_BACK: number & { readonly __brand: "graphics.FACE_TYPE_BACK" };
94
96
  const FACE_TYPE_FRONT: number & { readonly __brand: "graphics.FACE_TYPE_FRONT" };
95
97
  const FACE_TYPE_FRONT_AND_BACK: number & { readonly __brand: "graphics.FACE_TYPE_FRONT_AND_BACK" };
98
+ /**
99
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
100
+ */
101
+ const SEMANTIC_TYPE_BONE_INDICES: number & { readonly __brand: "graphics.SEMANTIC_TYPE_BONE_INDICES" };
102
+ /**
103
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
104
+ */
105
+ const SEMANTIC_TYPE_BONE_WEIGHTS: number & { readonly __brand: "graphics.SEMANTIC_TYPE_BONE_WEIGHTS" };
106
+ /**
107
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
108
+ */
109
+ const SEMANTIC_TYPE_COLOR: number & { readonly __brand: "graphics.SEMANTIC_TYPE_COLOR" };
110
+ /**
111
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
112
+ */
113
+ const SEMANTIC_TYPE_MORPH_TARGET_WEIGHTS: number & { readonly __brand: "graphics.SEMANTIC_TYPE_MORPH_TARGET_WEIGHTS" };
114
+ /**
115
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
116
+ */
117
+ const SEMANTIC_TYPE_NONE: number & { readonly __brand: "graphics.SEMANTIC_TYPE_NONE" };
118
+ /**
119
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
120
+ */
121
+ const SEMANTIC_TYPE_NORMAL: number & { readonly __brand: "graphics.SEMANTIC_TYPE_NORMAL" };
122
+ /**
123
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
124
+ */
125
+ const SEMANTIC_TYPE_NORMAL_MATRIX: number & { readonly __brand: "graphics.SEMANTIC_TYPE_NORMAL_MATRIX" };
126
+ /**
127
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
128
+ */
129
+ const SEMANTIC_TYPE_PAGE_INDEX: number & { readonly __brand: "graphics.SEMANTIC_TYPE_PAGE_INDEX" };
130
+ /**
131
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
132
+ */
133
+ const SEMANTIC_TYPE_POSITION: number & { readonly __brand: "graphics.SEMANTIC_TYPE_POSITION" };
134
+ /**
135
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
136
+ */
137
+ const SEMANTIC_TYPE_TANGENT: number & { readonly __brand: "graphics.SEMANTIC_TYPE_TANGENT" };
138
+ /**
139
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
140
+ */
141
+ const SEMANTIC_TYPE_TEXCOORD: number & { readonly __brand: "graphics.SEMANTIC_TYPE_TEXCOORD" };
142
+ /**
143
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
144
+ */
145
+ const SEMANTIC_TYPE_TEXTURE_TRANSFORM_2D: number & { readonly __brand: "graphics.SEMANTIC_TYPE_TEXTURE_TRANSFORM_2D" };
146
+ /**
147
+ * Vertex attribute semantic type, for `material.set_vertex_attributes`.
148
+ */
149
+ const SEMANTIC_TYPE_WORLD_MATRIX: number & { readonly __brand: "graphics.SEMANTIC_TYPE_WORLD_MATRIX" };
96
150
  const STATE_ALPHA_TEST: number & { readonly __brand: "graphics.STATE_ALPHA_TEST" };
97
151
  const STATE_ALPHA_TEST_SUPPORTED: number & { readonly __brand: "graphics.STATE_ALPHA_TEST_SUPPORTED" };
98
152
  const STATE_BLEND: number & { readonly __brand: "graphics.STATE_BLEND" };