Global LensFlare Setup
by Fluen

This tutorial is a thorough and in-depth explanation and reference on setting up and using the LensFlare command in the level editor. For those who don't want to read the full article I have placed a quick 'recipe' on how to set up a working lens flare (written in red) near the end of this tutorial.

To understand this tutorial you must understand how to calculate global coordinates. If you don't, I suggest that you skim through the tutorial 'How to understand and calculate global coordinates' so you can understand and follow this tutorial. You can find that tutorial here:

How to understand and calculate global coordinates

In the following I will use the word 'sun' to describe the sun-looking part (the centre) of the lens flare. It has no connection to the sun used to lighten a level in the level editor.

Similarly I use the compass directions as they appear in-game - see the tutorial 'How to understand and calculate global coordinates' to find a diagram of the correct compass directions.

The command for the global lens flare is:
LensFlare= Y,Z,X,red,green,blue

There are several things to consider before making a lens flare and I shall elaborate on them further below.

Am I done moving my level around in the editor?
Just like the Load Screen, the lens flare is a final touch - unless, of course, you are prepared to do some re-calculating during your level-building.

Is it a 'realistic' sun?
If not, everything is possible and you are mostly on your own. You can even make the lens flare appear below Lara.

From what compass direction should it be visible?
I must warn you that the two most common compass directions for the sun (west and south) are difficult, maybe even impossible to use properly, because of the orientation of the editor and the limitations of the coordinate system.

What time of day is it?
Sunrise and sunset demands a low sun - noon a sun high in the sky. And this factor is decided by the Z-coordinate. But also by the size of the two other coordinates.

What colour should it have?
The colour is determined by the three last coordinates. They work just like the colour settings for all lights in the editor. But the colour of the lens flare is also affected by the colour of the horizon and the Layer1-command.

What rooms should the lens flare been seen in?
Even though Lara is outdoor in several rooms, it might not be desirable to let her see a lens flare in all of them. Especially because the lens flare goes through the textured boxes (walls, floors and roofs that define the limits around your level) in the rooms adjacent to the unused part of the editor world. Use the NL-button (NL means No LensFlare) in the outdoor rooms, where you don't want the lens flare to be visible.

Are there many obstacles (walls and roofs with a density) that might ruin the view?
Once it has passed the outer box, the lens flare is stopped by constructions with a density and becomes pale near them. It might turn so ugly that it is better to turn the lens flare off altogether in that\those room(s).

Do I want to make the lens flare a special experience or just a tool to spice my level?
In Tomb Raider 4 - The Last Revelation, I have found only two lens flares - one in Desert Railroad and one in Coastal Ruins. The one in Desert Railroad is just used to show that it is bright day, while the one in Coastal Ruins gets a presentation in a flyby sequence and sets the atmosphere in that level.
You too must decide if you want to use the lens flare effect sparsely to make a more impressive effect when you finally use it or if you just put it in the sky to indicate what time of day it is. Too much use of it lessens the impression it makes.

Lens flare and compass directions

I have made some quick-lines here both as guidance and as an easy LensFlare-command. The lens flare height above the horizon is approximately the same and the colour of the sun is white in all cases. The lines should be ready for copying and pasting into the script. 

In the middle of everything (exact noon):
LensFlare= 52224,-500000,52224,255,255,255
But you will have to nearly twist Lara's head off to see the sun and not only the sparks in the lens.
North:
LensFlare= 52224,-18750,208896,255,255,255
North-east:
LensFlare= 208896,-30000,208896,255,255,255
East:
LensFlare= 208896,-18750,52224,255,255,255
South and south-east:
LensFlare= 52224,-15000,0,255,255,255
South-west:
LensFlare= 0,-15000,0,255,255,255
West and north-west:
LensFlare= 0,-15000,52224,255,255,255

The X- and Y-coordinate values I have used are the lowest value possible (0), half the size of the level editor window (52224), the whole size of the editor window (104448) and the double size of the editor window (208896).

TRLE accepts huge values in the LensFlare-command (the Z-coordinate for the lens flare in Desert Railroad is -1600000 - that is 6250 clicks above zero level!), but it does not accept negative X- and Y-coordinates - I tried, but the program just ignores the negative sign and places the lens flare according to the positive values. That leads to a problem.

