Merge branch 'MihailRis:main' into main

doc/en/block-properties.md

@@ -241,6 +241,15 @@ Number of block inventory slots. Default - 0 (no inventory).
 
 Array of three integers. Default value is `[1, 1, 1]`.
 
+### *grounding-behaviour*
+
+Defines the behavior of the extended grounded block. Available behavior options:
+
+- "partial" - at least one segment must be grounded (default)
+- "complete" - all segments must be grounded
+- "origin" - origin segment must be grounded
+
+
 ## Block fields
 
 Block fields allow you to write more data unique to a specified voxel than the user bits allow.

doc/en/main-page.md

@@ -21,5 +21,6 @@ Documentation for 0.31.
 - [Rigging](rigging.md)
 - [Scripting](scripting.md)
 - [Text styles](text-styles.md)
+- [VCM models format](vcm.md)
 - [World generator engine](world-generator.md)
 - [XML UI building](xml-ui-layouts.md)

doc/en/scripting/builtins/libblock.md

@@ -67,7 +67,7 @@ block.get_picking_item(id: int) -> int
 block.get_variant(x: int, y: int, z: int) -> int
 
 -- Sets the block variant by index
-block.set_variant(x: int, y: int, z: int, index: int) -> int
+block.set_variant(x: int, y: int, z: int, index: int)
 
 -- Checks if an block has specified tag
 block.has_tag(id: int, tag: str) -> bool

doc/en/vcm.md

