Merge branch 'main' into animation

doc/en/block-properties.md

@@ -1,6 +1,6 @@
 # Block properties
 
-## Visual
+## Visual & Audio
 
 ### *texture*
 
@@ -70,6 +70,18 @@ Rotation profile (set of available block rotations and behaviour of placing bloc
 - "pane" - panels, doors, signs
 - "stairs" - "pane" + flipped variants
 
+### *particles*
+
+Particles are specified as a JSON object. Property names can be found [in the particles section](particles.md).
+
+When camera is near to the block, the engine will create an emitter that will run
+until the block is destroyed or the camera moves away a certain distance.
+
+### Material - *material*
+
+Defines the name of the block's material in the format `pack:material_name`, which affects the selection of block interaction sounds.
+Material definitions are located in /block_materials.
+
 ## Variants
 
 Some properties can vary dynamically, depending on the variant number stored in the user bits of the block.

doc/en/rigging.md

@@ -38,7 +38,7 @@ Models are loaded automatically; adding them to preload.json is not required.
 
 ## Models
 
-Models should be located in the models folder. Currently only OBJ format is supported.
+Models must be located in the models folder. Currently, the following formats are supported: obj, vec3, and [vcm](vcm.md).
 
 >[!IMPORTANT]
 > When loading an obj model, the \*.mtl file is ignored.

doc/en/scripting.md

@@ -16,6 +16,7 @@ Subsections:
     - [block](scripting/builtins/libblock.md)
     - [byteutil](scripting/builtins/libbyteutil.md)
     - [cameras](scripting/builtins/libcameras.md)
+    - [ctypes](scripting/builtins/libctypes.md)
     - [entities](scripting/builtins/libentities.md)
     - [file](scripting/builtins/libfile.md)
     - [gfx.blockwraps](scripting/builtins/libgfx-blockwraps.md)

doc/en/scripting/builtins/libapp.md

@@ -180,14 +180,34 @@ app.get_content_sources() -> table<string>
 
 Returns a list of content sources (paths), in descending priority order.
 
-``lua
+```lua
 app.set_content_sources(sources: table<string>)
 ```
 
 Sets a list of content sources (paths). Specified in descending priority order.
 
-``lua
+```lua
 app.reset_content_sources()
 ```
 
 Resets content sources.
+
+## Sub-instances
+
+```lua
+-- Creates a headless engine instance with the current project and the specified application script.
+-- Returns the instance ID. The number of active sub-instances is currently limited to one.
+app.start_background_instance(
+    -- script file
+    app_script: string,
+    -- log file
+    output_file: string | nil
+) -> int
+
+-- Checks if the engine sub-instance is alive.
+app.is_instance_alive(handle: int) -> boolean
+
+-- Stops the engine sub-instance.
+-- Returns true if the instance was alive at the time of the call.
+app.terminate(handle: int) -> boolean
+```

doc/en/scripting/builtins/libblock.md

@@ -28,7 +28,8 @@ block.get(x: int, y: int, z: int) -> int
 block.get_states(x: int, y: int, z: int) -> int
 
 -- Set block with given integer ID and state (default - 0) at given position.
-block.set(x: int, y: int, z: int, id: int, states: int)
+-- If noupdate=true is passed, the `on_update` event will not be called for adjacent blocks.
+block.set(x: int, y: int, z: int, id: int, states: int, noupdate: boolean=false)
 
 -- Places a block with a given integer id and state (default - 0) at given position.
 -- on behalf of the player, calling the on_placed event.

doc/en/scripting/builtins/libctypes.md

@@ -0,0 +1,28 @@
+# *ctypes* Library
+
+A library for safe work with C types.
+
+| ctypes.\<name\> | C-Type   | Minimum              | Maximum              |
+| --------------- | -------- | -------------------- | -------------------- |
+| uint8           | uint8_t  | 0                    | 255                  |
+| uint16          | uint16_t | 0                    | 65535                |
+| uint32          | uint32_t | 0                    | 4294967295           |
+| uint64          | uint64_t | 0                    | 18446744073709551615 |
+| int8            | int8_t   | -128                 | 127                  |
+| int16           | int16_t  | -32768               | 32767                |
+| int32           | int32_t  | -2147483648          | 2147483647           |
+| int64           | int64_t  | -9223372036854775808 | 9223372036854775807  |
+
+
+Usage examples:
+
+```lua
+local x = ctypes.uint64(1234)
+print(x) --> 1234ULL (cdata)
+local y = ctypes.uint64("18446744073709551615")
+print(y) --> 18446744073709551615ULL (cdata)
+print(x + y) --> 1233ULL
+
+local z = tonumber(x)
+print(z) --> 1234 (number)
+```