@ts-defold/types 1.2.75 → 1.2.77

package/index.d.ts

@@ -3,35 +3,8 @@
 /// <reference types="lua-types/5.1" />
 /// <reference types="lua-types/special/jit-only" />
 
-// DEFOLD. stable version 1.11.2 (a6d86c0083f00ee6c3709478ff3b33deff5e6d19)
+// DEFOLD. stable version 1.12.0 (3206f699aaff89f357c9d549050b8453e080c5d2)
 
-/**
- * All ids in the engine are represented as hashes, so a string needs to be hashed
-before it can be compared with an id.
- * @param s string to hash
- * @returns a hashed string
- * @example To compare a message_id in an on-message callback function:
-```lua
-function on_message(self, message_id, message, sender)
-    if message_id == hash("my_message") then
-        -- Act on the message here
-    end
-end
-```
- */
-declare function hash(s: string): hash;
-/**
- * Returns a hexadecimal representation of a hash value.
-The returned string is always padded with leading zeros.
- * @param h hash value to get hex string for
- * @returns hex representation of the hash
- * @example ```lua
-local h = hash("my_hash")
-local hexstr = hash_to_hex(h)
-print(hexstr) --> a2bc06d97f580aab
-```
- */
-declare function hash_to_hex(h: hash): string;
 /**
  * Pretty printing of Lua values. This function prints Lua values
 in a manner similar to +print()+, but will also recurse into tables
@@ -61,6 +34,33 @@ Lua tables is undefined):
 ```
  */
 declare function pprint(...v: any[]): void;
+/**
+ * All ids in the engine are represented as hashes, so a string needs to be hashed
+before it can be compared with an id.
+ * @param s string to hash
+ * @returns a hashed string
+ * @example To compare a message_id in an on-message callback function:
+```lua
+function on_message(self, message_id, message, sender)
+    if message_id == hash("my_message") then
+        -- Act on the message here
+    end
+end
+```
+ */
+declare function hash(s: string): hash;
+/**
+ * Returns a hexadecimal representation of a hash value.
+The returned string is always padded with leading zeros.
+ * @param h hash value to get hex string for
+ * @returns hex representation of the hash
+ * @example ```lua
+local h = hash("my_hash")
+local hexstr = hash_to_hex(h)
+print(hexstr) --> a2bc06d97f580aab
+```
+ */
+declare function hash_to_hex(h: hash): string;
 /**
  * A unique identifier used to reference resources, messages, properties, and other entities within the game.
  */
@@ -83,6 +83,33 @@ declare type buffer = object;
 declare type bufferstream = LuaUserdata & number[] & object;
 
 
