Animations in the New Game Engine
by Titak

TRNG - Animation Scripting

Since TRNG is not compatible with TREP, new moves for Lara need to be scripted.

Remember that you have to use NG Center to create the scripts!! Otherwise the new script commands like the Animation= commands will not work in game. In this tutorial I'm assuming you have knowledge about how to change and build your script in NG Center.

You can basically make whatever moves you want for Lara with this script command. It is quite complicated to get things to work flawlessly, however, as with many things, practice makes perfect. Trial and error is often needed to learn how to use the many different conditions that can or need to be set in the Animation= command to make a certain new move work perfectly. 

In this tutorial I'll try to explain the basics of animation scripting. I have also included some scripts to make some of the TREP moves possible.

In General

To make new moves possible for Lara, you need to use the Animation= command in your script.

The general syntax is: 

Animation= AnimIndex, KEY1_ , KEY2_ , FAN_ flags, ENV_ Environment, 
Distance for Env, Extra, StateId or AnimationId array

This command should be placed in the [Level] section. This means that you will have to put the command in every level in your script if you want Lara to be able to perform this move in every level.

As you can see the Animation= command contains several fields divided by commas. The number of fields should stay the same at all times. In several cases you can add more commands/ conditions to one field. The conditions should then be divided by a +. If a field is not applicable you need to put IGNORE in it.

It is wise to view the help file on the Reference tab, show SCRIPT NEW commands, in NG Center for detailed explanations on what the fields mean and what conditions you can put in there. It is best to copy all the text in the green explanation box to a Word document and then print it for better viewing. Read through it carefully, because it tells you a lot about all the different conditions you can set.

Another useful part of the Reference tab is the show _MNEMONIC CONSTANTS for new script commands box. This is where all the conditions that can be used with script commands are listed. When you select one of the constants in the list, a short description of it will appear in the green info box.

What do the Command/Condition Fields Mean?

I've made a short description about the required fields you need to fill in the Animation= command line to give you a bit of a starter. For more detailed information you need to read the help file, as described above. 

AnimIndex
This is the field where you put the number of the animation you want Lara to perform. You can find the correct animation number using WADMerger Animation Editor.

KEY1_
This is where you put the key the player needs to press to make Lara perform the animation. You can put more than one key in this field. So if you want Lara to perform the animation only when the player presses arrow up and jump you need to put KEY1_UP + KEY1_JUMP in this field. In this tutorial I'm only using the default keyboard buttons.
You can also assign other keys, but this requires some extra scripting.

Possible keys for this field are:

KEY1_ACTION
KEY1_DOWN
KEY1_DRAW_WEAPON
KEY1_LEFT
KEY1_LOOK
KEY1_RELEASED
KEY1_RIGHT
KEY1_ROLL
KEY1_UP
KEY1_WALK

Note1: The special value KEY1_RELEASED may be added to the Key1 field to invert key conditions. When KEY1_RELEASED is present, the condition is true only when the specified keys are NOT down.
So you could use this to make Lara perform a certain animation when she is hanging onto something and the player lets go of Action. 

KEY2_
Basically the same as the KEY1_ field but you can only put a small number of keys in this field:

KEY2_DASH
KEY2_DUCK
KEY2_USE_FLARE

FAN_ flags
You can set one or more flags FAN_ to set the behaviour of the animation command.

An example of a FAN_flag is FAN_SET_FREE_HANDS. This flag performs a specific action to inform the game engine that Lara's hands are free and she will therefore be able to hang, climb and pick up objects or weapons.

ENV_ Environment
In the Environment field you can set a single very specific condition about the environment around Lara. You should use this field only when your animation requires a correct environment around Lara like: climbable walls, holes, walls etc.

A few examples of ENV_ Environment conditions are:

ENV_HOLE_FLOOR_IN_FRONT
This ensures that Lara will only perform the animation when there is a hole in the floor in front of her.

ENV_FRAME_NUMBER
This can be used to ensure that the custom move will only start playing when Lara is at a specified frame number of a certain animation. The frame number should be inserted in the Distance for Env field. The animation number (or StateID for that animation) should be inserted in the StateId or AnimationId array field.

ENV_MONKEY_CEILING
This condition is true when Lara is below monkeybars. You can then set the distance to the monkeybars in the Distance for Env field. The value that needs to be typed in the Distance for Env field is calculated with the following formula: MinClick + MaxClick * 256.

For example if you want the condition to be true when the monkeybars are enclosed in range 3 (min) clicks up to 4 (max) click, you'll have to type the value (3 + 4*256) = 1027 in the distance field. (This particular value is actually needed to make Lara perform the ladder-to-monkey move, as shown in the Examples section.)

Distance for Env
In this field you insert the values needed for some of the ENV_Environment conditions. See also some of the examples in the ENV_Environment. 

