Merge branch 'main' into main

This commit is contained in:
Astazium 2026-10-15 16:19:06 +03:00 • committed by GitHub
commit bf59e520a7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
109 changed files with 1908 additions and 474 deletions

View file

@ -1,8 +1,5 @@
# Documentation
> [!WARNING]
> Version is in development. Proceed to [Documentation for 0.31.](https://github.com/MihailRis/voxelcore/blob/release-0.31/doc/en/main-page.md)
## Sections
- [Assets preloading](assets-preload.md)
@ -20,5 +17,6 @@
- [Scripting](scripting.md)
- [Text styles](text-styles.md)
- [VCM models format](vcm.md)
- [VCM animation format](vca.md)
- [World generator engine](world-generator.md)
- [XML UI building](xml-ui-layouts.md)

View file

@ -163,6 +163,12 @@ file.ext(path: str) --> str
Extracts the extension from the path. Example: `world:data/base/config.toml` -> `toml`.
```lua
file.remove_ext(path: string) -> string
```
Returns the path without the extension. Example: `world:data/base/config.toml` -> `world:data/base/config`.
```lua
file.prefix(path: str) --> str
```

View file

@ -41,8 +41,14 @@ skeleton:is_visible([optional] index: int) -> bool
skeleton:set_visible([optional] index: int, status: bool)
-- Returns the color of the entity
skeleton:get_color() -> vec3
skeleton:get_color() -> vec4
-- Returns the color of the bone
skeleton:get_color(index: int) -> vec4
-- Sets the color of the entity
skeleton:set_color(color: vec3)
skeleton:set_color(color: vec4)
-- Sets the color of the bone
skeleton:set_color(color: vec4, bone: int)
```

View file

@ -50,7 +50,7 @@ network.get(
)
-- Example:
network.get("https://api.github.com/repos/MihailRis/VoxelEngine-Cpp/releases/latest", function (s)
network.get("https://api.github.com/repos/MihailRis/voxelcore/releases/latest", function (s)
print(json.parse(s).name) -- will output the name of the latest engine release
end)

View file

@ -185,9 +185,11 @@ rig:index(name: str) -> int
-- or the skeleton if no index is specified
rig:is_visible([optional] index: int) -> bool
-- Sets the visibility status of the skeleton
rig:set_visible(status: bool)
-- Sets the visibility status of a bone by index
-- or the skeleton if no index is specified
rig:set_visible([optional] index: int, status: bool)
rig:set_visible(index: int, status: bool)
-- Returns the color of the entity
rig:get_color() -> vec4

View file

@ -22,6 +22,8 @@ packid.binding.name="inputtype:codename"
- a..z
- 0..9
- f1..f25
- grave-accent, minus, equal, left-bracket, right-bracket, backslash
- semicolon, apostrophe, comma, period, slash
## *input* library

141
doc/en/vca.md Normal file
View file

@ -0,0 +1,141 @@
# VCA
A text-based animation format that uses [VCM](vcm.md) syntax.
A VCA file consists of a set of directives. The order of the directives does not affect the order in which transformations are applied.
Directives are applied to the given target, which can be an entity skeleton or a camera.
When targeting a skeleton, the directive specifies the bone name via the `bone` attribute:
```vcd
@move bone bone_name ...
```
Each directive controls a single scalar value, such as x, y, z, etc., specified via the `by` attribute:
```vcd
@move bone hand by y ...
```
Two kinds of curve definitions are currently available, each producing a value `f(t) = x`, where t is time:
- [keyframe curves (curve)](#keyframe-curves)
- [expression curves (func)](#expression-curves)
## Animation directives
- `@move` - translates an object/bone
- `@rotate` - rotates an object/bone
- `@scale` - scales an object/bone (multiplier)
- `@zoom` - camera zoom (multiplier)
- `@texture` - change of a dynamically assigned texture (see [skeleton:set_texture](scripting/ecs.md#skeleton))
## Metadata
Animation metadata is set in the file via the `configure` directive:
- `fps` - frame rate, used as the divisor when calculating duration
- `frames` - number of animation frames, used as the dividend when calculating duration
- `duration` - explicitly specified duration in seconds (requires `fps` to be specified when keyframes are present)
- `rotation-order` - specifies the order in which Euler angles are applied during rotation (since the format does not take directive order into account). Examples: XYZ, ZYX, YZX.
Metadata applies globally. Its behavior does not depend on its position in the file, but placing it at the beginning is recommended.
## Additional
- `curve` - declares a custom curve type. Specify the curve name `name` and the value expression `func`.
Two keys, `kl` and `kr`, and the value `t` in the range [0..1] are available in the expression.
Example:
`@curve test-linear func (kl.value + (kr.value - kl.value) * t)`
Custom curves are referenced with a `.` prefix. Example: `@move by y curve .test-linear {...}`.
## Keyframe curves
The curve type must be specified via the `curve` attribute:
- `const` - values are not interpolated; they switch when a keyframe is reached
- `linear` - a polyline; linear interpolation is used
- `bezier` - Bézier curve keyframes with explicitly specified left and right tangents (lx, ly, rx, ry)
Keyframes are described in the following `{...}` block as ordered `@key` directives:
```vcd
@rotate by z curve linear {
@key ...
@key ...
}
```
A keyframe must contain a frame number `frame` and a value `value`. For `bezier` keyframes, the tangents are also specified.
Example for `curve bezier`:
```vcd
@key frame 138 value 53.00411 lx 127.067 ly 53.00411 rx 138.001 ry 53.00411
```
For the `texture` directive, it is simpler. Example:
```vcd
@texture name $0 {
@key frame 0 value entities/tireman:face_0
@key frame 24 value entities/tireman:face_1
}
```
> Here, `entities/tireman` is the name of the texture atlas containing `face_*` textures.
> The texture does not necessarily have to be in an atlas.
If you do not wish to limit the animation duration via `configure` but want to loop the keyframe animation for a specific line, you can use the `period` parameter to specify the animation's repetition period in frames. Example:
```vcd
@move by y curve linear period 24 {
@key frame 0 value 0
@key frame 12 value 1
@key frame 24 value 0
}
```
## Expression curves
The attribute describes a function `f(t) = x`, where t is time in seconds.
Example: `func (sin(t * 2.5) + pi)`.
Operators available in expressions:
- `a + b` - addition
- `a * b` - multiplication
- `a / b` - division
- `a % b` - modulo
- `a ^ b` - exponentiation
Constants available in expressions:
- `pi` - the number π
- `e` - Euler's number
Functions available in expressions:
- `sin(x)` - sine of x
- `cos(x)` - cosine of x
- `tan(x)` - tangent of x
- `noise(x, octaves)` - fast 1D noise of x with the given number of octaves
- `noise2d(x, y, octaves)` - 2D noise of x,y with the given number of octaves
- `sign(x)` - an integer indicating the sign of x (-1/0/1)
- `rand(low, high)` - a pseudo-random floating-point number in the range from low to high
- `round(x, places)` - rounds x to the given number of decimal places `places` (optional)
- `floor(x)` - rounds x down to the nearest integer
- `ceil(x)` - rounds x up to the nearest integer
- `exp(x)` - $e^{x}$
- `min(x, ...)` - returns the smallest of the given arguments
- `max(x, ...)` - returns the largest of the given arguments
- `sqrt(x)` - square root of x
- `log(x)` - $ln({x})$
- `log10(x)` - $log_{10}({x})$
- `deg(x)` - converts radians to degrees
- `rad(x)` - converts degrees to radians
>[!WARNING]
> Using undocumented functions may have any undocumented consequences.

View file

@ -42,6 +42,7 @@ This primitive describes a triangle.
- `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`
- `normal` - overrides normal vector. Example: `normal (0,1,0)`
- `cull-face` - determines which side will be culled. Example: `cull-face front` or `cull-face off` (disables face culling)
By default, texture coordinates are not affected by shape or size, unlike other primitives.
@ -58,6 +59,7 @@ This primitive describes a parallelogram using the right and up vectors.
- `shading` - determines whether shading is enabled on the primitive. Example: `shading off`
- `flip` - flips the UV region horizontally or vertically. Example: `flip v`
- `normal` - overrides normal vector. Example: `normal (0,1,0)`
- `cull-face` - determines which side will be culled. Example: `cull-face front` or `cull-face off` (disables face culling)
### `box` Properties

View file

@ -215,6 +215,9 @@ Element is a container. Does not have specific attributes.
> [!WARNING]
> Inventories position is controlled by the engine and can not be changed by attributes *pos* and *margin*
> [!WARNING]
> Slots not linked to an inventory will not be displayed. "Linked to an inventory" refers to the association between an inventory UI element and an inventory via an ID. This link can be explicitly established using `inventory_ui.inventory = inventory_id`. [(see ui.md)](scripting/ui.md#inventory)
## *slot*
Element must be in direct sub-element of *inventory*.

View file

@ -1,8 +1,5 @@
# Документация
> [!WARNING]
> Версия находится в разработке. Перейдите к [документации для 0.31.](https://github.com/MihailRis/voxelcore/blob/release-0.31/doc/ru/main-page.md)
## Разделы
- [XML разметка интерфейса](xml-ui-layouts.md)

View file

@ -78,6 +78,9 @@ file.stem(путь: string) -> string
-- Извлекает расширение из пути. Пример: `world:data/base/config.toml` -> `toml`.
file.ext(путь: string) -> string
-- Возвращает путь без расширения. Пример: `world:data/base/config.toml` -> `world:data/base/config`.
file.remove_ext(путь: string) -> string
```
## Директории
@ -145,4 +148,4 @@ file.open(путь: string, режим: string) -> io_stream
-- * `/tmp/` или `\\\\.\\pipe\\` добавлять не нужно - движок делает это автоматически.
-- * Недоступен режим с `+`
file.open_named_pipe(имя: string, режим: string) -> io_stream
```
```

View file

@ -42,8 +42,14 @@ skeleton:is_visible([опционально] index: int) -> boolean
skeleton:set_visible([опционально] index: int, status: boolean)
-- Возвращает цвет сущности
skeleton:get_color() -> vec3
skeleton:get_color() -> vec4
-- Возвращает цвет кости
skeleton:get_color(index: int) -> vec4
-- Устанавливает цвет сущности
skeleton:set_color(color: vec3)
```
skeleton:set_color(color: vec4)
-- Устанавливает цвет кости
skeleton:set_color(color: vec4, index: int)
```

View file

@ -50,7 +50,7 @@ network.get(
)
-- Пример:
network.get("https://api.github.com/repos/MihailRis/VoxelEngine-Cpp/releases/latest", function (s)
network.get("https://api.github.com/repos/MihailRis/voxelcore/releases/latest", function (s)
print(json.parse(s).name) -- выведет имя последнего релиза движка
end)

View file

@ -174,9 +174,11 @@ rig:index(name: str) -> int
-- или всего скелета, если индекс не указан
rig:is_visible([optional] index: int) -> bool
-- Устанавливает статус видимости всего скелета
rig:set_visible(status: bool)
-- Устанавливает статус видимости кости по индексу
-- или всего скелета, если индекс не указан
rig:set_visible([optional] index: int, status: bool)
rig:set_visible(index: int, status: bool)
-- Возвращает цвет сущности
rig:get_color() -> vec4

View file

@ -20,6 +20,8 @@ packid.binding.name="inputtype:codename"
- a..z
- 0..9
- f1..f25
- grave-accent, minus, equal, left-bracket, right-bracket, backslash
- semicolon, apostrophe, comma, period, slash
## Библиотека input

View file

@ -27,6 +27,7 @@ VCA файл состоит из набора директив, порядок
- `@rotate` - поворот объекта/кости
- `@scale` - масштабирование объекта/кости (множитель)
- `@zoom` - масштаб камеры (множитель)
- `@texture` - смена динамически-назначаемой текстуры (см. [skeleton:set_texture](scripting/ecs.md#skeleton))
## Мета-информация
@ -73,6 +74,28 @@ VCA файл состоит из набора директив, порядок
@key frame 138 value 53.00411 lx 127.067 ly 53.00411 rx 138.001 ry 53.00411
```
Для директивы texture всё проще. Пример:
```vcd
@texture name $0 {
@key frame 0 value entities/tireman:face_0
@key frame 24 value entities/tireman:face_1
}
```
> entities/tireman здесь - имя текстурного атласа, в котором находятся face_\* текстуры.
> Текстура не обязательно должна находиться в атласе.
Если вы не хотите ограничивать длительность анимации через `configure`, но хотите зациклить анимацию по ключевым кадрам для конкретной линии, то можно использовать параметр `period` для указания периода повторения анимации в кадрах. Пример:
```vcd
@move by y curve linear period 24 {
@key frame 0 value 0
@key frame 12 value 1
@key frame 24 value 0
}
```
## Кривые через выражения
Через атрибут описывается функция `f(t) = x` где t - время в секундах.

View file

@ -42,6 +42,7 @@
- `region-scale` вектор-множитель для UV региона. Пример: `region-scale (0.5,1)`
- `shading` определяет возможность затенения на примитиве. Пример: `shading off`
- `normal` переопределяет вектор нормали. Пример: `normal (0,1,0)`
- `cull-face` - определяет, какая сторона будет отсечена. Пример: `cull-face front` или `cull-face off` (отлючает отсечение сторон)
Текстурные координаты по-умолчанию не зависят от формы из размера, в отличие от других примитивов.
@ -58,6 +59,7 @@
- `shading` - определяет возможность затенения на примитиве. Пример: `shading off`
- `flip` - отражает UV регион по горизонтали или вертикали. Пример: `flip v`
- `normal` - переопределяет вектор нормали. Пример: `normal (0,1,0)`
- `cull-face` - определяет, какая сторона будет отсечена. Пример: `cull-face front` или `cull-face off` (отлючает отсечение сторон)
### Свойства `box`

View file

@ -216,6 +216,9 @@
> [!WARNING]
> Расположение инвентарей управляется движком и не может быть изменено свойствами pos, margin и т.д.
> [!WARNING]
> Слоты без привязки к инвентарю не будут отображаться. Под приязкой к инвентарю понимается связь UI элемента inventory с инвентарём по id. Которая может быть явно создана через `inventory_ui.inventory = inventory_id`. [(см ui.md)](scripting/ui.md#инвентарь-inventory)
## Одиночный слот - *slot*
Элемент должен находиться внутри `inventory` элемента, без посредников.

View file

@ -2,7 +2,7 @@
Format version: 1.1
This binary data format is developed for use as binary version of JSON in [VoxelEngine-Cpp](https://github.com/MihailRis/VoxelEngine-Cpp) and not compatible with [BSON](https://bsonspec.org/spec.html) due to elements/entries syntax and type codes differences
This binary data format is developed for use as binary version of JSON in [voxelcore](https://github.com/MihailRis/voxelcore) and not compatible with [BSON](https://bsonspec.org/spec.html) due to elements/entries syntax and type codes differences
## Basic types