flipeffects.asc

Flipeffects

The Concept

As it was briefly mentioned earlier, flipeffect is a special pre-compiled routine which is called when some non-trivial event occurs.

The concept of flipeffect is somewhat similar to task, i.e. when some flipeffect is engaged, it could be flagged by engine to call every game frame (however, there are primarily one-shot flipeffects present). Such setup is needed for some complex flipeffect events, like flickering lights in TR1 Atlantis (see FLICKER_FX description), which stops automatically after some time.

If flipeffect is flagged to execute every game frame, this flag can only be unset by own current flipeffect code (when its task is done — for this purpose, special internal flip timer is used to count how much time have passed since flipeffect activation) or replaced by any other flipeffect call (however, newly called flipeffect doesn’t necessarily overwrite current flipeffect flag, so you can have one-shot flipeffect executed with another one queued for continuous execution). Ergo, it’s not possible to queue more than one _continuous flipeffect at a time, but it’s possible to have one one-shot and another continuous flipeffect executed every game frame.

Note	Continuous flipeffects are mostly present in TR1 and TR2. In TR3, only two ``legacy'' continuous flipeffects remained, and in TR4 and TR5 there are no continuous flipeffects at all. However, there’s still legacy code that checks if there’s any continuous flipeffect queued.

Complete Flipeffect List

In this chapter, we’ll try to describe each flipeffect for every TR engine version. Given the fact that flipeffect listing changed from version to version, yet retaining common ones, the easiest way to lay them down is to create a table with flipeffect indexes corresponding to each game version.

There are some guidelines to flipeffect table:

• It’s possible that same flipeffect goes under different names in different game versions. In this case, legacy flipeffect name will be preserved (for historical [sic] reasons), and description will point to a flipeffect with more recent name. Legacy flipeffect names would be colored in green.

• Flipeffect names are directly brought from native SDK or debug listings, where available (namely TR1, TR2, and TR4). When native names are wrong (which happens in TR4 and TR5 listings), new ones will be coined. New flipeffect names would be colored in purple.

• It’s possible that legacy flipeffect code could migrate to later engine version without changes, but could be broken due to missing code in another part of engine or changes in internal structures. In this case, flipeffect name would be colored in red.

• If there’s an entry in engine’s flipeffect list, but no actual code for it, it would be marked as (-).

• If actual flipeffect’s purpose is unknown, it would be marked as (?).

• If flipeffect ought to be continuous, it will be marked in bold.

Note

As mentioned here, flipeffect could be called in two ways — either by an entity via AnimCommand, or by trigger action. However, there are certain flipeffect which strictly require caller entity ID to work with (see effect descriptions for that). In such case, if flipeffect is called by trigger action, resulting outcome is undefined in original engine. The most sane way to deal with this situation is to pass an ID of entity which activated given trigger. On contrary, some flipeffects may require certain trigger action and/or certain trigger type to be called at the moment. In such case, if flipeffect is called via AnimCommand, resulting outcome is undefined in original engine.

