The Torch
by AkyV

Part1 - The Basics

1.1. WHAT IS NEEDED

If you want to use Lara's torch in your level, then you need these things in your WAD - you can find them all for example in the WAD of an original TRLE project, coastal.wad:

a, The torch item (BURNING_TORCH_ITEM). Place it so Lara can pick it up. In this case it won't get into inventory: Lara will hold it in the left hand and you can get rid of it if Lara throws it (by key 'drawing a weapon', i.e. SPACE) or drops it (by drawing a weapon with shortcut keys 1, 2 etc. or choosing a weapon from inventory).

b, The TORCH_ANIM object: it contains Lara's 'left hand with the torch' mesh and some animations to use the torch.

c, The animations 427, 428, 429, 430 and 431 of LARA object to use the torch for ignition.

Note:

You don't want Lara to pick up the torch with SARCOPHAGUS method. (See for example original TRLE project cleopal.prj Room97 to get what this method means.)

1.2. IGNITING THE TORCH

If Lara has the torch in her hand then she can ignite it if she stands close to a triggered flame (an object FLAME_EMITTER or a FLAME_EMITTER2), and holds the torch to that, using key Action (CTRL).
For the successful igniting operation the flame object isn't allowed to be:

a, lower than Lara's soles
b, higher than 1 square (4 clicks) from Lara's soles (with FLAME_EMITTER)
c, higher than 3,5 clicks from Lara's soles (with FLAME_EMITTER2)*

*: 1 click on Floor+/-, Ceiling+/- buttons with the left mouse button (or hitting key Q, A, W, S once) moves the marked effect bulb, light bulb or object with 0,5 click unit. (Doing the same thing with the right button moves them with 4 click units.)

Notes:

1. It should also work with the non-default flames of these objects:

