ALPHA version - expect chaos
LuaLibraryAnimate
History
Lua library documentation of Animate; for cinematics, cut-scenes and other nice animations
Updated Thu, 03 May 2018 00:42:33 +0100 by Wuzzy

Lua library: Animate

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

In order to use its full potential, the following lines need to be at the beginning of onGameTick .

function onGameTick() AnimUnWait() if ShowAnimation() == false then return end ExecuteAfterAnimations() CheckEvents() end

Also, AnimInit() needs to be called in onGameInit() . Each of these functions will be explained below.

Note: The Animate library will direclty 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.

Cinematic handling

AnimInit([startAnimating])

Initializes variables used by the other functions. Needs to be called in onGameInit .

Since 0.9.23, 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.

Example: function BlowHog(deadHog) AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false}) AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false}) AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}}) AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}}) AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}}) AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) 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}}}}

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) .

Animate(steps)

THIS FUNCTION IS UNDOCUMENTED!

AddAnim(steps)

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 .

  • 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.

  • args is a table containing the arguments that need to be passed to the function given

  • 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.
Example: cinem = { {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}}, {func = AnimMove, args = {myhog, "Left", 2000, 0}}, {func = AddCaption, swh = false, args = {"But he found no more snails..."}} } AddAnim(cinem)

RemoveAnim(steps)

Removes steps from the animations array.

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. Example: AddSkipFunc(cinem, SkipCinem, {})

RemoveSkipFunction(anim)

Removes the skip function associated with anim .

SetAnimSkip(bool)

Sets the state of animation skipping to bool . It is useful in case the player is allowed to skip the animation.

Example: function onPrecise() if AnimInProgress() then SetAnimSkip(true) end end

AnimInProgress()

Returns true if a cinematic 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 .

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 .

Example: AddFunction({func = AfterCinem, args = {2}})

RemoveFunction()

Removes the first function from the aforementioned list.

AnimUnWait()

Decreases the wait time used by cinematics. 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.

Internally, the input mask you provide is simply AND-ed with the input mask used by the Animate library. Otherwise, this function works lik SetInputMask .

If you call SetInputMask directly, note that it might get quickly overwritten by the Animatel library!

Cinematic functions

AnimSwitchHog(gear)

Switches to gear and follows it.

AnimGiveState(gear, state)

Adds the gear state state to gear .

AnimRemoveState(gear, state)

Removes the gear state state from gear .

AnimWait(gear, time)

Increases the wait time by time . gear is just for compatibility with ShowAnimation .

AnimSay(gear, text, manner, time)

Calls HogSay with the first three arguments and increses the wait time by time .

Example: cinem = { {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}}, {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}} }

AnimSound(gear, sound, time)

Plays the sound sound and increases the wait time by time .

AnimTurn(hog, dir)

Makes hog face in direction dir , where dir equals either "Right" or "Left" .

AnimMove(hog, dir, x, y)

Makes hog move in direction dir until either his horizontal coordinate is x or his vertical coordinate is y .

AnimJump(hog, jumpType)

Makes hog perform a jump of type jumpType , where jumpType equals either "long" , "high" or "back" .

AnimSetGearPosition(gear, x, y, fall)

Sets the position of gear to ( x , y ). If the optional argument fall does not equal false then the gear is given a small falling velocity in order to get around exact positioning.

AnimDisappear(gear, x, y)

Teleports the gear to ( x , y ), adding some effects at the previous position and sounds. Doesn’t follow the gear.

AnimOutOfNowhere(gear, x, y)

Teleports the gear to ( x , y ), adding effects and sounds at the final position. Follows gear.

AnimTeleportGear(gear, x, y)

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

AnimVisualGear(gear, x, y, vgType, state, critical, follow)

Calls AddVisualGear with arguments second to sixth. If the optional argument follow equals true then the gear is followed. gear is for compatibility only.

AnimCaption(gear, text, time)

Adds text as caption and increases wait time by time .

AnimCustomFunction(gear, func, args)

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.

Example: function NeedToTurn(hog1, hog2) if GetX(hog1) < GetX(hog2) then HogTurnLeft(hog1, false) HogTurnLeft(hog2, true) else HogTurnLeft(hog2, false) HogTurnLeft(hog1, true) end end cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}

Event handling

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.

AddEvent(condFunc, condArgs, doFunc, doArgs, evType)

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: function CheckPos() return GetX(myHog) > 1500 end function CheckAmmo() return GetAmmoCount(myHog, amGrenade) == 0 end function DoPos() ShowMission("Scooter", "Mover", "Nice Work", 0, 0) end function DoAmmo() AddAmmo(myHog, amGrenade, 5) end AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event

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.

RemoveEventFunc(cFunc, cArgs)

Removes the event or events that have cFunc as the condition checking function. If cArgs does not equal nil then only those events get removed that have cArgs as arguments for cFunc , too.

Example: AddEvent(condFunc1, condArgs1, doFunc, doArgs) AddEvent(condFunc1, condArgs2, doFunc, doArgs) AddEvent(condFunc1, condArgs2, doFunc, doArgs) AddEvent(condFunc2, condArgs1, doFunc, doArgs) AddEvent(condFunc2, condArgs2, doFunc, doArgs) RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1 RemoveEventFunc(condFunc2, condArgs1) --Removes a single event

CheckEvents()

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 equals 0 then it is removed from the list. This function is best placed in onGameTick .

Misc.

StoppedGear(gear)

Returns true if the gear is considered to be resting (not moving). (dX and dY are very small) or if the gear does not exist.