Index	TR1	TR2	TR3	TR4	TR5
0	TURN180	TURN180	TURN180	ROTATE_180	ROTATE_180
1	DINO_STOMP	FLOOR_SHAKE	FLOOR_SHAKE	FLOOR_SHAKE	FLOOR_SHAKE
2	LARA_NORMAL	LARA_NORMAL	LARA_NORMAL	FLOOD_FX	FLOOD_FX
3	LARA_BUBBLES	LARA_BUBBLES	LARA_BUBBLES	LARA_BUBBLES	LARA_BUBBLES
4	FINISH_LEVEL	FINISH_LEVEL	FINISH_LEVEL	FINISH_LEVEL	FINISH_LEVEL
5	EARTHQUAKE_FX	FLOOD_FX	FLOOD_FX	ACTIVATE_CAMERA	ACTIVATE_CAMERA
6	FLOOD_FX	CHANDELIER_FX	CHANDELIER_FX	ACTIVATE_KEY	ACTIVATE_KEY
7	RAISINGBLOCK_FX	RUBBLE_FX	RUBBLE_FX	RUBBLE_FX	RUBBLE_FX
8	STAIRS2SLOPE_FX	PISTON_FX	PISTON_FX	SWAP_CROWBAR	SWAP_CROWBAR
9	SAND_FX	CURTAIN_FX	CURTAIN_FX	-	-
10	POWERUP_FX	SETCHANGE_FX	SETCHANGE_FX	TIMER_FIELD_FX	TIMER_FIELD_FX
11	EXPLOSION_FX	EXPLOSION_FX	EXPLOSION_FX	EXPLOSION_FX	EXPLOSION_FX
12	LARA_HANDSFREE	LARA_HANDSFREE	LARA_HANDSFREE	LARA_HANDSFREE	LARA_HANDSFREE
13	FLIP_MAP	FLIP_MAP	FLIP_MAP	-	-
14	DRAW_RIGHTGUN	DRAW_RIGHTGUN	DRAW_RIGHTGUN	DRAW_RIGHTGUN	-
15	CHAINBLOCK_FX	DRAW_LEFTGUN	DRAW_LEFTGUN	DRAW_LEFTGUN	-
16	FLICKER_FX	-	SHOOT_RIGHTGUN	SHOOT_RIGHTGUN	SHOOT_RIGHTGUN
17		-	SHOOT_LEFTGUN	SHOOT_LEFTGUN	SHOOT_LEFTGUN
18		MESH_SWAP1	MESH_SWAP1	MESH_SWAP1	-
19		MESH_SWAP2	MESH_SWAP2	MESH_SWAP2	-
20		MESH_SWAP3	MESH_SWAP3	MESH_SWAP3	-
21		INV_ON	INV_ON	INV_ON	INV_ON
22		INV_OFF	INV_OFF	INV_OFF	INV_OFF
23		DYN_ON	DYN_ON	-	-
24		DYN_OFF	DYN_OFF	-	-
25		STATUE_FX	STATUE_FX	-	-
26		RESET_HAIR	RESET_HAIR	RESET_HAIR	RESET_HAIR
27		BOILER_FX	BOILER_FX	-	-
28		ASSAULT_RESET	ASSAULT_RESET	SETFOG	SETFOG
29		ASSAULT_STOP	ASSAULT_STOP	GHOSTTRAP	-
30		ASSAULT_START	ASSAULT_START	LARALOCATION	LARALOCATION
31		ASSAULT_FINISHED	ASSAULT_FINISHED	CLEARSCARABS	RESET_TEST (?)
32			FOOTPRINT_FX	FOOTPRINT_FX	FOOTPRINT_FX
33			ASSAULT_PENALTY_8	-	CLEAR_SPIDERS_PATCH (?)
34			RACETRACK_START	-	-
35			RACETRACK_RESET	-	-
36			RACETRACK_FINISHED	-	-
37			ASSAULT_PENALTY_30	-	-
38			GYM_HINT_1	-	-
39			GYM_HINT_2	-	-
40			GYM_HINT_3	-	-
41			GYM_HINT_4	-	-
42			GYM_HINT_5	-	-
43			GYM_HINT_6	POURSWAP_ON	-
44			GYM_HINT_7	POURSWAP_OFF	-
45			GYM_HINT_8	LARALOCATIONPAD	LARALOCATIONPAD
46			GYM_HINT_9	KILLACTIVEBADDIES	KILLACTIVEBADDIES
47			GYM_HINT_10		TUT_HINT_1
48			GYM_HINT_11		TUT_HINT_2
49			GYM_HINT_12		TUT_HINT_3
50			GYM_HINT_13		TUT_HINT_4
51			GYM_HINT_14		TUT_HINT_5
52			GYM_HINT_15		TUT_HINT_6
53			GYM_HINT_16		TUT_HINT_7
54			GYM_HINT_17		TUT_HINT_8
55			GYM_HINT_18		TUT_HINT_9
56			GYM_HINT_19		TUT_HINT_10
57			GYM_HINT_RESET		TUT_HINT_11
58					TUT_HINT_12

