# HG changeset patch
# User Wuzzy
# Date 1687339473 0
# Node ID dd92ebc2895794d70e6753557ca509bf54ad7656
# Parent  47493b26d4ee48100e5030e78d40f26a46f03bb6
LuaLibraryAnimate: Extend the introduction

diff -r 47493b26d4ee -r dd92ebc28957 LuaLibraryAnimate.wiki
--- a/LuaLibraryAnimate.wiki	Wed Jun 21 07:51:30 2023 +0000
+++ b/LuaLibraryAnimate.wiki	Wed Jun 21 09:24:33 2023 +0000
@@ -5,9 +5,13 @@
 <wiki:toc max_depth="2" />
 This library provides functions that aid cinematic/cut-scene creation and functions for handling events.
 
-== Getting started ==
+== Structure of an Animate script ==
+
+The Animate library is somewhat complex, so this section explains how scripts using the Animate library are supposed to look like and how the functions interact.
 
-In order to use its full potential, the following lines need to be at the beginning of `onGameTick`:
+=== Initial code ===
+
+For every script using this library, the following lines need to be at the beginning of `onGameTick`:
 
 <code language="lua">function onGameTick()
     AnimUnWait()
@@ -26,7 +30,47 @@
 
 Each of these functions will be explained below.
 
-Note: The Animate library will directly overwrite the input mask with `SetInputMask`. If you already use this function in your script, it might lead to conflicts. Use `AnimSetInputMask` to set the input mask in a manner that is compatible with the Animate library.
+Also, if your script calls `SetInputMask`, you **must** replace each call of it with `AnimSetInputMask` (see function description below). Failing to do so may lead to bugs.
+
+Also, you **must not** call `SetCinematicMode` ever in your script.
+
+=== Steps ===
+
+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:
+
+* `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
+* `swh` is an optional boolean value that defaults to `true` and denotes whether the current hedgehog should be switched to the hog given as argument 1 in `args`. You *must* set this to `false` if argument 1 is not a hog or the argument list is empty.
+
+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}}
+</code>
+
+Example 2:
+<code language="lua">
+    -- 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!"}}
+</code>
+
+=== 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.
+
+You are expected to add to the list of animatinons with `AddAnim`. If the script is animating, this animation will be played after all the others have been played. If the script is not animating, the animation will be played immediately. (Assuming you have correctly added the boilerplate code mentioned at the beginning of this page.)
+
+Animations are basically cut scenes. During animation, Cinematic Mode is enabled (see `SetCinematicMode` which is part of the main Lua API) and most player input is blocked. Animations can cause various things to happen, like move hedgehogs, show speech bubbles, explode the landscape or just call (almost) any function. During an animation, the player can only watch or optionally skip (details later). The player can still move the camera.
+
+There is also an internal wait time. It starts at 0 and a few cinematic functions as well as `AnimWait` can increase this time. The wait time counts down to 0, during which the script waits to execute the next animation step. Adding to the wait time is important to time your animation correctly.
 
 == Cinematic handling ==
 
@@ -124,6 +168,7 @@
 If you call `SetInputMask` directly, note that it might get quickly overwritten by the Animate library!
 
 == Cinematic functions ==
+These are the functions you can specify in animation steps.
 
 === `AnimSwitchHog(gear)` ===
 Switches to `gear` and follows it.
@@ -190,7 +235,7 @@
    end
 end
 
-cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}</code>
+cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hog2}}}}</code>
 
 == Event handling ==
 
@@ -200,7 +245,12 @@
 Adds the functions `condFunc` and `doFunc` to the events list. They get called with the respective args (`condArgs` and `doArgs`). `condFunc` will get called in every game tick until it returns `true` or is removed. Once it returns `true`, `doFunc` is called and they are or are not removed from the list, depending on `evType` (`0` for removal, `1` for keeping). An `evType` of `1` is useful for repeating actions (e.g. every time a hog gets damaged, do something).
 
 Example:
-<code language="lua">function CheckPos()
+<code language="lua">
+--[[
+This code shows the mission text "Nice Work" if the hog `myHog` has an X coordinate above 1500, but only once.
+Also, it immediately gives `myHog` 5 grenades once it runs out of grenades. It does that every time this happens.
+]]
+function CheckPos()
    return GetX(myHog) > 1500
 end
 function CheckAmmo()
@@ -213,7 +263,8 @@
    AddAmmo(myHog, amGrenade, 5)
 end
 AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion
-AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event</code>
+AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event
+</code>
 
 === `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` ===
 Does the same as `AddEvent`, but first checks if the event is already in the list so that it isn’t added twice.