a, FLAME_EMITTER with negative OCB window value (blown flame, igniting the torch at the source of the flame)
b, FLAME_EMITTER2 with OCB window value 1 or 3 (small or very small flame)
c, FLAME_EMITTER2 with OCB window value 2 ('traveling' flame)
d, FLAME_EMITTER2 with OCB window value 123 (flame on the middle of the square - because the default flame of FLAME_EMITTER2 won't be on the middle of the square where the flame object is - as opposed to FLAME_EMITTER - but it will be at the side of the square where the bottom of this 'red pyramid' object - we call the objects like this 'nullmesh' - is.)

But it won't work for other flames (for example, FLAME_EMITTER3).

2. The statuses of these flames (as for Lara):

torch: harmless
FLAME_EMITTER: harmful
FLAME_EMITTER2: harmless

1.3. THE BASIC USING OF THE IGNITED TORCH

You can use the ignited torch mostly for these purposes:

a, Lighting with it in the darkness.
Just think about this situation: Lara doesn't have any flares so she has to find and ignite the torch to see in a pitch dark room.
(Okay, she can also light a bit with the gunflash but what if she doesn't have any weapons? - See 'Lara (Weapons)' FLIPEFFECT triggers.
And, okay, she can also light with binoculars, but we can take that from her as well. - See Equipment script command or 'Inventory Item' FLIPEFFECT triggers.)

b, Igniting flames with it.
In these cases the rules are (mostly) the same just as at igniting the torch: if Lara has the flaming torch in her hand and she stands to a non-triggered flame (an object FLAME_EMITTER or a FLAME_EMITTER2), then she will ignite the flame object with the torch, if she holds the torch to the flame object, using key Action (CTRL). These flame objects must be within 0-4 (0-3,5) clicks vertical distance, but it doesn't matter if they don't have the default OCB window values.
But you have to do one more thing to make this setup work: place one HEAVY trigger on the square of each of these flame objects. The subject of a HEAVY is the flame object on that square.

The non-flaming flame objects are invisible, of course. So, if you want to know whereto Lara holds the flaming torch to ignite this flame object then you have to mark the place of this object somehow. - For example, placing the object to an oil lamp:

c, The ropes in FIREROPE object slot are flammable. If Lara stands to a rope like this with the flaming torch, then the rope will be ignited. (You don't have to use CTRL to ignite. But the torch must touch the rope over the square of the rope so if you don't reach the rope with the torch then jump to it.)
See this example in 'Coastal Ruins' level (original TRLE project coastal.prj Room108 and the adjacent rooms):

d, You can use the torch for the burning floor.

e, You can use the torch for the element puzzle.

1.4. THE TORCH AND THE WATER

a, Lara will never be able to pick up the torch in deep water. (But she will if she's standing in water.)

b, Lara will let the torch go automatically if she falls / dives into deep water. (But she won't if she's standing in water or floating on the surface of water.)

c, If it's not in Lara's hand then the torch will be put out automatically under the surface of water.

Note:

These rules don't work about quicksand. In quicksand rooms the torch will work as on land.

1.5. TAKING THE TORCH IN LARA'S HAND INTO THE NEXT LEVEL

Lara can hold the flaming/non-flaming torch when jumping level. In this case she shows up in the new level with the torch in the hand.
If it's problematic then place another torch item anywhere in this new level.
(If it's still problematic then I think it must be a WAD problem in the new level.)

1.6. ADDITIONAL FEATURES

1.6.1. Putting the torch into/taking it from Lara's hand

You can also give the torch into Lara's hand or remove it from the hand if you use this FLIPEFFECT trigger:

Lara. (Mesh) Torch. <&>Give/Remove Torch to/from hand of Lara

But don't forget about these things when giving the torch with that trigger:

a, The torch won't be flaming just when Lara gets it if

- she hasn't got the torch in her hand before in this level,
- the last torch in her hand wasn't flaming in this level.

b, The torch will be flaming just when Lara gets it if the last torch in her hand was flaming in this level.

c, Don't give the torch to Lara's hand if she just has something (pistols etc.) in it. (In some cases you may try it. For example if she's driving motorbike. But even if it's successful then it can't be ignited or flaming in that position.)

1.6.2. Throwing the torch away

Activating this FLIPEFFECT trigger, Lara will holster the weapons in the hands or throw the flare/torch in the hand:

Lara. (Weapons) Remove weapons or flare from lara's hands

Note:

After a throwing like this Lara's next weapon-drawing must be with shortcut keys or from inventory.

1.6.3. The flame on the torch

You can also ignite/put out the torch (if it's just in Lara's hand) if you use this FLIPEFFECT trigger:

Lara. (Mesh) Torch. <&>Light/Put-Out the Torch in the hands of Lara

Part2 - Advanced Settings

2.1. USING CONDITIONS FOR THE TORCH

You can use the torch for some more purposes if you use conditions for the torch.

2.1.1. Conditions customized for the torch

Use these constants in script:

HOLD_ANY_TORCH: it means the condition is true if Lara just has the flaming/non-flaming torch in the hand
HOLD_FIRED_TORCH: it means the condition is true if Lara just has the flaming torch in the hand
HOLD_OUT_TORCH: it means the condition is true if Lara just has the non-flaming torch in the hand

You can use the constants in GlobalTrigger or MultEnvCondition script commands as conditions.
Let's see two examples:

GlobalTrigger= 1, IGNORE, GT_LARA_HOLDS_ITEM, HOLD_FIRED_TORCH, IGNORE, 1, 2

This GlobalTrigger says if Lara has the flaming torch in her hand then TriggerGroup#1 will happen or else (i.e. if she has a non-flaming torch or other things in the hand or if her hands are empty) TriggerGroup#2 will happen.

MultEnvCondition= 1, ENV_HOLD_EXTRA_ITEM_IN_HANDS, IGNORE, HOLD_OUT_TORCH

This MultEnvCondition defines a condition that is true if Lara has the non-flaming torch in her hand.

You can use this MultEnvCondition:

a, in a CONDITION trigger: 'Multiple condition of <#>MultEnvCondition script command in (E)way'.
b, in an Animation script command - for example:

Animation= 500, 30, IGNORE, FAN_KEYS_AS_SCANCODE, ENV_MULT_CONDITION, 1, IGNORE, -103

So you can start Lara's Animation500 with key A (the 30 means this key - see Keyboard Scancodes list in NG_Center\Reference) if Lara's standing (i.e. if she has Animation103) and has a non-flaming torch in the hand. (Thanks to FAN_KEYS_AS_SCANCODE constant you can use non-TR4 keys to start an animation.)

Notes:

1. 'Lara. (Holds) Lara is holding/driving the <#>item' CONDITION trigger also has those any/fired/out torch conditions.

2. It could also be useful to adjust this general CONDITION trigger for the torch:

'Lara. (Animation) Lara is performing <#>animation': the condition is true if Lara's just performing an animation (marked in window #) of using the torch.

2.1.2. Conditions of the variables used for the torch

For example you want to simulate this thing: 'Lara throws/drops the flaming torch and the current of air - caused by this flying torch - will blow the flame out'. - In this case write this in the Script:

GlobalTrigger= 2, IGNORE, GT_CONDITION_GROUP, IGNORE, 3, 4, IGNORE
TriggerGroup= 3, $2000, 244, $1450, $8000, 80, $12B, $8000+TGROUP_OR, 80, $22B
TriggerGroup= 4, $2000, 199, $0

This GlobalTrigger says if the condition in TriggerGroup#3 is true then TriggerGroup#4 will happen.

; Exporting: TRIGGER(5200:0) for FLIPEFFECT(244)
; <#> : Variables. Memory. Copy to <&>Numeric Variable the (E)Savegame Memory value
; <&> : Local Short Alfa1
; (E) : Lara. Test. Throw out item from the Hands (1 = lara is throwing out item) (Short)
; Values to add in script command: $2000, 244, $1450

This trigger gives data for the condition in TriggerGroup#3, i.e. puts the actual value of window E into Local Short Alfa1 variable.
The window E is a field of Savegame Memory Zone: 'Lara. Test. Throw out item from the Hands (1 = lara is throwing out item) (Short)'. (See more about it in the tutorial in Variables demo project.)
This field is about the actual status of the torch, presenting that with these values:

0: Lara picks up/holds the torch / torch is (in NGLE position/thrown/dropped) on the floor
1: Lara throws the torch by hitting SPACE
2: Lara drops the torch by drawing a weapon (with shortcut keys or in inventory)
3: Lara ignites the torch with the flame / the flame with the torch

; Exporting: CONDITION(43:60) for PARAMETER(80)
; <#> : Local Short Alfa1
; <&> : Variables. The <#>Numeric Variable is = than (E)Value
; (E) : Value= 1
; Values to add in script command: $8000, 80, $12B

; Exporting: CONDITION(43:58) for PARAMETER(80)
; <#> : Local Short Alfa1
; <&> : Variables. The <#>Numeric Variable is = than (E)Value
; (E) : Value= 2
; Values to add in script command: $8000, 80, $22B

The two triggers above examine the value of 'Lara. Test. Throw out item from the Hands (1 = lara is throwing out item) (Short)' in Local Short Alfa1 variable. If it's 1 (because Lara's just throwing the torch) or 2 (because Lara's just dropping the torch) then the condition in TriggerGroup#3 is true. (Thanks to TGROUP_OR constant we can adjust 'OR connection' between $8000, 80, $12B and $8000, 80, $22B.)

; Exporting: TRIGGER(0:0) for FLIPEFFECT(199)
; <#> : Lara. (Mesh) Torch. <&>Light/Put-Out the Torch in the hands of Lara
; <&> : Put out the Torch
; (E) :
; Values to add in script command: $2000, 199, $0

So if Lara's just throwing / dropping the torch then this trigger puts out the flame on the torch.

Notes:

1. Just think about this situation: Lara picks the torch up at the starting point of the level, and she also ignites it there at a flame. Then she carries the torch to the end of the level where she ignites a flame with the torch before finishing the level.
But, what if there's no other flame placed and ignited in the level and Lara throws/drops the torch in the middle of the level? If you used that 'flame-blowing' condition, then Lara picks the torch up again, goes back to the starting point, journeying half the level, and ignites that there again. - But it's a bad level editing, of course.
To prevent this problem disable the Globaltrigger for some points of the level (with 'GlobalTriggers. <&>Enable/Disable the (E)GlobalTrigger' FLIPEFFECT trigger), so the torch won't be put out at those points if Lara throws/drops it. (Saying, for example, the 'blowing feature' won't work there, because the 'blowing feature' will work only in outside areas where 'the wind helps to blow'.)

2. Maybe sometimes you can see flashing some kind of flame in the very foreground of the screen. One of reasons of this is the flaming torch thrown/dropped down - so, in a technical meaning (i.e. to disable this unwanted effect), it's a useful thing to put out the torch.

2.1.3. Mixed conditions

You can mix the customized and variable type conditions of the torch. - See this example:

GlobalTrigger= 3, IGNORE, GT_LARA_HOLDS_ITEM, HOLD_OUT_TORCH, 5, 6, IGNORE
TriggerGroup= 5, $2000, 244, $1450, $8000, 80, $32B

; Exporting: CONDITION(43:56) for PARAMETER(80)
; <#> : Local Short Alfa1
; <&> : Variables. The <#>Numeric Variable is = than (E)Value
; (E) : Value= 3
; Values to add in script command: $8000, 80, $32B

The value 3 means 'Lara ignites the torch with the flame / the flame with the torch' (see above). But we also use a HOLD_OUT_TORCH condition this time, so TriggerGroup#6 will happen only if Lara's just igniting the (non-flaming) torch with a flame and won't if Lara's just igniting a flame with the (flaming) torch.

2.2. 'FREE HAND' FEATURE WITH THE TORCH

Lara can't do some animations if she has the torch in the hand: crouching, catching a ledge etc.
We can do some trick to solve that problem - i.e., for example, we can make Lara catch the ledges with the torch in the hand -, but it may have some risk (i.e. it may mess up some of the adjacent animations), so be careful:

That's what I'm talking about:
Some of Lara animations must have an AnimCommand so-called 'Command3'. If it's not there then maybe Lara refuses to grab the subject of the animation: for example, she refuses to grab a switch in an animation of using a switch. Because without Command3 the game always senses Lara's hands are not free, thinking they are engaged by something - a weapon, for example. - Lucky us, the command won't work if there's really something in Lara's hands. (Because of State-ID of the animation?)
But, if we use that AnimCommand at an animation without that problem then Lara will overwrite the disallowance for the really engaged hands in that animation. It means, for example, she will be able to grab a ledge with a weapon in the hand.

But Command3 (an original TR4 feature) won't work if we want that trick for the torch.
No matter, we can solve it, exporting this FLIPEFFECT as an AnimCommand: 'AnimCommand. Set temporary Free Hands until is performing <&>Animation'. It can do all the things that Command3 can do, moreover, it works for the torch. (The value of window & is the animation where we want to use that AnimCommand. Add the command to any frame of the animation.)

Notes:

1. Just after that tricky animation you can find Lara with a lowered left hand. The torch in the lowered hand is useless, moreover, for example, you can draw weapon now and it means the torch will disappear in Lara's hand.
You can solve the problem if you use 'Lara. (Mesh) Torch. <&>Give/Remove Torch to/from hand of Lara' trigger (see above) just after that tricky animation to raise Lara's hand again (i.e. to give her the torch back).

2. If the torch was flaming just before that animation then that FLIPEFFECT (or any other one) won't help, the flame will be put out when Lara starts the animation.

3. Other methods to adjust 'free hands' for the torch (and other things in Lara's hand):

a, ENV_FREE_HANDS constant for MultEnvCondition or Animation script commands, as a condition.
b, FAN_SET_FREE_HANDS_TEMP constant for Animation script command, as an order.

This tutorial was made using TRNG 1.2.2.6