Note	In original engines, all flipeffects which name begins with LARA_ prefix automatically take Lara character as an entity to work with. Also, most flipeffects with _FX postfix are simple sound effect events.

• ROTATE_180 — Rotates an entity 180 degrees around yaw axis and also around pitch axis for underwater cases. Mostly used in Lara roll animations. This flipeffect needs special approach if original animation frames are interpolated, because usually rotation is done on animation transition (e.g., frame 5 of Lara animation 48, which is second and final part of her roll movement). To prevent stray misaligned interpolated frames, this flipeffect must be performed only in the end of frame-to-frame interpolated sequence.

• TURN180 — Same as ROTATE_180.

• LARA_NORMAL — Resets certain internal Lara parameters to default ones, including movement modes, FOV and camera position.

• FLOOR_SHAKE — If entity producing this effect is in less than 8 sector range, send shake effect to camera. Shake effect is a variable which is inversely proportional to entity distance, and, when sent to camera, makes it shake with corresponding amplitude gradually fading out. If there are multiple FLOOR_SHAKE events constantly occuring nearby camera, shake effect won’t accumulate, but rather overwrite previous value.

• DINO_STOMP — Same as FLOOR_SHAKE.

• LARA_BUBBLES — When underwater, emit bubble sound (ID #37) and produce bubble particle for Lara. Position of bubble is linked to model’s last mesh (which is headmesh in case of Lara).

• FINISH_LEVEL — Same effect as TrigAction 0x07 — immediately loads next level. For TR4, (which requires explicit level index to jump), current level index is increased and passed as level index to jump to.

• FLIP_MAP — Equal to TrigAction 0x03.

• ACTIVATE_CAMERA — If there is a trigger type Key (SubFunction 0x03) being queued at the moment, and there are any Camera TrigActions (0x01) present in ActionList, these TrigActions will be forced to activate at a given frame of keyhole entity current animation, rather than at the ending frame of it. Works only for keyhole entities which have complex activation animations, not single-frame ones. It can be used to change camera POV before keyhole animation is finished.

• ACTIVATE_KEY — Same as above, but works for Object TrigAction. That is, any entities to be activated from ActionList will be activated at a given frame of keyhole entity current animation, rather than at the ending frame of it. Can be used to activate entities before actual keyhole animation is finished.

• LARA_HANDSFREE — Functionally removes any weapon from Lara’s hands. If called during holstering or unholstering operation, immediately aborts it. Note that holstering animation won’t be automatically performed, and weapon model meshswaps won’t be swapped back to normal hands.

• DRAW_RIGHTGUN — Swaps given entity’s mesh #10 index with same mesh’s index from PISTOLS_ANIM model (model ID #1 in all TR versions). Calling this effect again swaps mesh #10 back to native. Used primarily in cutscenes to create an illusion of Lara getting pistol in her right hand.

• DRAW_LEFTGUN — Swaps given entity’s mesh #13 index with same mesh’s index from PISTOLS_ANIM model (model ID #1 in all TR versions). Calling this effect again swaps mesh #13 back to native. Used primarily in cutscenes to create an illusion of Lara getting pistol in her left hand.

• SHOOT_RIGHTGUN — Activates given entity’s muzzle flash effect and dynamic light near mesh #10. Muzzle flash position and orientation, as well as effect duration and intensity is hardcoded. Used primarily in cutscenes.

• SHOOT_LEFTGUN — Activates given entity’s muzzle flash effect and dynamic light near mesh #13. Muzzle flash position and orientation, as well as effect duration and intensity is hardcoded. Used primarily in cutscenes.

• MESH_SWAP1 — Swaps all given entity meshes with MESH_SWAP1 model meshes (model ID varies across TR versions). Each mesh is swapped only if source meshswap model mesh is not null, otherwise swap is ignored for a given mesh. Calling this flipeffect again swaps all meshes back to native. Used primarily in cutscenes.

• MESH_SWAP2 — Swaps all given entity meshes with MESH_SWAP2 model meshes (model ID varies across TR versions). Each mesh is swapped only if source meshswap model mesh is not null, otherwise swap is ignored for a given mesh. Calling this flipeffect again swaps all meshes back to native. Used primarily in cutscenes.

• MESH_SWAP3 — Swaps all given entity meshes with MESH_SWAP3 model meshes (model ID varies across TR versions). Each mesh is swapped only if source meshswap model mesh is not null, otherwise swap is ignored for a given mesh. Calling this flipeffect again swaps all meshes back to native. Used primarily in cutscenes.

• SWAP_CROWBAR — Swaps given entity’s mesh #10 index with same mesh’s index from CROWBAR_ANIM model (either model ID #246 in TR4, or model ID #240 in TR5). Calling this flipeffect again swaps mesh #10 back to native. Used primarily in cutscenes to create an illusion of Lara getting crowbar in her hand.

• POURSWAP_ON — Swaps given entity’s mesh #10 index with same mesh’s index from LARA_WATER_MESH model (TR4, modei ID #25). Used in Lara’s waterskin animations used in late TR4 levels with waterskin puzzle.

• POURSWAP_OFF — Swaps given entity’s mesh #10 back to native. Used in Lara’s waterskin animations used in late TR4 levels with waterskin puzzle.

• INV_ON — Hides given entity.

• INV_OFF — Shows given entity, if it was hidden.

• DYN_ON — Turns dynamic lights on for a given entity. Actual result is unclear.

• DYN_OFF — Turns dynamic lights off for a given entity. Actual result is unclear.

• RESET_HAIR — Presumably used to save Lara’s ponytail from potential stuck during cutscenes by resetting all hair parameters to ``identity''.

• SETFOG — When called by trigger action, changes global colour for volumetric fog effect. Takes TriggerSetup Timer field as an index into hardcoded RGB table of colours (see this section for more info). If specified index is 100, engine temporarily turns off volumetric fog effect (possibly, this was used for debug purposes).

• GHOSTTRAP — Kills all the living WRAITH3 entities (model ID #88 in TR4) this way: the wraith starts falling towards given entity. Reaching it or not, the wraith will die if it hits the floor of the room.

• CLEARSCARABS — Removes all swarms of scarabs currently wandering in level.

• KILLACTIVEBADDIES — Disable and remove all active NPCs from level.

• CLEAR_SPIDERS_PATCH — Present only in TR5. It seems it’s same as KILLACTIVEBADDIES, but some other processing is done. Never used in actual levels.

• RESET_TEST — Present only in TR5. No visible or significant effect on gameplay. If there are any NPCs in level, then this flipeffect will fill certain memory zone with zero bytes. This flipeffect seems like last-minute fix-up for some memory leak bug. Used in RICH1.TRC level (The 13th Floor)

• LARALOCATION — When activated, makes Guide NPC (TR4, model ID #37) or Von Croy NPC (TR4, model ID #39) to move to specific AI_FOLLOW object. Takes TriggerSetup Timer field as an index to search for such OCB within AI objects array. When AI_FOLLOW AI object with same OCB index is found, NPC is then directed to this AI_FOLLOW object. This flipeffect also stores this index in additional global variable which is used to prevent NPC to get back to AI_FOLLOW objects with lower OCB indexes that were already passed — for example, if NPC already passed AI_FOLLOW with OCB 2, he won’t return to AI_FOLLOW with OCB 1, even if he hasn’t been there before.

• LARALOCATIONPAD — Same action as LARALOCATION, but with one difference - Timer field is checked for certain values to engage either specific soundtrack and/or cinematic dialogue with Von Croy NPC (for demonstration, look for Angkor Wat level walkthrough). This additional behaviour is hardcoded for TR4’s first level index only.

• ASSAULT_RESET — Resets assault course clock (for ex., when Lara stepped out of assault course).

• ASSAULT_STOP — Stops assault course clock.

• ASSAULT_START — Starts assault course clock.

• ASSAULT_FINISHED — Finishes assault course clock and fixes the record. Depending on record time, plays either unbeat record (I’m sure you can do better'', track ID #24 in TR2) soundtrack or best record (Gosh, that was my best time yet'', track ID #22 in TR2, #95 in TR3) soundtrack. Record time is hardcoded to 100 seconds in TR2 and to 180 seconds in TR3. In TR3, flipeffect also checks if all targets in shooting range were hit by Lara, and if not, applies penalty of 10 seconds for each unhit target. Also, TR3 lacks ``unbeat record'' soundtrack.

• ASSAULT_PENALTY_8 — 8-second penalty for losing track on assault course.

• ASSAULT_PENALTY_30 — 30-second penalty for losing track on assault course.

• RACETRACK_START — Prepare racetrack timer for counting lap time. Only works when Lara is on a quadbike! As soon as quadbike leaves sector with this flipeffect, timer will start counting.

• RACETRACK_RESET — Resets current lap time. Only works when Lara is on a quadbike!

• RACETRACK_FINISHED — Finishes racetrack timer and fixes the record. Only works when Lara is on a quadbike!

• GYM_HINT_1-19 — Sequence of Lara’s voice hints on how to complete gym training. Reason why these are activated via flipeffects rather than normal soundtrack is they must be engaged in predefined order, e.g. voice hint #8 can’t play before #7 was played, and so on.

• GYM_HINT_RESET — Resets gym training progress, so all voice hints will be played once again.

• TUT_HINT_1-12 — Sequence of Lara’s voice hints on how to complete tutorial on Streets of Rome (TR5). Setup is similar to GYM_HINT flipeffects, but seems that there’s no reset flipeffect to restart tutorial.

• RAISINGBLOCK_FX — Plays global sound with ID 117. Used in TR1, Palace Midas.

• CHAINBLOCK_FX — Plays global sounds with ID 173 and ID 33 with predefined interval. Used in TR1, Tomb of Tihocan.

• EARTHQUAKE_FX — Shakes screen violently and plays sounds with ID 99 and 70 globally with predefined intervals. Used in TR1, Palace Midas.

• STAIRS2SLOPE_FX — Plays global sound with ID 119 with predefined delay. Used in TR1, City of Khamoon.

• SAND_FX — Plays global sounds with ID 161, 118 and 155 with predefined intervals. Used in TR1, City of Khamoon.

• POWERUP_FX — Plays global sound with ID 155 for 1 second. Presumably used in TR1, one of the Atlantis levels, but never appears on map.

• FLICKER_FX — Flips alternate rooms back and forth several times with predefined intervals, creating illusion of flickering light. Used in TR1, first room of Atlantis.

• CHANDELIER_FX —  Plays global sound with ID 278 for 1 second. Used in TR2, Bartoli’s Hideout.

• BOILER_FX — Plays global sound with ID 338. Used in TR2, Wreck of the Maria Doria.

• PISTON_FX — Plays global sound with ID 190. Used in TR2, Living Quarters.

• CURTAIN_FX — Plays global sound with ID 191. Used in TR2, Living Quarters.

• SET_CHANGE_FX — Plays global sound with ID 330. Used in TR2, Opera House and Temple of Xian.

• STATUE_FX — Plays global sound with ID 331. Used in TR2, Barkhang Monastery.

• RUBBLE_FX — Plays global rumble sound FX and holds camera shake effect for some time, then finishes it with ``shutting'' sound. {TR4}{TR5} If there are any earthquake type objects in a level, engine engages same behaviour locally for these objects.

• TIMER_FIELD_FX — If this flipeffect is called by trigger action, play global sound FX, taking TriggerSetup Timer field as a sound ID.

• EXPLOSION_FX — Plays global explosion sound (ID #105) and produce full-screen flash graphical FX (TR3-5) or camera shake effect (TR1-2).

• FLOOD_FX — Plays global flooding sound (TR1 — ID #81, TR2 — ID #79, TR3 — ID #163, TR4 — ID #238). Implementation differs from version to version — in TR1 and TR2 looped waterfall sound is used (which is then stopped by an engine after 1 second), while in TR3 and TR4 one-shot sound is engaged.