Extra
This field may host different values in accordance with FAN flags.

StateId or AnimationId Array
After the Extra field you can type one or more values to set State-Ids or Animation indices to use as condition to start your special animation.

For example the following table shows the most important state-ids:

Climbing: $38 , $39, $3A, $3B, $3C, $3d
Falling: $09, $1d
Jumping: $19, $1A, $1b, $1C, $03
Moving on all fours: $50, $51, $47, $48
Rolling: 5
Running: 1
Walking: 0
Monkey: $4b, $4c, $4d, $4e, $4f, $52, $53
Still, stand up: 2

Note 2: The '$' sign means "hexadecimal value". You can use the Windows calculator in scientific mode to convert hex to decimal. You can also type the numbers in decimal but then you have to type the negative number, so animation 164 should be typed as -164. The state-ids or animation numbers you type in this field are used by the engine to determine when your animation is allowed and when it's not.

Examples

I have recreated some of the TREP moves using the script command Animation= to get those moves to work with TRNG, since TRNG is not compatible with TREP. Below are the moves I got to work properly. You may freely use the commands.

I've also explained the conditions I used, so it might help you to gain a better understanding of the use of the various conditions.

Ladder to Monkey

This move allows Lara to grab a monkeybar ceiling above her, when she is on a climbable wall.

Download Animation - this animation was originally created by Geckokid. The script I made works with this animation.

Script command

Animation= 446, KEY1_ACTION + KEY1_UP, IGNORE, IGNORE, ENV_MONKEY_CEILING, 1027, IGNORE, -164 ;ladder to monkey*

446 
This is the animation number of the ladder-to-monkey animation.

KEY1_ACTION + KEY1_UP
To activate the animation you have to press Action and arrow up.

IGNORE
No KEY2_ is assigned, so that's why IGNORE is put in this field.

IGNORE
No FAN_flags are needed so that's why IGNORE is put in this field.

ENV_MONKEY_CEILING
Since it is the ladder-to-monkey move, it should only be performed when Lara is below a monkeybar ceiling.

1027
This is the Distance for Env fvalue to make sure that Lara can only grab the monkeybars when she is right below them. It is calculated with the formula: 256 * MaxClicks + MinClicks = 256 * 4 + 3 = 1027)

IGNORE
No Extra value/condition is needed so that's why IGNORE is put in this field.

-164
This is the animation number of Lara climbing on a wall. It is the animation when she is hanging still with her legs pulled up.

Note that if you use an animation number instead of a StateID, you have to use the negative number!!

Screenshot

180 Degree turn on Monkeybars

This move allows Lara to make a 180 degree turn while hanging still from monkeybars.

Download Animation - this animation was originally created by Geckokid. The script I made works with this animation.

Script command

Animation= 257, KEY1_ROLL, IGNORE, IGNORE, IGNORE, IGNORE, IGNORE, -234 ;180 degree turn on monkeybars*

257
This is the number of 180-degree-on-monkeybars animation.

When you view this slot in WADMerger's animation Editor you'll see that there is actually a very simple turning around animation in there. That's why this slot can be used for this move without having to create extra animation slots.

KEY1_ROLL
To make Lara perform the move, you need to press the ROLL button.

IGNORE, IGNORE, IGNORE, IGNORE, IGNORE
No KEY2_ is assigned, no FAN_flags are needed, no ENV_Environment conditions are needed, no Distance for Env is needed and no Extra values are needed, so that's why IGNORE is put in all these fields.

-234
The number of the animation from which Lara should perform the move.
It is the number of the hanging-still-on-monkeybars animation.

NOTE:
The thing I noticed with this animation is that there's a delay. You need to press the ROLL button for about a second before Lara performs the move.

Screenshot

ROLL IN CRAWLSPACE

Lara can perform a quick roll in a crawlspace, which makes her move forward much quicker than regular crawling.

The animations for it are already present in the Lara object of one of the Revised wads, so there's no need to add it.

Script command

Animation= 218, IGNORE, $4000, FAN_KEEP_NEXT_STATEID + FAN_SET_FREE_HANDS_TEMP, ENV_MULT_CONDITION, 4, IGNORE, -222, -353, -354 
MultEnvCondition= 4 ,ENV_NO_BLOCK_IN_FRONT, 256, IGNORE, ENV_NON_TRUE + ENV_HOLE_FLOOR_IN_FRONT, 512, IGNORE 

What does it all mean?
As you can see you need two different scriptcommands to make this move work properly.

Animation= 
218
Number of the roll-in-crawlspace animation.

IGNORE
No KEY1_ is assigned, so that's why IGNORE is put in this field.

$4000
The hexadecimal value of the Sprint key.
You can also type KEY2_DASH instead.