Imagine that you are riding by car or train and watch the trees and houses pass by and disappear in the horizon as you drive on. But the sun in the sky barely moves and only does so by the passing of the day. This is because of the relative distance between you and the things you see.

If you pass a house a few hundred meters\yards away from the road or railroad and take a look at your watch right when you pass it, the house will be 8.3 km\5.2 miles behind you five minutes later if you travel at a speed of 100 km\h (62.5 mph). But the distance between the sun and the earth is almost 150 million km (almost 94 million miles) and your petty travel speed of 100 km\h or 62.5 mph means that you really don't move seen in relation to the sun.

The above situation works better in TRLE concerning the lens flare. If you position your lens flare far out of the editor world, Lara can move around a great deal and the sun will still appear at the same place in the sky. But some of the LensFlare-commands written above contain small coordinates (the ones written in red) and then small changes in Lara's position have great significance.

As an example of this I suggest you make the following changes in your version of the Playable Tutorial Level (make backups of the level and the script first):

1. Enter the Outside1-3 and Outside1-3 Top rooms and press the O-button (the outdoor button, which is a condition to make the lens flare work in all its glory) in every room.
2. Remove the finish-trigger from Outside1, so Lara gets the chance to run around in these rooms.
3. Remove the jeep, so Lara has unlimited mobility.
4. Move Lara to one of the Outside1-3 rooms (optional).
5. Output the wad.
6. Enter the script and add this line (it's ready for copying and pasting):
LensFlare= 33792,5376,30720,255,255,255
7. Convert the new script.

(The block in use is Outside1, X = 32, Y = 29 and Z = -21 clicks - I know the Z-coordinate is below the floor level in Outside1, but the lens flare seems to have a standard raise added to its Z-coordinate, so to get the lens flare down very close to Lara, I lowered it somewhat.)

You should get a very local 'global' lens flare, which Lara is able to run around and examine from most angles. I think it looks funny with a private sun, but it also shows that with coordinates inside the editor world, just a small running around changes the angle of vision of the sun - and if you wanted your lens flare to appear as a sunrise in the east and Lara suddenly sees it in the north, you might be in trouble.

And that is why the south and west side of the editor world works so poorly. You can't get X- and Y-coordinates lower than zero and just moving your level around in the editor window will be enough to change the compass direction the lens flare appears from in-game.

To use the south or south-east lens flare you must place your level:

A. In the right side of the editor window and in the middle between top and bottom to get the southern lens flare.
B. In the right side of the editor window and in the top corner to get the south-eastern lens flare.

To use the west or north-west lens flare you must place your level:

A. In the middle of the editor window and in the bottom to get the western lens flare.
B. In the bottom of the editor window and in the left corner to get the north-western lens flare.

To get the south-eastern lens flare your level must be placed as far right and down in the level editor window as possible - but avoid the bottom right corner itself, as rooms placed there cause a bug, where the textures in the room and adjacent rooms disappear in-game, so Lara appears to be standing 'in the middle of nowhere'

How to set up a lens flare along a specific line - the script part

That is enough about 'preset' lens flares. I want to make a custom-made one. For this purpose and for testing the global lens flare I have made a small park level, where Lara has her private swimming pool\aquarium (I wish I had such a great swimming pool).

And I want the lens flare to be visible along the line of the park gate - this line:

The accentuated line runs along the X=32-line. And that is the only piece of information I need to know. The global X-coordinate is then Xglobal= (32 + 1) * 1024 = 33792.
So right now my LensFlare-command looks like this:
LensFlare= Y,Z,33792,red,green,blue.

As I explained above it works better if the sun is far outside Lara's world to give it a 'global' appearance, and because I have occupied the X-coordinate with the condition about the line from the gate, I am only able to impose this on the Y-coordinate. I choose to use the global coordinate twice the size of the level editor window: Yglobal = 208896.
Now the LensFlare-command is:
LensFlare = 208896,Z,33792,red,green,blue

I have decided that Lara does her swims early in the morning, so the sun is still low in the sky and has a bright yellow colour. And this is where some trial and error gets into the picture.
It is fairly easy to decide the colour setting. I think that the colour (255,255,128) gives the bright yellow I associate with early mornings:
LensFlare= 208896,Z,33792,255,255,128

Then there is the height, which takes the mentioned testing to find the best suited result.

If you are prepared to use trigonometry, it is undoubtedly possible to decide a specific height the lens flare should have at a specific block - just like in the 'private sun'-example I suggested in the Playable Tutorial Level above - and then calculate the Z-coordinate when the lens flare position is twice the distance of the level editor window away. But that must belong to very special situations - like the lens flare seen through a portal.

The height of the lens flare might depend on what obstacles are around the area where it is supposed to appear. A level with high walls or rocks will demand a higher lens flare to get a good view than a flat level (by the beach or in a park like mine).

After some trial and error I settled for a Z-coordinate at -60000, which is high enough to shine through the part of the horizon, where the sky scrolls by and down above the stone fence around Lara's park, but low enough to peek through the grates at the top of the fence and make an impression of an early morning:
LensFlare = 208896,-60000,33792,red,green,blue

Here is the final result:

Good morning, Lara!

By the way: the LensFlare-command is amazingly stable when you think of the many weaknesses the editor has. The levels worked every time in spite of my experiments, where I tried out both negative coordinates, no Layer1-command even though I had a sky, two lens flares in the same level (no, it didn't work) and three Layer-commands (no, that didn't work either). I never encountered any conversion or load problems - the TRLE simply adjusted to a usable version of the script and happily worked on.

And now to the things which must be done in the level itself to make the lens flare work.

How to set up a global lens flare - the level part

If you haven't already done that during your planning of the lens flare and its coordinates, now is the time to select the rooms the lens flare must be visible in - or to think about it if it should be visible in other rooms other than the primary ones.

The lens flare in its full glory is only visible in rooms set to outdoor and only if the adjacent rooms are also set to outdoor. Always,always remember that!

To do that you press the O-button (O means outdoor) in the plan view panel.
If you don't, you will get a pale lens flare (just a sun disc) and all your calculations of global coordinates have no effect on that.

I spent a whole week re-calculating my coordinates and made about sixty different versions of the script while I became more and more frustrated over a gorgeous lens flare in some rooms and just a pale version in others. And all I had needed to do was to switch the outdoor setting on in those rooms!

The outdoor setting is very important to remember in rooms Lara is never going to enter, but sees the lens flare through - such as rooms working as 'horizons' (made to give an impression of more land around the rooms Lara moves in) or 'skies' (rooms above with building roofs, treetops or similar).

In the picture below I have switched the outdoor setting on in the ground rooms, but forgotten it in the rooms above. Near the gate the sun still shines as it did in the picture of the final lens flare, but as soon as the line of visibility goes through one of the top rooms, the lens flare turns pale.

Water rooms are a story of their own. They can't have an outdoor setting because the editor makes it an 'either this or that choice' - if you press one button the other switches off. Fortunately for the beauty of Lara's morning swims in her park, water rooms are affected by the setting of the surrounding rooms.

I haven't found out precisely which rooms must be set to outdoor to make the sun shine through the sides in a water room (I have set them all), so this is a bit of a trial and error. But to make the lens flare shine down through the water surface, it just demands an outdoor setting in the air room above it.

I have used this to send Lara into outer space just for the fun of it (sorry for her lack of appropriate clothing, but I don't have a wad containing a space suit, so I just have to rely on her superwoman abilities).

(It is the same park with a swimming pool and the same lens flare as above - I have just made everything transparent, set the colours in the Layer1-command to (0,0,0) and changed the horizon from Angkor Wat to a TR3-horizon which I had coloured all black.)

But I haven't yet figured out how to make a full lens flare shine into a water room from below. No matter what I did, I only got the pale lens flare.

And then there are the outdoor rooms, where the lens flare should not be seen.

The lens flare has no problem penetrating the first layer it encounters - walls, floors and roofs.

My park level is very small and the stone fence is the limit of it all the way around. The lens flare goes right through that:

I tried to make the wall dense by raising the outermost row of blocks - the lens flare went through anyway. It also went through anything wafer thin inside the level, including portals with toggled opacity and opaque textures.

The same happened when I experimented with a lens flare below zero level. This time the lens flare just shone up through the ground.

This means that you might have to switch the lens flare off in rooms that have a wall directly into the void outside your level if you want to set a low lens flare in an area with a steep landscape. But I suggest you test your level first. Maybe another room cuts in between the lens flare and some of your 'outer rim rooms' and if that's the case, the lens flare might respect the walls it meets.

To turn the lens flare off locally in outdoor rooms press the NL-button (NL = No LensFlare) in the plan view grid. It's the neighbour to the outdoor-button.

Other aesthetic considerations may also have something to say. In the level I am building I have a hall with a broken roof. It looks nice when the noon sun shines into the hall from the hole in the roof:

But less nice when Lara looks up at the sky near the remaining part of the roof:

All the glory of a lens flare comes off and only the sun disc is left when a dense construction gets near the line of sight.

This is a situation, where turning the lens flare off is the only right solution - but that's of course in the eye of the beholder (i. e. the level builder).

Even though the lens flare is able to penetrate the outer box of a level, it behaves more naturally when it gets deeper into the rooms. After all we don't see the sun shine right through walls and roofs in the real world, so the lens flare doesn't do that either.
Deeper in the level rooms the lens flare is stopped by any block with a density - this means pillars, walls made of blocks and roofs and floors made of lowered/raised blocks.

I don't know if it's a coincidence or well planned by the level designers, but in Desert Railroad the roofs of the train wagons are shaped a bit by raised blocks, and Lara can climb in and out of the wagons without seeing the sun in strange places.
How this can be used to make Lara run back and forth between a sunny day and a gloomy building is completely up to the individual level builder.

The lens flare position is somehow connected to Lara's position

The lens flare seems to adjust itself to Lara's whereabouts. Poetically spoken the sun always turns its face towards her. It might be a part of making the illusion of an omnipresent sun more realistic. But if you use a fixed camera and have the lens flare in its view you may see the lens flare move around when Lara does.

Depending on the setup, this behavior may not be noticeable at all or it may ruin a great sequence. So check things out in game and be prepared to make adjustments if it is a problem for you.

This is about all it takes to make a lens flare. Roughly speaking good planning is the most important thing. But there are a couple of things which have the potential to make the use of a lens flare a tricky business.

Troublesome issues

Height versus distance

When the X- and Y-coordinates change they also affect the apparent height of the sun. I'll try to show what I mean with a couple of triangles and squares:

The thick line is the limitation of how far Lara can see. And in each triangle the vertical line represents the Z-coordinate, the horizontal line the overall distance between Lara's position and the lens flare position and the sloped line Lara's line of sight to the lens flare. If you double the distance between Lara and the lens flare and keep the same Z-coordinate you halve the height at which the sun appears when seen in-game. So to make the sun appear at the same height after doubling the distance between it and Lara, you must also double the Z-coordinate.
That is the reason behind the different Z-coordinates in my 'quick lens flare lines' at the beginning of this tutorial. Because the distance between Lara and the lens flare changes with both the X- and the Y-coordinate, I had to adjust the Z-coordinate.

Therefore it is simpler to work with a lens flare along one of either the X- or the Y-coordinate. That way you have 'locked' one of those two coordinates and just have to keep an eye on what changes you make in the other and change the Z-coordinate accordingly.

You will have to be more aware of it if you make a lens flare along a line which slants through the level and uses both the X- and Y-line to get in place.

Lens flare colour versus sky\horizon colour

The lens flare colour is affected by the colour of the horizon, the sky and the Layer1- and Layer2-command.

This particular situation confuses me since I haven't been able to figure out what influences the lens flare the most.

I tried all the skies that came with the editor and the according Layer1-commands on a white version of my early morning sun and could barely see any change - even with the sky and colour from City of the Dead (and that takes place during the night so a lens flare is not likely to appear there):

But strongly coloured horizons seem to make a difference. The following pictures are all made with a white lens flare (255,255,255) in a script where I had deleted the Layer1-command, so the difference in colour was caused by the horizon (a TR3-horizon) only:

This could cause trouble for those who use a TR3-horison and a strongly coloured lens flare. But I am not able to say anything of the degree of the problem.

Personally I think the black sky/horizon reveals the lens flare colour better and I recommend it while testing which colour you want to give your finished lens flare. And a test is easily done by setting the Layer1-command to (0,0,0) and putting the lens flare so high in the sky that it doesn't touch the horizon (if you use a TR4-horizon).

The "recipe" on how to set up a custom-made global lens flare

The script part:

1. Choose the compass direction the lens flare must shine along and be careful about the southern and western directions.
2. Pick one or more blocks lying along the desired compass direction and calculate the global coordinates for the lens flare based on their (X, Y)-coordinates. Think about the magnitude of the distance and what it might do to the perception of height and world corner.
3. Choose a lens flare colour - some testing in a black sky might be a help.
4. Test the height of the lens flare and be careful about its ability to shine through the outer walls of the level.

The level part:
1. Turn the outdoor setting on (the O-button in the plan view panel) if you want the full lens flare and remember to do the same for those rooms Lara isn't meant to enter but to see the lens flare through.
2. Test the level to see if there are places where the lens flare passes through walls and similar or if too many solid blocks make the lens flare flip to and from the full glory and the pale sun disc and turn the lens flare off in those rooms (the NL-button next to the O-button)

Other ideas and crazy suggestions for use of the global lens flare

The global lens flare may be used to give an object a 'glory'. Idea by George Maciver.
In this case you have to be very precise with its position and height.
The formula for calculating the global X- and Y-coordinates based on the X- and Y-coordinates from the editor are:
Xglobal = (X-coordinate from the editor + 1) * 1024
Yglobal = (Y- coordinate from the editor + 1) * 1024
They are the coordinates for the top left corner of the block (the red dot on the picture below).

So to get the coordinates for the centre of the block (the blue dot below) you have to add half a block to the formula:
Xglobal = (X-coordinate from the editor + 1.5) * 1024
Yglobal = (Y- coordinate from the editor + 1.5) * 1024

And to get the coordinates for the bottom right corner of the block (the green dot) you have to add one (1) block to the original formula:
Xglobal = (X-coordinate from the editor + 1) * 1024
Yglobal = (Y- coordinate from the editor + 1) * 1024
These are also the coordinates for the top left corner of the block diagonally below (the purple one).

I will leave you to do the math for a side of the block if that is where you want to place the global lens flare.

Furthermore the lens flare will appear 16 clicks above zero if you use Zglobal = 0. So to get the lens flare down into a precise height you must subtrackt 16 in the formula:
Zglobal = (height in clicks (must be examined closer and forget about any negative sign) - 16) * 256, and add a negative sign to the final value, if the height is above zero level

The remaining adjustment of the global coordinates is a matter of trial and error depending of what you want to use the lens flare for.

Let us all bow to worship Lara the Great!

The pale lens flare is also usable to set a mood
I changed the season and Lara's outfit in my park level and turned it into a grey winter day:

However the pale sun disc doesn't work very well with a scrolling sky because the clouds go behind the sun. In this case a TR3-horizon might be the better choice. And neither the Fog-command nor fog bulbs had any effect as to 'cloud' the sun.

Of course I had to turn the outdoor setting off to get the above effect, so Lara's ponytail/braid was lifeless; but maybe this problem can be circumvented by enclosing the outdoor room(s), where the pale lens flare must be seen, in a series of rooms with no outdoor setting to block the line of sight to the lens flare and thus cause the pale sun. But I have done my share of experiments and leave that to level builders who want to work more with this effect.

The global lens flare works fine in tandem with the local one (the object). They can even appear in the same room.

It's not possible to have more that one global lens flare in a level. When I tried, the TRLE just picked the first LensFlare-command and used it even though I had given them separate numbers like the layer-commands.

This is what I have worked out. If you discover or know something that might be of use, please contact me. I am a frequent visitor at Skribblerz and will be happy to update this tutorial with new information on the global lens flare and ideas as to its use.