# HG changeset patch
# User Wuzzy
# Date 1687357732 0
# Node ID dd8b0bad793a4999f6f563419adaeb9bace42f30
# Parent  de14b46c7c16c39796e24745a1352d2c26acbe27
LuaLibraryAnimate: Document skipping

diff -r de14b46c7c16 -r dd8b0bad793a LuaLibraryAnimate.wiki
--- a/LuaLibraryAnimate.wiki	Wed Jun 21 13:56:48 2023 +0000
+++ b/LuaLibraryAnimate.wiki	Wed Jun 21 14:28:52 2023 +0000
@@ -83,6 +83,24 @@
 
 Once all animations in the animation list have been played, the game returns to the *Not Animating* state and behaves normally again.
 
+<code language="lua">function onPreciseLocal()
+    if AnimInProgress() then
+        SetAnimSkip(true)
+    end
+end</code>
+
+=== Skipping ===
+
+You can optionally allow to skip animations so allows players can skip the currently running animation. Skipping is *not* enabled by default. By convention, pressing the Precise key in singleplayer missions should skip the current animation. We recommend to use the following code to enable skipping with the Precise key:
+
+<code language="lua">function onPreciseLocal()
+    if AnimInProgress() then
+        SetAnimSkip(true)
+    end
+end</code>
+
+When the current animation is skipped, it is actually immediately stopped, so the game might be in a state you do not want it to be in. For example, if hogs walk in your animation, the hogs will not be in the intended position if the animation was skipped. To fix this, you need to use `AddSkipFunction` (see below for an example).
+
 == Function reference ==
 === Cinematic handling ===
 
@@ -136,15 +154,28 @@
 Removes `animation` from the animation list.
 
 ==== `AddSkipFunction(animation, func, args)` ====
-Adds `func` to the array of functions used to skip animations, associating it with `animation`. When the animation is skipped (see below), the function is called with `args` as arguments.
+Adds `func` to the array of functions used to skip animations, associating it with `animation`. When the animation is skipped, the function is called with `args` as arguments.
+
 Example:
-<code language="lua">AddSkipFunc(animation, myAnimationSkipFunction, {})</code>
+<code language="lua">-- Makes a hedgehog `myHog` walk to the left until X=1000 but if the animation was skipped, teleport the hog to this X position instead.
+local walkAnimation = {
+    {func = AnimMove, args = {myHog, "Left", 1000, 0}},
+}
+AddAnim(walkAnimation)
+local function afterWalkAnimationSkip(args)
+    -- Teleport hog
+    SetGearPosition(myHog, 1000, GetY(myHog))
+    -- Stop walking
+    SetGearMessage(myHog, 0)
+end
+AddSkipFunction(walkAnimation, afterWalkAnimationSkip, {})
+</code>
 
 ==== `RemoveSkipFunction(animation)` ====
 Removes the skip function associated with `animation`.
 
 ==== `SetAnimSkip(bool)` ====
-Sets the state of animation skipping to `bool`. It is useful in case the player is allowed to skip the animation.
+Sets the state of animation skipping to `true` or `false`. If `true`, animations will be skipped. It is useful in case the player is allowed to skip the animation. Note this library will automatically reset the state back to `false` from time to time.
 
 By convention, a cut scene in a singleplayer mission should be skipped when the player presses the Precise key. In this case, use the `onPreciseLocal` callback for this.