Merge pull request #988 from MihailRis/vca-keyframes-period

add 'period' keyframes-based line parameter to VCA

doc/en/vca.md

@@ -86,6 +86,16 @@ For the `texture` directive, it is simpler. Example:
 > 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.

doc/ru/vca.md

@@ -86,6 +86,16 @@ VCA файл состоит из набора директив, порядок
 > 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 - время в секундах.

res/modules/animation.lua

@@ -48,6 +48,8 @@ local this = {
     INT_LINEAR = 2,
     INT_BEZIER = 3,
     INT_CUSTOM = 4,
+    MAX_DURATION = 1e9,
+    MAX_FRAMES = 1e9,
 
     TRACE_CODEGEN = false,
 

res/modules/internal/animation_codegen.lua

@@ -150,16 +150,16 @@ local function codegen_track(raw_track, lineset, memoised, keysets, use_tsf)
                 local valueat = string.format("curves[%s]", string.escape(line.curve_func))
 
                 code = code .. string.format(
-                "\n   local l%d = value_at_custom(keysets['%s'][%d], t * %s, %s)",
+                "\n   local l%d = value_at_custom(keysets['%s'][%d], t * %s %% %s, %s)",
-                i, lineset.target_name, i, raw_track.fps, valueat)
+                i, lineset.target_name, i, raw_track.fps, line.period, valueat)
             elseif line.channel == animation.CH_TEXTURE then
                 code = code .. string.format(
-                    "\n   local l%d = string_at(keysets['%s'][%d], t * %s)",
+                    "\n   local l%d = string_at(keysets['%s'][%d], t * %s %% %s)",
-                    i, lineset.target_name, i, raw_track.fps)
+                    i, lineset.target_name, i, raw_track.fps, line.period)
             else
                 code = code .. string.format(
-                    "\n   local l%d = value_at(keysets['%s'][%d], t * %s, %s)",
+                    "\n   local l%d = value_at(keysets['%s'][%d], t * %s %% %s, %s)",
-                    i, lineset.target_name, i, raw_track.fps, line.interp)
+                    i, lineset.target_name, i, raw_track.fps, line.period, line.interp)
             end
         end
 

res/modules/internal/formats/vca.lua

@@ -106,7 +106,8 @@ local function parse_track(root)
         end
         local line = {
             axis = node.by and ("xyz"):find(node.by) or "",
-            channel = channel
+            channel = channel,
+            period = node.period or animation.MAX_FRAMES
         }
         if node.func then
             line.expression = node.func

res/scripts/components/animator.lua

@@ -1,4 +1,4 @@
-local ALMOST_HUGE = 1e9
+local MAX_DURATION = animation.MAX_DURATION
 
 local rig = entity.skeleton
 
@@ -54,7 +54,7 @@ local function update(delta)
         if state.track and intensity > 0.0 then
             state.track.func(
                 rig,
-                state.timer % math.min(ALMOST_HUGE, state.track.duration),
+                state.timer % math.min(MAX_DURATION, state.track.duration),
                 intensity * state.max_intencity
             )
         end