Note:
The hexvalue of a certain key or condition is listed in the show _MNEMONIC CONSTANTS for new script commands list.

FAN_KEEP_NEXT_STATEID
This will make sure that Lara will go back to the stateID of her kneeling animations.

FAN_SET_FREE_HANDS_TEMP
This makes sure that Lara's hands go back to properly holding her weapons in case you perform this move with drawn weapons. 

ENV_MULT_CONDITION
Since more ENV_Environment conditions are needed you have to use this condition.
It tells the engine to also use the MultEnvCondition= command where all the ENV_Environment conditions will be listed.

4
The number of the MultEnvCondition= command that should be used by the engine.

IGNORE
No Extra value/condition is needed so that's why IGNORE is put in this field.

-222, -353, -354
These are the animationnumber of Lara's kneeling animations.
These are the animation from which Lara can perform the move.

MultEnvCondition=
[B]4[/B]
The number of the command, as assigned in the Animation= command.
The engine will now know to use this MultEnvCondition= in conjunction with the Animation= command.

ENV_NO_BLOCK_IN_FRONT, 256, IGNORE
ENV_Environment, Distance for ENV and Extra field for the conditions to prevent Lara from performing the roll when she is face to face with a wall/block at a distance of less than a block and a half.

ENV_NON_TRUE + ENV_HOLE_FLOOR_IN_FRONT, 512, IGNORE
ENV_Environment, Distance for ENV and Extra field for the conditions to prevent Lara from performing the roll when she is face to face with a hole in the floor which is equal to or deeper than 2 clicks.

So this move cannot be used to make Lara roll out of a crawlspace unless the crawlspace is only one click above the floor.

Screenshot

Ledge Climb Control

This particular TREP patch allows you to add two more StateID's to animation 96 to enable Lara to perform two extra moves when she is hanging from a ledge.

With TRNG and the Animation= scripting you can add as many moves to animation 96 as you want. Needless to say that these extra moves most likely don't exist in the Lara object, so you will need to create your own animations for it.

As an example I've created two script commands and two custom animations which allow Lara to make a jump upwards to, for example, another ledge right above her and to make her jump backwards to a ledge behind her.

Ledge-jump-up

Script command

Animation= 448, KEY1_JUMP, IGNORE , IGNORE, ENV_FRAME_NUMBER, 21, IGNORE, -96 ;ledge jump up*

448
This is the animation number of my ledge-jump-up animation.

KEY1_JUMP
The move is activated by pressing the JUMP button when Lara is hanging still from a ledge (animation 96)

IGNORE
No KEY2_ is assigned, so that's why IGNORE is put in this field.

IGNORE
No FAN_flags are needed so that's why IGNORE is put in this field.

ENV_FRAME_NUMBER
I used this condition to ensure that Lara will only perform the move on the assigned frame of the assigned animation.

21
The frame number from which the move should be enabled. So as long as Lara is NOT at frame 21 of animation 96, she will not perform the move.

IGNORE
No Extra value/condition is needed so that's why IGNORE is put in this field.

-96
Negative value of the animation number from which the move should be performed.

Screenshot

Ledge-jump-backwards

Script command

Animation= 450, KEY1_DOWN, IGNORE , FAN_SET_FREE_HANDS, ENV_FRAME_NUMBER, 21, IGNORE, -96 ;ledge jump backwards*

450, KEY1_DOWN, IGNORE
These first three fields should speak for themselves now.

FAN_SET_FREE_HANDS
I used this FAN_flag so the engine will know that Lara's hands are free and she can therefore grab a ledge or jumpswitch or whatever when she is in midair.

ENV_FRAME_NUMBER, 21, IGNORE, -96
Same as with the ledge-jump-up move.

Roll out of Crawlspace

This move enables Lara to quickly roll out of a crawlspace, instead of turning around first and then crawl out.

Script command

Animation= 421, KEY1_JUMP, IGNORE, FAN_SET_NEUTRAL_STATE_ID + FAN_SET_FREE_HANDS, ENV_POS_HORTOGONAL + ENV_HOLE_FLOOR_IN_FRONT + ENV_POS_STRIP_1, IGNORE, IGNORE, 80

What does it all mean?

421
This is the animation number of the roll-out-of-crawlspace animation. This animation is already present in the Lara objects of the revised wads. 

KEY1_JUMP
The move is activated by pressing the JUMP button when Lara is facing the exit of the crawlspace.

IGNORE
No KEY2_ is assigned, so that's why IGNORE is put in this field.

FAN_SET_NEUTRAL_STATE_ID
From the Reference List of NG_Scripter:
This value forces the engine to change the real state-id number of your animation, replacing it with a neutral state-id. The advantage is to avoid some interference created by tomb4 engine in some circumstances.

(More details are in the Reference section of NG_Scripter.)

