Lua library:
Animate
This library provides functions that aid cinematic/cut-scene creation and functions for handling events.
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.
Initial code
For every script using this library, 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()
:
function onGameInit()
AnimInit()
end
Each of these functions will be explained below.
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.
Data structures
Animation step
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
-
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 hedgehog.
Example 1:
-- This calls `AnimSay(myHog, "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}}
Example 2:
-- Moves myHog to the left
local step2 = {func = AnimMove, args = {myHog, "Left", 2000, 0}}
Example 3:
-- Shows the caption "Hello, world!". Because argument 1 is not a hedgehog, `swh` is false
local step3 = {func = AddCaption, swh = false, args = {"Hello, world!"}}
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.
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.
Once all animations in the animation list have been played, the game returns to the Not Animating state and behaves normally again.
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:
function onPrecise()
if AnimInProgress() then
SetAnimSkip(true)
end
end
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).
Animation example
This is the complete source code for a mission script demonstrating a simple animation in which a single hedgeghog says Hello and walks to the left. It shows the basic structure of a script using animations. This is only an example, your own implementation may vary.
HedgewarsScriptLoad("/Scripts/Animate.lua")
-- Mandatory code for Animate library
function onGameTick()
AnimUnWait()
if ShowAnimation() == false then
return
end
ExecuteAfterAnimations()
CheckEvents()
end
-- Store hegehog ID here
local hog1
function onGameInit()
-- Mandatory code for Animate library
AnimInit()
-- Configure mission
Map = "Ruler"
Theme = "Nature"
Explosives = 0
MinesNum = 0
CaseFreq = 0
GameFlags = gfOneClanMode
-- Add team and hog
AddTeam("Test Team", -1, "egg", "Castle", "Default_qau", "cm_test")
hog1 = AddHog("Hog 1", 0, 100, "NoHat")
SetGearPosition(hog1, 1100, 770)
end
-- Skip animation when pressing [Precise]
function onPrecise()
if AnimInProgress() then
SetAnimSkip(true)
end
end
-- This function sets up the example animation
local function addWalkAnim()
-- X coordinate that hog walks to
local goalX = 900
-- Animation example: Hog says hello and then walks to the left and then speaks again
local animation = {
-- List of animation steps
{func = AnimSay, args = {hog1, "Hello. I will walk to the left.", SAY_SAY, 2000}},
{func = AnimMove, args = {hog1, "Left", goalX, 0}},
{func = AnimSay, args = {hog1, "I reached my goal!", SAY_SAY, 2000}},
}
-- Add skip function if player presses the skip key
local function afterAnimSkip(args)
-- Teleport hog
SetGearPosition(hog1, goalX, GetY(hog1))
-- Face left (because hog walked left)
HogTurnLeft(hog1, true)
-- Stop walking
SetGearMessage(hog1, 0)
end
AddSkipFunction(animation, afterAnimSkip, {})
-- This will be execuded when the animation ended
local function afterWalkAnim()
AddCaption("Animation completed!")
ShowMission("Animation completed!", "It's over!", "You can return to the menu now.", 0, 0)
end
AddFunction({func = afterWalkAnim, args = {}})
-- Add the animation to the animation list.
-- In our case, it wiill be perfmored immediately.
AddAnim(animation)
end
-- This makes sure the animation starts on the first turn
local hasAnimationStarted = false
function onNewTurn()
if hasAnimationStarted then
return
end
if CurrentHedgehog ~= hog1 then
SwitchHog(hog1)
end
addWalkAnim()
hasAnimationStarted = true
end
Function reference
Cinematic handling
AnimInit([startAnimating])
Initializes variables used by the other functions. Needs to be called in
onGameInit
.
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 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:
-- Show explosion effects around hedgehog `liveHog`, then delete it
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
animation = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}
AddAnim(animation)
ShowAnimation()
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(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(animation)
Adds
animation
to the animation list.
animation
is a list of animation steps; see data structures above for details.
Example:
-- Makes myHog say "Snails! SNAILS!, wait 3 seconds, move it to the left until its X coordinate equals 2000, then show the caption "But he found no more snails ..."
animation = {
{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(animation)
RemoveAnim(animation)
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, the function is called with
args
as arguments.
Example:
-- 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, {})
RemoveSkipFunction(animation)
Removes the skip function associated with
animation
.
SetAnimSkip(bool)
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
onPrecise
callback for this.
Example:
function onPrecise()
if AnimInProgress() then
SetAnimSkip(true)
end
end
AnimInProgress()
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 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 animation.
element
is a table with the keys:
func
,
args
.
Example:
AddFunction({func = myAfterAnim, args = {2}})
RemoveFunction()
Removes the first function from the aforementioned list.
AnimUnWait()
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.
Internally, the input mask you provide is simply AND-ed with the input mask used by the Animate library. Otherwise, this function works like
SetInputMask
.
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. Unless specified otherwise, the
gear
argument of each function switches the
CurrentHedgehog
to
gear
and follows it. This behavior can be disabled with
swh=false
(see definition of animation steps above).
AnimSwitchHog(gear)
Switches the
CurrentHedgehog
to
gear
and follows it.
AnimFollowGear(gear)
Follows
gear
.
AnimGiveState(gear, state)
Sets the
gear state of
gear
to
state
(full bitmask).
AnimRemoveState(gear, state)
Removes the
gear state
state
from
gear
.
AnimWait(gear, time)
Increases the wait time by
time
(in milliseconds) without changing the
CurrentHedgehog
. The
gear
argument is ignored (it exists for compability with `ShowAnimation).
AnimGearWait(gear, time)
Increases the wait time by
time
(in milliseconds) and changes the
CurrentHedgehog
to
gear
.
AnimSay(gear, text, manner, time)
Calls
HogSay
with the first three arguments and increases the wait time by
time
.
Example:
animation = {
{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, maxMoveTime)
Makes
hog
walk in direction
dir
(
"Right"
or
"Left"
) until either its horizontal coordinate equals
x
or its vertical coordinate equals
y
.
maxMoveTime
is optional. If specified, the animation will automatically end if this number of milliseconds have passed.
AnimJump(hog, jumpType)
Makes
hog
perform a jump of type
jumpType
, where
jumpType
is one of:
-
"long"
: Long jump
-
"high"
: High jump
-
"back"
: Backjump
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. If
x
and
y
are not specified, gear will not teleport, only the animation is played.
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)
Calls
AddVisualGear
with arguments second to sixth.
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:
-- Make hog1 and hog2 look at each other
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
animation = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hog2}}}}
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:
--[[
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()
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.