diff --git a/doc/en/scripting/builtins/libfile.md b/doc/en/scripting/builtins/libfile.md index 0d4374cac..8f4378b44 100644 --- a/doc/en/scripting/builtins/libfile.md +++ b/doc/en/scripting/builtins/libfile.md @@ -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 ``` diff --git a/doc/en/vca.md b/doc/en/vca.md new file mode 100644 index 000000000..adde137f6 --- /dev/null +++ b/doc/en/vca.md @@ -0,0 +1,118 @@ +# 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) + +## 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 +``` + +## 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. diff --git a/doc/ru/scripting/builtins/libfile.md b/doc/ru/scripting/builtins/libfile.md index 0d1b9d58c..0c1e03ff6 100644 --- a/doc/ru/scripting/builtins/libfile.md +++ b/doc/ru/scripting/builtins/libfile.md @@ -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 -``` \ No newline at end of file +```