ENV_POS_HORTOGONAL + ENV_HOLE_FLOOR_IN_FRONT + ENV_POS_STRIP_1

ENV_POS_HORTOGONAL 
To make sure Lara can only perform the move when she is facing the exit of the crawlspace directly. She will not perform the move when she is in a diagonal position because of this condition.

ENV_HOLE_FLOOR_IN_FRONT
To make sure Lara will only perform the move when there's a hole in the floor in front of her.

ENV_POS_STRIP_1
To make sure Lara will only perform the move when at the edge of the crawlspace, instead of on the entire tile.

IGNORE
The move can take place during the entire in-crawling-position animation, so no framenumber or other extra values needed.

IGNORE
No Extra value/condition is needed so that's why IGNORE is put in this field.

80
StateID of Lara's crawling animation.

Ladder to Crawlspace

This move enables Lara to quickly squeeze into a crawlspace when climbing a ladder. In TR4, you first have to let go of the ladder, quickly grab it again and while Lara is still hanging from her hands (before she pulls up her legs again) you have to press DUCK and ARROW_UP to make her crawl into the crawlspace. With this move you don't have to do all this. All you have to do is keep pressing ARROW_UP and Lara will crawl into the crawlspace.

Script command

Animation= 445, KEY1_ACTION + KEY1_UP,IGNORE, FAN_KEEP_NEXT_STATEID + FAN_SET_FREE_HANDS, ENV_MULT_CONDITION, 2, -164 ;ladder to crawlspace
MultEnvCondition= 2, ENV_WALL_HOLE_IN_FRONT, 8738, IGNORE, ENV_CLIMB_WALL_IN_FRONT, IGNORE, IGNORE ;ladder to crawlspace

What does it all mean?

445
This is the animationnumber of the ladder-to-crawlspace animation.
The animation for this move can be found in a TRC Lara object. 

KEY1_ACTION + KEY1_UP
The move is activated by pressing the ARROW_UP button when Lara has reached the entrance of a crawlspace, while climbing a wall.
Keep ACTION pressed to prevent Lara from falling down.

IGNORE
No KEY2_ is assigned, so that's why IGNORE is put in this field.

FAN_KEEP_NEXT_STATEID + FAN_SET_FREE_HANDS
FAN_SET_FREE_HANDS indicates that Lara's hands are emtpy and that she can therefore do things like climbing, crawling, etc.
More details are in the Reference section of NG_Scripter.

ENV_MULT_CONDITION
More than one ENV_*** is needed in this case, so the ENV_MULT_CONDITION needs to be used.

ENV_WALL_HOLE_IN_FRONT 
Perform the move only when there's a hole in the wall in front of Lara.

8738
This number specifies some conditions of the hole in the walls. It makes sure that Lara will only perform the move when the hole in the wall has the size of a crawlspace (2 clicks high). So when Lara reaches a 1 click high hole, she won't climb into it, and when the hole is 4 clicks high, she will perform her regular ledge climb. See the reference section in NG_Scripter to see how this number was determined. 

ENV_CLIMB_WALL_IN_FRONT
Perform the move only when the wall in front of Lara is climbable. (So the move can only be performed when Lara is on a climbable wall) 

2
This is the number of the ENV_MULT_CONDITION (MultEnvCondition=) that should be used when performing this move.

-164
Lara's climbing animation.

Scripting Tip

Since a lot of the features of TRNG need to be scripted, you'll end up with a very long script block for your level if you use a lot of those scriptable features.

My script isn't that long yet, but even now I'm starting to find it difficult to remember what each line is about, especially with all the animation=commands I'm using at the moment, and the MultEnvCondition= I also need to use for some of the animations.

So I added the name of the animation at the end of the scriptline, using ; before the name, like this:

Animation= 218, IGNORE, $4000, FAN_KEEP_NEXT_STATEID, ENV_MULT_CONDITION, 4, IGNORE, -222, -353, -354 ;roll in crawlspace

MultEnvCondition= 4 ,ENV_NO_BLOCK_IN_FRONT, 256, IGNORE, ENV_NON_TRUE + ENV_HOLE_FLOOR_IN_FRONT, 512, IGNORE ;roll in crawlspace

Animation= 448, KEY1_JUMP, IGNORE , IGNORE, ENV_FRAME_NUMBER, 21, IGNORE, -96 ;ledge jump up

The ; tells the script not to use anything that comes after the ; until you use Enter to go to the next line. The script still works like a charm but it becomes much easier to read what the scriptlines are about exactly.

IMPORTANT

Using Animation= 445 and Animation= 287 in the same level causes a bug with the LADDER_TO_CRAWLSPACE move. So use both of them only if you are using scripting for the TRC style ladder-to-crawlspace move and leaving the default settings for the hanging-to-crawlspace move.