+declare namespace missingName {
+/**
+ * Enables engine throttling.
+ * @param enable true if throttling should be enabled
+ * @param cooldown the time period to do update + render for (seconds)
+ * @example Disable throttling
+```lua
+sys.set_engine_throttle(false)
+```
+
+Enable throttling
+```lua
+sys.set_engine_throttle(true, 1.5)
+```
+ */
+export function set_engine_throttle(enable: boolean, cooldown: number): void;
+/**
+ * Disables rendering
+ * @param enable true if throttling should be enabled
+ * @example Disable rendering
+```lua
+sys.set_render_enable(false)
+```
+ */
+export function set_render_enable(enable: boolean): void;
+}
+
 declare namespace b2d {
 /**
  * Get the Box2D body from a collision object
@@ -637,6 +664,48 @@ export function get_projection(camera: url | number | undefined): vmath.matrix4;
  * @returns the view matrix.
  */
 export function get_view(camera: url | number | undefined): vmath.matrix4;
+/**
+ * Converts a screen-space 2D point with view depth to a 3D world point.
+z is the view depth in world units measured from the camera plane along the camera forward axis.
+If a camera isn't specified, the last enabled camera is used.
+ * @param pos Screen-space position (x, y) with z as view depth in world units
+ * @param camera optional camera id
+ * @returns the world coordinate
+ * @example Place objects at the touch point with a random Z position, keeping them within the visible view zone.
+```lua
+ function on_input(self, action_id, action)
+     if action_id == hash("touch") then
+         if action.pressed then
+             local percpective_camera = msg.url("#perspective_camera")
+             local random_z = math.random(camera.get_near_z(percpective_camera) + 0.01, camera.get_far_z(percpective_camera) - 0.01)
+             local world_position = camera.screen_to_world(vmath.vector3(action.screen_x, action.screen_y, random_z), percpective_camera)
+             go.set_position(world_position, "/go1")
+         end
+     end
+ end
+```
+ */
+export function screen_to_world(pos: vmath.vector3, camera?: url | number | undefined): vmath.vector3;
+/**
+ * Converts 2D screen coordinates (x,y) to the 3D world-space point on the camera's near plane for that pixel.
+If a camera isn't specified, the last enabled camera is used.
+ * @param x X coordinate on screen.
+ * @param y Y coordinate on screen.
+ * @param camera optional camera id
+ * @returns the world coordinate on the camera near plane
+ * @example Place objects at the touch point.
+```lua
+ function on_input(self, action_id, action)
+     if action_id == hash("touch") then
+         if action.pressed then
+             local world_position = camera.screen_xy_to_world(action.screen_x, action.screen_y)
+             go.set_position(world_position, "/go1")
+         end
+     end
+ end
+```
+ */
+export function screen_xy_to_world(x: number, y: number, camera?: url | number | undefined): vmath.vector3;
 /**
  * Sets the manual aspect ratio for the camera. This value is only used when
 auto aspect ratio is disabled. To disable auto aspect ratio and use this
@@ -683,6 +752,23 @@ export function set_orthographic_mode(camera: url | number | undefined, mode: nu
  * @param orthographic_zoom the zoom level when the camera uses orthographic projection.
  */
 export function set_orthographic_zoom(camera: url | number | undefined, orthographic_zoom: number): void;
+/**
+ * Converts a 3D world position to screen-space coordinates with view depth.
+Returns a vector3 where x and y are in screen pixels and z is the view depth in world units
+measured from the camera plane along the camera forward axis. The returned z can be used with
+camera.screen_to_world to reconstruct the world position on the same pixel ray.
+If a camera isn't specified, the last enabled camera is used.
+ * @param world_pos World-space position
+ * @param camera optional camera id
+ * @returns Screen position (x,y in pixels, z is view depth)
+ * @example Convert go position into screen pisition
+```lua
+ go.update_world_transform("/go1")
+ local world_pos = go.get_world_position("/go1")
+ local screen_pos = camera.world_to_screen(world_pos)
+```
+ */
+export function world_to_screen(world_pos: vmath.vector3, camera?: url | number | undefined): vmath.vector3;
 }
 
 declare namespace collectionfactory {
@@ -1133,9 +1219,25 @@ export function unload(url?: string | hash | url): void;
 
 declare namespace font {
 /**
- * Asynchronoously adds more glyphs to a .fontc resource
- * @param path The path to the .fontc resource
- * @param text A string with unique unicode characters to be loaded
+ * associates a ttf resource to a .fontc file.
+ * @param fontc The path to the .fontc resource
+ * @param ttf The path to the .ttf resource
+ * @example ```lua
+local font_hash = hash("/assets/fonts/roboto.fontc")
+local ttf_hash = hash("/assets/fonts/Roboto/Roboto-Bold.ttf")
+font.add_font(font_hash, ttf_hash)
+```
+ */
+export function add_font(fontc: string | hash, ttf: string | hash): void;
+/**
+ * Gets information about a font, such as the associated font files
+ * @param fontc The path to the .fontc resource
+ */
+export function get_info(fontc: string | hash): { path: hash, fonts: { path: string, path_hash: hash }[] };
+/**
+ * prepopulates the font glyph cache with rasterised glyphs
+ * @param fontc The path to the .fontc resource
+ * @param text The text to layout
  * @param callback (optional) A callback function that is called after the request is finished
 
 `self`
@@ -1149,26 +1251,24 @@ string `nil` if the request was successful
 
  * @returns Returns the asynchronous request id
  * @example ```lua
--- Add glyphs
-local requestid = font.add_glyphs("/path/to/my.fontc", "abcABC123", function (self, request, result, errstring)
-        -- make a note that all the glyphs are loaded
-        -- and we're ready to present the text
-        self.dialog_text_ready = true
+local font_hash = hash("/assets/fonts/roboto.fontc")
+font.prewarm_text(font_hash, "Some text", function (self, request_id, result, errstring)
+        -- cache is warm, show the text!
     end)
-```
-
-```lua
--- Remove glyphs
-local requestid = font.remove_glyphs("/path/to/my.fontc", "abcABC123")
 ```
  */
-export function add_glyphs(path: string | hash, text: string, callback?: ((this: any, request_id: any, result: any, errstring: any) => void)): number;
+export function prewarm_text(fontc: string | hash, text: string, callback?: ((this: any, request_id: any, result: any, errstring: any) => void)): number;
 /**
- * Removes glyphs from the font
- * @param path The path to the .fontc resource
- * @param text A string with unique unicode characters to be removed
+ * associates a ttf resource to a .fontc file
+ * @param fontc The path to the .fontc resource
+ * @param ttf The path to the .ttf resource
+ * @example ```lua
+local font_hash = hash("/assets/fonts/roboto.fontc")
+local ttf_hash = hash("/assets/fonts/Roboto/Roboto-Bold.ttf")
+font.remove_font(font_hash, ttf_hash)
+```
  */
-export function remove_glyphs(path: string | hash, text: string): void;
+export function remove_font(fontc: string | hash, ttf: string | hash): void;
 }
 
 declare namespace go {
@@ -3718,6 +3818,7 @@ export function new_text_node(pos: vmath.vector3 | vmath.vector4, text: string):
 `"rgb"` - RGB
 `"rgba"` - RGBA
 `"l"` - LUMINANCE
+`"astc"` - ASTC compressed format
 
  * @param buffer texture data
  * @param flip flip texture vertically
@@ -3746,6 +3847,16 @@ function init(self)
          end
      end
 end
+```How to create a texture using .astc format
+
+```lua
+local path = "/assets/images/logo_4x4.astc"
+local buffer = sys.load_resource(path)
+local n = gui.new_box_node(pos, vmath.vector3(size, size, 0))
+-- size is read from the .astc buffer
+-- flip is not supported
+gui.new_texture(path, 0, 0, "astc", buffer, false)
+gui.set_texture(n, path)
 ```
  */
 export function new_texture(texture_id: string | hash, width: number, height: number, type: string | number, buffer: string, flip: boolean): LuaMultiReturn<[boolean, number]>;
@@ -4554,6 +4665,7 @@ export function set_texture(node: node, texture: string | hash): void;
   `"rgb"` - RGB
   `"rgba"` - RGBA
   `"l"` - LUMINANCE
+  `"astc"` - ASTC compressed format
 
  * @param buffer texture data
  * @param flip flip texture vertically
@@ -4808,6 +4920,24 @@ export const TYPE_RGB: number;
  * RGBA image type
  */
 export const TYPE_RGBA: number;
+/**
+ * get the header of an .astc buffer
+ * @param buffer .astc file data buffer
+ * @example How to get the block size and dimensions from a .astc file
+```lua
+local s = sys.load_resource("/assets/cat.astc")
+local header = image.get_astc_header(s)
+pprint(s)
+```
+ */
+export function get_astc_header(buffer: string): {
+						width: number;
+						height: number;
+						depth: number;
+						block_size_x: number;
+						block_size_y: number;
+						block_size_z: number;
+					} | undefined;
 /**
  * Load image (PNG or JPEG) from buffer.
  * @param buffer image data buffer
@@ -9909,7 +10039,7 @@ export const REQUEST_STATUS_ERROR_NOT_FOUND: number;
  */
 export const REQUEST_STATUS_FINISHED: number;
 /**
- * deserializes buffer into a lua table
+ * This function will raise a Lua error if an error occurs while deserializing the buffer.
  * @param buffer buffer to deserialize from
  * @example Deserialize a lua table that was previously serialized:
 ```lua
@@ -9981,6 +10111,7 @@ end
 export function get_application_info(app_string: string): {installed: boolean};
 /**
  * The path from which the application is run.
+This function will raise a Lua error if unable to get the application support path.
  * @returns path to application executable
  * @example Find a path where we can store data (the example path is on the macOS platform):
 ```lua
@@ -10005,6 +10136,17 @@ print(application_path) --> http://www.foobar.com/my_game
 ```
  */
 export function get_application_path(): string;
+/**
+ * Get boolean config value from the game.project configuration file with optional default value
+ * @param key key to get value for. The syntax is SECTION.KEY
+ * @param default_value (optional) default value to return if the value does not exist
+ * @returns config value as a boolean. default_value if the config key does not exist. false if no default value was supplied.
+ * @example Get user config value
+```lua
+local vsync = sys.get_config_boolean("display.vsync", false)
+```
+ */
+export function get_config_boolean(key: string, default_value?: boolean): boolean;
 /**
  * Get integer config value from the game.project configuration file with optional default value
  * @param key key to get value for. The syntax is SECTION.KEY
@@ -10118,6 +10260,7 @@ end
 export function get_ifaddrs(): { name: string, address: string | undefined, mac: string | undefined, up: boolean, running: boolean }[];
 /**
  * The save-file path is operating system specific and is typically located under the user's home directory.
+This function will raise a Lua error if unable to get the save file path.
  * @param application_id user defined id of the application, which helps define the location of the save-file
  * @param file_name file-name to get path for
  * @returns path to save-file
@@ -10161,6 +10304,7 @@ end
 export function get_sys_info(options?: { ignore_secure: boolean }): {device_model?: string, manufacturer?: string, system_name: string, system_version: string, api_version: string, language: string, device_language: string, territory: string, gmt_offset: number, device_ident?: string, user_agent?: string};
 /**
  * If the file exists, it must have been created by `sys.save` to be loaded.
+This function will raise a Lua error if an error occurs while loading the file.
  * @param filename file to read from
  * @example Load data that was previously saved, e.g. an earlier game session:
 ```lua
@@ -10335,23 +10479,22 @@ Additionally, the total number of rows that any one table may contain is limited
 (i.e. a 16 bit range). When tables are used to represent arrays, the values of
 keys are permitted to fall within a 32 bit range, supporting sparse arrays, however
 the limit on the total number of rows remains in effect.
+This function will raise a Lua error if an error occurs while saving the table.
  * @param filename file to write to
  * @param table lua table to save
- * @returns a boolean indicating if the table could be saved or not
  * @example Save data:
 ```lua
 local my_table = {}
 table.insert(my_table, "my_value")
 local my_file_path = sys.get_save_file("my_game", "my_file")
-if not sys.save(my_file_path, my_table) then
-  -- Alert user that the data could not be saved
-end
+sys.save(my_file_path, my_table)
 ```
  */
-export function save(filename: string, table: object): boolean;
+export function save(filename: string, table: object): void;
 /**
  * The buffer can later deserialized by `sys.deserialize`.
-This method has all the same limitations as `sys.save`.
+This function has all the same limitations as `sys.save`.
+This function will raise a Lua error if an error occurs while serializing the table.
  * @param table lua table to serialize
  * @returns serialized data buffer
  * @example Serialize table:
@@ -11600,22 +11743,22 @@ export type matrix4 = number & {
 		c1: vmath.vector4;
 		c2: vmath.vector4;
 		c3: vmath.vector4;
+		m00: number;
 		m01: number;
 		m02: number;
 		m03: number;
-		m04: number;
+		m10: number;
 		m11: number;
 		m12: number;
 		m13: number;
-		m14: number;
+		m20: number;
 		m21: number;
 		m22: number;
 		m23: number;
-		m24: number;
+		m30: number;
 		m31: number;
 		m32: number;
 		m33: number;
-		m34: number;
 	};
 export function mul_per_elem(v1: vmath.vector3, v2: vmath.vector3): vmath.vector3;
 export function mul_per_elem(v1: vmath.vector4, v2: vmath.vector4): vmath.vector4;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-defold/types",
-  "version": "1.2.75",
+  "version": "1.2.77",
   "description": "TypeScript definitions for Defold",
   "repository": "github:ts-defold/types",
   "keywords": [