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
.
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.
By convention, a cut scene in a singleplayer mission should be skipped when the player presses the Precise key. In this case, use the
onPreciseLocal
callback for this.
Example:
function onPreciseLocal()
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)
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
.
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. 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:
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.