114 

   115 

   116 = Animate =

   117 

   118 This library provides functions that aid cinematic/cut-scene creation and functions for handling events. 

   119 

   120 In order to use it's full potential, the following lines need to be at the beginning of onGameTick.

   121 

   122 <code lang="lua">function onGameTick()

   123     !AnimUnWait()

   124     if !ShowAnimation() == false then

   125         return

   126     end

   127     !ExecuteAfterAnimations()

   128     !CheckEvents()

   129 end</code>

   130 

   131 Also, !AnimInit() needs to be called in !onGameInit().

   132 Each of these functions will be explained below.

   133 

   134 == Cinematic Handling ==

   135 

   136 === !ShowAnimation() ===

   137 <blockquote>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).</blockquote>

   138 

   139 === !AddAnim(steps) ===

   140 <blockquote>Adds steps to the array of animations, where steps is a table with numbers as keys and elements of the following form. Each step is a table having the following keys: func, args, swh.

   141 

   142   * _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 can be one of the cinematic functions. 

   143 

   144   * _args_ is a table containing the arguments that need to be passed to the function given

   145 

   146   * _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.</blockquote>

   147 Example:

   148 <code lang="lua">cinem = {

   149     {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}},

   150     {func = AnimMove, args = {myhog, "Left", 2000, 0}},

   151     {func = AddCaption, swh = false, args = {"But he found no more snails..."}}

   152     }

   153 AddAnim(cinem)</code>

   154 

   155 === !RemoveAnim(steps) ===

   156 <blockquote>Removes steps from the animations array.</blockquote>

   157 

   158 === !AddSkipFunction(anim, func, args) ===

   159 <blockquote>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.</blockquote>

   160 Example:

   161 <code lang="lua">AddSkipFunc(cinem, SkipCinem, {})</code>

   162 

   163 === !RemoveSkipFunction(anim) ===

   164 <blockquote> Removes the skip function associated with _anim_.</blockquote>

   165 

   166 === !SetAnimSkip(bool) ===

   167 <blockquote> Sets the state of animation skipping to _bool_. It is useful in case the player is allowed to skip the animation.</blockquote>

   168 Example:

   169 <code lang="lua">function onPrecise()

   170     if !AnimInProgress() then

   171         SetAnimSkip(true)

   172     end

   173 end</code>

   174 

   175 === !AnimInProgress() ===

   176 <blockquote> Returns true if a cinematic is currently taking place, false otherwise.</blockquote>

   177 

   178 === !ExecuteAfterAnimations() ===

   179 <blockquote> Calls the functions (added with !AddFunction) that need to be executed after the cinematic. The best location for this function call is in onGameTick.</blockquote>

   180 

   181 === !AddFunction(element) ===

   182 <blockquote> Adds _element_ to the functions array that are to be called after the cinematic. _element_ is a table with the keys: func, args.</blockquote>

   183 Example:

   184 <code lang="lua">AddFunction({func = AfterCinem, args = {2}})</code>

   185 

   186 === !RemoveFunction() ===

   187 <blockquote> Removes the first function from the aforementioned list.</blockquote>

   188 

   189 === !AnimInit() ===

   190 <blockquote> Initializes variables used by the other functions. Needs to be called in onGameInit.</blockquote>

   191 

   192 === !AnimUnWait() ===

   193 <blockquote> Decreases the wait time used by cinematics. It is best called in onGameTick</blockquote>

   194 

   195 == Cinematic Functions ==

   196 

   197 === !AnimSwitchHog(gear) ===

   198 <blockquote> Switches to _gear_ and follows it. </blockquote>

   199 

   200 === !AnimWait(gear, time) ===

   201 <blockquote> Increases the wait time by _time_. _gear_ is just for compatibility with !ShowAnimation.</blockquote>

   202 

   203 === !AnimSay(gear, text, manner, time) ===

   204 <blockquote> Calls HogSay with the first three arguments and increses the wait time by _time_.</blockquote>

   205 Example:

   206 <code lang="lua">cinem = {

   207     {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}},

   208     {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}}

   209    }</code>

   210 

   211 === !AnimSound(gear, sound, time) ===

   212 <blockquote> Plays the sound _sound_ and increases the wait time by _time_.</blockquote>

   213 

   214 === !AnimTurn(hog, dir) ===

   215 <blockquote> Makes _hog_ face in direction _dir_, where _dir_ is either "Right" or "Left".</blockquote>

   216 

   217 === !AnimMove(hog, dir, x, y) ===

   218 <blockquote> Makes _hog_ move in direction _dir_ until either his horizontal coordinate is _x_ or his vertical coordinate is _y_.</blockquote>

   219 

   220 === !AnimJump(hog, jumpType) ===

   221 <blockquote> Makes _hog_ perform a jump of type _jumpType_, where _jumpType_ is either "long", "high" or "back".</blockquote>

   222 

   223 === !AnimSetGearPosition(gear, x, y, fall) ===

   224 <blockquote> Sets the position of _gear_ to (x, y). If the optional argument _fall_ is not false then the gear is given a small falling velocity in order to get around exact positioning.</blockquote>

   225 

   226 === !AnimDisappear(gear, x, y) ===

   227 <blockquote> Teleports the gear to (x, y), adding some effects at the previous position and sounds. Doesn't follow the gear.</blockquote>

   228 

   229 === !AnimOutOfNowhere(gear, x, y) ===

   230 <blockquote> Teleports the gear to (x, y), adding effects and sounds at the final position. Follows gear.</blockquote>

   231 

   232 === !AnimTeleportGear(gear, x, y) ===

   233 <blockquote> Teleports the gear to (x, y), adding effects and sounds both at the starting position and the final position. Follows gear.</blockquote>

   234 

   235 === !AnimVisualGear(gear, x, y, vgType, state, critical, follow) ===

   236 <blockquote> Calls AddVisualGear with arguments second to sixth. If the optional argument _follow_ is true then the gear is followed. _gear_ is for compatibility only.</blockquote>

   237 

   238 === !AnimCaption(gear, text, time) ===

   239 <blockquote> Adds _text_ as caption and increases wait time by _time_.</blockquote>

   240 

   241 === !AnimCustomFunction(gear, func, args) ===

   242 <blockquote> Calls the function _func_ with _args_ as arguments. This function is useful, for instance, when the cinematic uses the position of a gear at the moment of execution. If _func_ needs to be called in following game ticks then it should return false.</blockquote>

   243 Example:

   244 <code lang="lua">function NeedToTurn(hog1, hog2)

   245    if GetX(hog1) < GetX(hog2) then

   246       HogTurnLeft(hog1, false)

   247       HogTurnLeft(hog2, true)

   248    else

   249       HogTurnLeft(hog2, false)

   250       HogTurnLeft(hog1, true)

   251    end

   252 end

   253 

   254 cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}</code>

   255 

   256 === !AnimInsertStepNext(step) ===

   257 <blockquote> Inserts _step_ after the current step (read: action) in the cinematic array. Useful when an action depends on variables (e.g. positoins). It can be used mostly with !AnimCustomFunction. Note: In case of multiple consecutive calls, steps need to be added in reverse order.</blockquote>

   258 Example:

   259 <code lang="lua">function BlowHog(deadHog)

   260   AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false}) 

   261   AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false})

   262   AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}})

   263   AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})

   264   AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})

   265   AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})

   266   AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})

   267   AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})

   268   AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})

   269   AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})

   270 end

   271 cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code>

   272 

   273 == Event Handling ==

   274 

   275 Events are pairs of functions that are used to check for various conditions. One of them is for verification and, if it returns true, the second function is called.

   276 

   277 === !AddEvent(condFunc, condArgs, doFunc, doArgs, evType) ===

   278 <blockquote> 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).</blockquote>

   279 Example:

   280 <code lang="lua">function CheckPos()

   281    return GetX(myHog) > 1500

   282 end

   283 function CheckAmmo()

   284    return GetAmmoCount(myHog, amGrenade) == 0

   285 end

   286 function DoPos()

   287    ShowMission("Scooter", "Mover", "Nice Work", 0, 0)

   288 end

   289 function DoAmmo()

   290    AddAmmo(myHog, amGrenade, 5)

   291 end

   292 AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion

   293 AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event</code>

   294 

   295 === !AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType) ===

   296 <blockquote> Does the same as !AddEvent, but first checks if the event is already in the list so that it isn't added twice.</blockquote>

   297 

   298 === !RemoveEventFunc(cFunc, cArgs) ===

   299 <blockquote> Removes the event(s) that have _cFunc_ as the condition checking function. If _cArgs_ is not nil then only those events get removed that have _cArgs_ as arguments for _cFunc_, too.</blockquote>

   300 Example:

   301 <code lang="lua">AddEvent(condFunc1, condArgs1, doFunc, doArgs)

   302 AddEvent(condFunc1, condArgs2, doFunc, doArgs)

   303 AddEvent(condFunc1, condArgs2, doFunc, doArgs)

   304 AddEvent(condFunc2, condArgs1, doFunc, doArgs)

   305 AddEvent(condFunc2, condArgs2, doFunc, doArgs)

   306 RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1

   307 RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code>

   308 

   309 === !CheckEvents ===

   310 <blockquote> Verifies all the condition functions in the events list and calls the respective 'action' functions if the conditions are met. If the evType of a completed event is 0 then it is removed from the list. This function is best placed in onGameTick.</blockquote>