--- a/LuaLibraryAnimate.wiki	Wed Jun 21 13:33:14 2023 +0000
+++ b/LuaLibraryAnimate.wiki	Wed Jun 21 13:54:38 2023 +0000
@@ -34,9 +34,10 @@
 
 Also, you *must not* call `SetCinematicMode` ever in your script.
 
-=== Steps ===
+=== Data structures ===
+==== Animation step ====
 
-The step is the primary data structure of this library. A step is a single action in an animation specified in table form. A step table must have the following fields:
+The animation step step is the primary data structure of this library. A step is a single action in an animation specified in table form. A step table must have the following fields:
 
  * `func` is the function to be executed. It can be any function that returns false when it needs to be called again in following game ticks (e.g. `AnimMove`). It could theoretically be any function, but usually you want to use one of the cinematic functions here.
  * `args` is a list containing the arguments that need to be passed to the function given, in the same order
@@ -44,24 +45,32 @@
 
 Example 1:
 <code language="lua">
-    -- This calls `AnimSay(myHog, "Snails! SNAILS!", SAY_SAY, 3000)`,
-    -- meaning the hedgehog gear `myHog` will say "Snails!" and set the animation delay to 3000 milliseconds
-    -- Because `swh` is not set, it is true, so `myHog` also becomes the current hedgehog
-    local step1 = {func = AnimSay, args = {myHog, "Snails!", SAY_SAY, 3000}}
+-- This calls `AnimSay(myHog, "Snails! SNAILS!", SAY_SAY, 3000)`,
+-- meaning the hedgehog gear `myHog` will say "Snails!" and set the animation delay to 3000 milliseconds
+-- Because `swh` is not set, it is true, so `myHog` also becomes the current hedgehog
+local step1 = {func = AnimSay, args = {myHog, "Snails!", SAY_SAY, 3000}}
 </code>
 
 Example 2:
 <code language="lua">
-    -- Moves myHog to the left
-    local step2 = {func = AnimMove, args = {myHog, "Left", 2000, 0}}
+-- Moves myHog to the left
+local step2 = {func = AnimMove, args = {myHog, "Left", 2000, 0}}
 </code>
 
 Example 3:
 <code language="lua">
-    -- Shows the caption "Hello, world!". Because argument 1 is not a hedgehog, `swh` is false
-    local step3 = {func = AddCaption, swh = false, args = {"Hello, world!"}}
+-- Shows the caption "Hello, world!". Because argument 1 is not a hedgehog, `swh` is false
+local step3 = {func = AddCaption, swh = false, args = {"Hello, world!"}}
 </code>
 
+==== Animation ====
+
+An animation is a data structure that is a sequence of animation steps. It is specified as a table of steps. The steps will be executed in the specified order.
+
+==== Animation list ====
+
+The animation list is a list of all animations that were added but not performed so far. This is an internal table, you can not access it directly. You add to the list with `AddAnim`.
+
 === How animation works ===
 
 The Animation library has two states: *Animating* and *Not Animating*. By default, the game starts in the *Not Animating* state, meaning the game behaves normally. In *Animating* state, the library looks at the list of registered animations and executes them one by one, in that order.
@@ -83,7 +92,7 @@
 An optional convenience parameter `startAnimating` is available; if set to `true`, the game will start in “animation” mode which enables cinematic mode and disables all controls except precise for skipping. This is useful if you want to indicate that an animation will be played right at the start and the player must not be allowed to use any controls before the animation is over. If you set this parameter to `true`, you also *must* play at least one animation after this, otherwise the game will be stuck.
 
 ==== `AnimInsertStepNext(step)` ====
-Inserts `step` after the current step (read: action) in the cinematic array. Useful when an action depends on variables (e.g. positions). It can be used mostly with `AnimCustomFunction`. Note: In case of multiple consecutive calls, steps need to be added in reverse order.
+Inserts `step` after the current step (read: action) in the animation list. Useful when an action depends on variables (e.g. positions). It can be used mostly with `AnimCustomFunction`. Note: In case of multiple consecutive calls, steps need to be added in reverse order.
 
 Example:
 <code language="lua">-- Show explosion effects around hedgehog `liveHog`, then delete it
@@ -99,17 +108,19 @@
     AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
     AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
 end
-cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}
-AddAnim(cinem)</code>
+animation = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}
+AddAnim(animation)</code>
 
 ==== `ShowAnimation()` ====
-Performs the current action in the cinematic and returns `true` if finished, otherwise `false`. It needs to be used in `onGameTick`. Cut-scenes need to be added with `AddAnim(steps)`.
+Performs the first animation (if possible) in the animation list and removes it once it’s done. Returns `true` if the animation list was empty and no animation was played or `false` if an animation was played.
+
+It needs to be used in `onGameTick`. Cut-scenes need to be added with `AddAnim(animation)`.
 
-==== `Animate(steps)` ====
-*THIS FUNCTION IS UNDOCUMENTED!*
+==== `Animate(animation)` ====
+Performs the specified animation manually. Returns `true` if the animation was performed successfully, `false` otherwise. This function is internally used; its use in scripts is not recommended.
 
-==== `AddAnim(steps)` ====
-Adds `steps` to the array of animations, where `steps` is a table with numbers as keys and the values are animation steps. See the introduction above for the syntax of animation steps.
+==== `AddAnim(animation)` ====
+Adds `animation` to the animation list. `animation` is a list of animation steps; see data structures above for details.
 
 Example:
 <code language="lua">
@@ -121,16 +132,16 @@
 }
 AddAnim(cinem)</code>
 
-==== `RemoveAnim(steps)` ====
-Removes `steps` from the animations array.
+==== `RemoveAnim(animation)` ====
+Removes `animation` from the animation list.
 
-==== `AddSkipFunction(anim, func, args)` ====
-Adds `func` to the array of functions used to skip animations, associating it with `anim`. When the animation is skipped (see below), the function is called with `args` as arguments.
+==== `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.
 Example:
 <code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code>
 
-==== `RemoveSkipFunction(anim)` ====
-Removes the skip function associated with `anim`.
+==== `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.
@@ -145,13 +156,13 @@
 end</code>
 
 ==== `AnimInProgress()` ====
-Returns `true` if a cinematic is currently taking place, `false` otherwise.
+Returns `true` if a amimation is currently taking place, `false` otherwise.
 
 ==== `ExecuteAfterAnimations()` ====
-Calls the functions (added with `AddFunction`) that need to be executed after the cinematic. The best location for this function call is in `onGameTick`.
+Calls the functions (added with `AddFunction`) that need to be executed after the animation. The best location for this function call is in `onGameTick`.
 
 ==== `AddFunction(element)` ====
-Adds `element` to the functions array that are to be called after the cinematic. `element` is a table with the keys: `func`, `args`.
+Adds `element` to the functions array that are to be called after the animation. `element` is a table with the keys: `func`, `args`.
 
 Example:
 <code language="lua">AddFunction({func = AfterCinem, args = {2}})</code>
@@ -160,7 +171,7 @@
 Removes the first function from the aforementioned list.
 
 ==== `AnimUnWait()` ====
-Decreases the wait time used by cinematics. It is best called in `onGameTick`.
+Decreases the wait time used by animations. It is best called in `onGameTick`.
 
 ==== `AnimSetInputMask(inputMask)` ====
 Call this function instead of `SetInputMask` if you want to set the input mask in a way that does not conflict with the Animate library.