@@ -0,0 +1,101 @@
+# VCM
+
+A text format for describing 3D models, replacing the deprecated `model-primitives` property.
+
+Syntax:
+
+```
+@primitive attribute (value1, value2,...) attribute2 "value3" {
+    @inner_primitive ...
+}
+```
+
+Same structure in XML:
+
+```xml
+<primitive attribute="value1, value2,..." attribute2="value3">
+    <inner_primitive .../>
+</primitive>
+```
+
+Unlike XML, the root can contain multiple elements.
+
+Currently, there are three types of primitives: `tri`, `box`, `rect` and `part` (describes a part of a primitive, such as the side of a cube).
+
+> [!NOTE]
+> By default, texture coordinates are determined by the dimensions of the primitives.
+> For sizes greater than 1.0, the result is undefined and may change in future updates.
+> Use `region` or `region-scale` for manual adjustments.
+
+## Primitives
+
+### `tri` Properties
+
+This primitive describes a triangle.
+
+- `a` - Point A. Example: `a (0,0,0)`
+- `b` - Point B. Example: `b (1,0,0)`
+- `c` - Point C. Example: `c (1,1,0)`
+- `uv` - Normalized texture coordinates of the points (6 numbers, 2 per point). Example: `uv (0,0,1,0,1)`
+- `texture` - The texture to display. Default: `$0`. Example: `texture "blocks:sand"`
+- `region` - UV region within the selected texture, defined by the positions of opposite corners of a square of normalized texture coordinates. Example: `region (0,0,1,1)`
+- `region-scale` - multiplier vector for the UV region. Example: `region-scale (0.5,1)`
+- `shading` - determines whether shading is enabled on the primitive. Example: `shading off`
+
+By default, texture coordinates are not affected by shape or size, unlike other primitives.
+
+### `rect` Properties
+
+This primitive describes a parallelogram using the right and up vectors.
+
+- `from` - the origin of the primitive. Example: `from (0,0.5,0.125)`
+- `right` - the X vector, which also determines the width of the primitive. Example: `right (1,0,0)`
+- `up` - the Y vector, which also determines the primitive's height. Example: `up (0,1,0)`
+- `texture` - the texture to display. Default: `$0`. Example: `texture "blocks:sand"`
+- `region` - the UV region within the selected texture, defined by the positions of opposite corners. Example: `region (0,0,1,1)`
+- `region-scale` - the multiplier vector for the automatically selected UV region. Example: `region-scale (0.5,1)`
+- `shading` - determines whether shading is enabled on the primitive. Example: `shading off`
+- `flip` - flips the UV region horizontally or vertically. Example: `flip v`
+
+### `box` Properties
+
+This primitive describes a rectangular parallelepiped.
+
+- `from` - the primitive's origin. Example: `from (0,0,0)`
+- `to` - the point opposite the origin. Example: `to (1,1,1)`
+- `origin` - the point relative to which the rotation will be applied. Default: the center of the primitive. Example: `origin (0.5,0.5,0.5)`
+- `rotate` - rotation around the (x,y,z) axes in degrees, or a quaternion (x,y,z,w). Example: `rotate (45,0,0)` or `rotate (0.3826834, 0, 0, 0.9238795)`
+- `texture` - the default texture to display for all sides.
+- `shading` determines whether shading is enabled on the primitive. Example: `shading off`
+- `delete` deletes sides by name (top, bottom, east, west, north, south)
+
+### `part` properties (nested in `box`)
+
+This primitive describes the properties of the sides of a rectangular parallelepiped with the specified tags (top/bottom/north/south/east/west).
+
+- `tags` - determines which side the properties will be applied to. Example: `tags (top,bottom)`
+- `texture` - the texture to display. Default: `$side_index`.
+- `region` - the UV region within the selected texture, defined by the positions of opposite corners. Example: `region (0,0,1,1)`
+- `region-scale` is a multiplier vector for the automatically selected UV region. Example: `region-scale (0.5,1)`
+
+## Skeleton
+
+VCM can describe the [skeleton](rigging.md) of a model. The `@bone` element is used for this.
+
+There are two types of bones:
+- unnamed - used only for transformations on inner primitives and not included in the final skeleton.
+- named - will be included in the final skeleton. The name is specified via the `name` attribute.
+
+The main bone (`root`) is created automatically for the entire model.
+If bones are explicitly specified, the model will be divided into several parts named as `model_name.bone_name`.
+Since the model is an asset and has no prefix, the loaded skeleton receives the model name, also without a prefix.
+The loaded skeleton can be used in the [entity](entity-properties.md#skeleton-name) via the `skeleton-name` property.
+
+In the `pack/preload.json` list, if `"squash": true` is specified, the vcm will be loaded as a single model, without a skeleton.
+
+### `bone` Properties
+
+- `name` - The bone name. If omitted, the bone will be "dissolved" and will not be included in the final skeleton, but transformations will be applied.
+- `move` - Moves nested elements.
+- `scale` - Scales nested elements. Applied before moving.
+- `rotate` - Rotates nested elements around the (x, y, z) axes in degrees, or as a quaternion (x, y, z, w). Example: `rotate (45,0,0)` or `rotate (0.3826834, 0, 0, 0.9238795)`

doc/ru/block-properties.md

@@ -247,6 +247,14 @@
 
 Массив из трех целых чисел. Значение по-умолчанию - `[1, 1, 1]`.
 
+### Поведение приземленности - *grounding-behaviour*
+
+Определяет поведение расширенного приземленного блока. Доступные варианты поведения:
+
+- "partial" - как минимум один сегмент блока должен быть приземленным (по-умолчанию)
+- "complete" - все сегменты блока должны быть приземленными
+- "origin" - главный сегмент должен быть приземленным
+
 ## Поля блока
 
 Поля блоков позволяет записывать больше уникальных для конкретного блока данных, чем это позволяют пользовательские биты.

doc/ru/main-page.md

@@ -22,5 +22,5 @@
 - [Свойства сущностей](entity-properties.md)
 - [Скриптинг](scripting.md)
 - [Стили текста](text-styles.md)
-- [Частицы](particles.md)
 - [Формат моделей VCM](vcm.md)
+- [Частицы](particles.md)

doc/ru/scripting/builtins/libblock.md

@@ -46,7 +46,7 @@ block.destruct(x: int, y: int, z: int, playerid: int)
 block.get_variant(x: int, y: int, z: int) -> int
 
 -- Устанавливает вариант блока по индексу
-block.set_variant(x: int, y: int, z: int, index: int) -> int
+block.set_variant(x: int, y: int, z: int, index: int)
 ```
 
 > [!WARNING]