eSSe scripting reference (updated 13 Jun 2007)
Table of contents:
1.1. I am italian / french / german / etc. user!
Esse isn't working with my PC! What should I do?
3. How to edit
script and strings file?
Objects and traps
Enemy HP and attack power
Level-specific inventory item names
eSSe is a recent
addition to TREP toolkit small and simple utility with important
purpose: to generate new, custom script and strings file.
The idea of such program was floating around since early days of
TREP cause it's good to edit engine's parameters, but it is much
better, if you can change all these parameters on the
fly. With such advanced scripting TR4 engine becomes
more and more similar to modern game engines, which allow level
builders to create total conversions and outstanding mods. Of course,
such old and primitive engine can't compete with monsters like Source
or Doom III engines, but look there are still lots of custom
games made with Doom I/II, Quake I/II/III engines, and so on. There
are a lot of projects based on old hits like Transport Tycoon (OpenTTD
project), and such games will never get old. I hope that with
new scripting feature TR level editing will become even more fun
and interesting hobby.
Here is the overview
of eSSe main window:
In the top center part
you can see log window, which will deliver to you some details
about script and string file operations like amount of entries
in current loaded script file, size of compiled script, etc.
log window there is six options to choose from, divided into
1. script section:
- alias list: this
option will bring up a list of script entries (aka
aliases). You can use it to see how many options you can
use in your extra script file.
- load: if
you remember old TR4 script, you know that you need file
called SCRIPT.TXT (script draft) that will be later converted
into SCRIPT.DAT. So this option allows you to load plain
text file (SCRIPT2.TXT by default) that can be later converted
into SCRIPT2.DAT file.
- compile: compiles
SCRIPT2.DAT script file. This option will be inactive until
you'll load script draft with previous option.
2. strings section:
- load: as with script,
it will allow you to load string draft text file (STRINGS2.TXT
by default) to convert it into final strings file.
- compile: compiles
strings file. This option
will be inactive until you'll load string draft with previous
Also eSSe supports command
line automation, i. e. you can compile both strings and script
file automatically with only one click. To do this, launch autocompile.bat
file that is supplied with eSSe. Or you can write batch file for
yourself just launch eSSe with -? or /? command
line parameter, and you will get all information that you need to
1.1.: I AM ITALIAN / FRENCH /
GERMAN / ETC. USER! ESSE ISN'T WORKING WITH MY PC! WHAT SHOULD
Most likely, you are
using foreign native strings file. E. g., instead of using common
ENGLISH.TXT / ENGLISH.DAT, you're using ITALIAN.TXT / ITALIAN.DAT.
Tomb4.exe will crash, if you will use such string files just
like this, by simply renaming or deleting original ENGLISH.TXT.
It has completely nothing to do with your locale or language settings!
To overcome this problem,
simply delete all other language filenames
from original SCRIPT.TXT and leave only your language's filename. For
example, that's what you should do in case you're italian user:
Find this text in SCRIPT.TXT:
Replace it with this
Then, recompile original
SCRIPT.TXT to SCRIPT.DAT with SCRIPT.EXE utility, and after
this your game should work normally. There is no need to specifically
recompile SCRIPT2.TXT, cause this bug is not related to eSSe code
or additional script file structure.
AM I LIMITED?
Our Dearest Core Design
Programmers did a great job with creating such hardcoded and straightforward
[sic!] engine, that it took several years to learn how to
create decent levels with it. Some very important parameters were
missing from script file, like drawing distance, distant fog, animated
textures speed, enemy HP, weapon parameters c'mon, it is level
editing after all! Now, when we're approaching more and more
new grounds, there is completely no point in further limitations.
What if soon someone will decide to create game with level-specific
gravity or enemy HP? That's where eSSe can help you.
Just like DRACO module,
new script is not hardcoded to some specific parameters. eSSe allows
to extend script file and add absolutely new script entries of any
type. In combination with DRACO patches, per-level scripting possibilities
are almost unlimited. For you it must mean that new, updated script
entries can appear as frequently as DRACO module updates!
So, if you are more
experienced, you can edit script file structure for yourself. The
thing is, script file is compiled using extra text file that declares
every script parameter's name, type, position, size, and so on.
This file called aliases.txt. Technically speaking, your
SCRIPT2.DAT file is compiled using this another script file!
You also are absolutely
not limited in assigning new strings for your game. Unlike old script,
that allowed you to store only fixed amount of strings, new STRINGS2.TXT
file can store hundreds, thousands of strings it was tested with
1 megabyte-long text file with several thousands of strings.
So the final answer
is: you are now NOT limited, as you were in the early days of TRLE.
HOW TO EDIT SCRIPT AND STRINGS FILE?
First of all, let's
talk about strings file (STRINGS2.TXT). It is plain simple text
file, where each non-commented (with ;
character) and non-empty string
will be compiled and available to engine. But each string in this
file has its own purpose it depends on its index where it will
be used. For example, first 4 strings are used for diary user interface,
next 500 strings are reserved for diary records, and so on. So don't
try to remove some unused strings from the middle of this file,
or else in-game text may be corrupted! Instead, edit existing strings
that are present in sample strings file that is bundled with eSSe.
Now for script file.
You can't use [Title]
or [Options] or any other sections except [Level]
sections with this new script file. To edit parameters for title flyby, use first [Level]
entry in SCRIPT2.TXT. In other part, SCRIPT2.TXT appearance
is somehow similar to SCRIPT.TXT appearance, but, of course, you
CAN'T USE SCRIPT.TXT PARAMETERS IN SCRIPT2.TXT. These two scripts
are completely independent. But you must note that amount of level
entries in SCRIPT2.TXT should be equal to amount of level entries
in SCRIPT.TXT (i. e. if you have 5 levels and one title flyby in
your game, you should have six [Level] entries in SCRIPT2.TXT).
Of course, you also
can add commentaries by typing ; symbol. You can add commentaries
in the end of existing parameter strings or add completely new comment
lines. In both cases, comments won't affect script compilation.
There are about 130 script parameters
available for now, but you don't need to declare all of them for
each level. As with SCRIPT.TXT, if you won't explicitly declare
some parameter, default value will be used. You of course can
edit default value for each parameter in aliases.txt file.
All additional info can be found in commantaries
inside both supplied text files.
Now let's learn which
parameters you can use...
that most of SCRIPT2.TXT parameters will overwrite corresponding
native TREP settings.
Distance. Values are same as in the main TREP window. I. e., by
default it's 20480.
Fog. Values are same as in the main TREP window. I. e., by default
Fog Threshold. This parameter is equal to DD by default, but its
purpose is not to cut-off far polygons, but simply to change distance,
where distant fog becomes most dense. This way, you can simultaneously
set high drawing distance value and low DFThresh value, and
this way receive dense narrow fog WITHOUT polygon cutting-off. This
picture illustrates how DFThresh and DD parameters act in different
Also it helps to overcome
missing save/load item meshes in inventory at extremely dense fog
values. So, it's better to use this trick when you're creating Silent
Hill-like levels with dense fog than simply limiting drawing distance.
volumetric FX on (ENABLED) or off (DISABLED). Absolutely useful
when you want to switch from colored distant fog mode (Vol. FX=OFF)
to fog bulb mode (Vol. FX=ON) on the fly, without exiting TR4 and
re-setting opton in game setup.
SCRIPT.TXT had UVRotate parameter that specified scroll speed, but
only for wall textures. As for waterfall object textures, it was
hardcoded some time ago, but not now. You can edit waterfall scroll
speed with this parameter.
option may be interesting for TRLE users only, since DXTre3D has
perfect animation texture module that allows you to use texture
sequences of any speed and any combination. It changes general animated
to TREP's waterfall mist colour 1 / 2 settings. Note that format
is hexadecimal raw string, i. e. you ALWAYS should
preserve 6-char length and use hexadecimal colour values.
Another three parameters for waterfall mist appearance.
Similar to corresponding TREP settings.
RevolverFlashArea, ShotgunFlashArea, FlameEmitterArea, BlinkingLightArea
effective areas for corresponding dynamic lights. Similar to TREP
Light Customizer's settings.
RGB value for blinking light object color. Note that format is hexadecimal
raw string, i. e. you ALWAYS should preserve 6-char length
and use hexadecimal colour values.
Lara's ponytail mode intact (depends on YoungLara parameter),
single or twin. To force single ponytail, set it to 1, and
if you want twin ponytail, set it to 2. Default is 0 (i.
Overrides level start-up health and air. Similar
to corresponding Inventory Customizer settings.
general gravity. Can be VERY useful when you're making single level
where Lara must go to low-gravity environments (like another planets,
outer space, dream sequences etc.). This parameter is similar to
Physics Customizer's jump gravity and overrides it.
or DISABLED. With it, you can disable motorbike headlight in specific
levels (if you have motorbike in both day and night levels).
of swimming. Maybe in some of your levels you will have pools of
goo, and in another levels it's pure water and this parameter
will help you to improve realism. Or imagine that in one of your
levels Lara will become more powerful and will be able to swim faster,
parameter is very important by means of using more audiotracks and
possibility to assign level-specific audiotracks with same number.
In other words, AudioPath parameter
allows you to use LEVEL-SPECIFIC AUDIO FILES. By default it's set
to audio\%s (it's the default path with \%s
symbols added in the end to mask wav filename), but you can
change it to whatever you want (but you must preserve \%s
in the end of string). This way you can have MUCH MORE THAN 111
AUDIOS in your game, actually, you will be able to use 111 different
audiotracks (or 127, if you've increased it in TREP) for EACH
LEVEL. Can you imagine this?
Be sure you've put all corresponding
audio files in corresponding subdirectories in \audio directory.
For example, if your first level's audiotracks placed in \audio\level
1 directory, you must set this parameter to audio\level
1\%s . You can have many subdirectories with any depth (like
audio\level 1\episode 2\part 6 etc.), but max. path
length is 52 symbols.
Example: AudioPath= audio\Level
MPBarDecSpeed, MPBarIncSpeed, MPBarHPDecSpeed
This set of
parameters will adjust multipurpose bar behaviour (please note that
to use multipurpose bar itself, you must turn on corresponding
DRACO patch). You can change bar main and fade colours (MPBarRGB1
and MPBarRGB2 parameters), decrease and restore speed (MPBarDecSpeed
and MPBarIncSpeed parameters), and also HP drain speed, when multipurpose
bar is empty (MPBarHPDecSpeed parameter).
With all these parameters
you can have unique bars for each new level (for ex., in one level
it can be cold water bar, in other level it can be gas room bar,
in third level it can be outer space oxygen bar and so on).
Example 1: MPBarRGB1=
FF00FF ; sets MP bar main colour
Example 2: MPBarRGB2=
FF00FF ; sets MP bar fade colour to magenta
30 ; sets MP bar value
decrease speed to 30 (max. 127)
15 ; sets MP bar value
restore speed to 15 (max. 127)
100 ; sets HP drain speed to 100 (max. 32767)
RevolverDmg, ShotgunDmg, CrossbowDmg
Sets each weapon's damage. Parameters
are similar to TREP's Weapon Customizer weapon table and overrides
Sets each weapon's firing rate. Parameters are
similar to TREP's Weapon Customizer weapon table and overrides it.
Sets each weapon's bullet dispersion (accuracy).
Parameters are similar to TREP'S Weapon Customizer weapon table
and overrides it.
Sets each weapon's gunflash
duration. Parameters are similar to TREP's Weapon Customizer weapon
table and overrides it.
weapons (explosive crossbow and grenade gun) damage.
Sets each weapon's bullet dispersion (accuracy).
Parameters are similar to TREP's Weapon Customizer weapon table
and overrides it.
of shotgun shots.
bolt speed. Useful when swapping weapons in crossbow slot between
and grenade gun ammo flags. Similar to TREP's Weapon Customizer
settings, but here you can edit it as raw hexadecimal string. You
should preserve six-char length, of course.
Various parameters for Grenade Launcher
weapon. Useful when swapping weapons in Grenade Launcher slot (for
ex., set timeout to 1000, weight to 0 and launch power to 500, and
you will get straight-flying grenade, like in TR2).
These two parameters can be set to ENABLED
or DISABLED. You can disable grenade rotation and enable one-touch
mode if, for ex., you've made TR2-like grenade launcher or rocket
launcher weapon in some of your levels.
UziTargDistance, RevolverTargDistance, ShotgunTargDistance, GrenadeTargDistance,
Targeting distances for all weapons.
You think it's stupid to have it level-specific. You are not right!
Here is an example. Let's imagine you have two levels in your game
one with very dense, narrow distant fog (like in Silent Hill),
and other with fantastic great landscapes and very far viewing distance.
And now imagine that Lara can see an enemy from the same large distance
in the both levels! Very unrealistic. Instead, specify very low
targeting distances in your first foggy level, and you will preserve
suspense and realism.
of shotgun shots.
Objects and traps
of Joby Spikes object stretching.
Spikes retraction interval and retraction
speed. Useful when creating different spike types for various levels.
interval and speed.
colour. Note that format is hexadecimal raw string, i.
e. you ALWAYS should preserve 6-char length and use hexadecimal
ball (aka boulder) gravity. What if different levels in your game
has different gravity and you still want to use same boulders in
all of them? That's where this parameter will help you.
Falling block parameters. What if you'll
decide different falling blocks in different parts of your game?
That's where these script parameters will help you.
height for BOTH raising blocks AND EXPANDING PLATFORM. When applied
to Raising Block 2, specified height will be multiplied by 2. Unlike
TREP, height is NOT specified in clicks, but in raw global coordinate
values, i. e. to use 2-click raising block, set it to 512.
or DISABLED. If set to ENABLED, two-block platform will go down,
not up. Maybe it's not so useful since you have one-block platform
slot for the same action, but who knows...
Various settings for
two-block platform in OCB 0 mode. Same as with native TREP settings.
Enemy HP and attack power
Quite often experienced
level builders uses same enemy slots for different enemies in different
levels. Unfortunately, all parameters were remaining the same with
each enemy, cause all enemy behaviour was hardcoded, thanks to Our
Dearest Core Design Programmers. Now you should be able to change
enemy characteristics on the fly, and this should allow you to create
true different enemies in the same slots.
Baddy2HP, ScorpionHP, MummyHP, KnightTemplarHP, SphinxHP, SethHP,
HorsemenHP, HammerheadHP, CrocHP, MutantHP, GuideHP, Demigod1HP,
Demigod2HP, Demigod3HP, TroopsHP, SASHP, HarpyHP, WildBoarHP, DogHP,
AhmetHP, BaboonHP, BatHP, BigBeetleHP, VonCroyHP
all TR4 enemies (except doomed Small Scorpion). Values are same
as with native TREP settings, except GuideHP, which is signed integer
instead of unsigned.
TurretDmg, BatDmg, CrocUWDmg, CrocLandDmg, LocustDmg, MummyDmg,
BaddySwordDmg, SmallScorpionDmg, DogDmg, SkeletonAttack1Dmg, SkeletonAttack2Dmg,
WildBoarDmg, HarpyDmg, ScorpionDmg, HammerheadDmg, KnightTemplarDmg,
BigBeetleDmg, SphinxDmg, SethAttack1Dmg, SethAttack2Dmg
power for each TR4 enemy. Values are similar to TREP's Damage
Level-specific inventory item names
It's important to
mention that level-specific item names was one of the most requested
features for new script file. Why? The reason is simple episodic
level series with different weapons in each of episode. Remember
Lara at the Movies do you remember these ugly weapon names, like
«Pistols / Laser Beam / Knife / Hell-If-You-Know-What»?
No more. You can specify different weapon and item names for EACH
LEVEL, i. e. it is even better than in TR5, where you was only able
to switch between two weapon names.
Here is one important note
about new item names. Since now, you should edit corresponding weapon
/ item names ONLY IN SCRIPT2.TXT FILE, because old ENGLISH.TXT strings
will be overwritten in any case. Also, due to crappy nature of TR4
engine and script file format, you must maximize old ENGLISH.TXT
item names to 25 characters. It is needed to reserve space for alternative
item names, and the maximum length for these names is 25 symbols.
In other words, go to ENGLISH.TXT file and convert all corresponding
item names to something like this:
Don't worry, you
won't get these funny weapon names in game, since SCRIPT.TXT names
will be overwritten in ANY WAY.
ShotgunName, RevolverName, CrossbowName, GrenadeName
for all weapons. As mentioned above, if your game have different
weapons in different episodes, you can change their name with these
Ultra-Cool Guns 2007
Same names as with standard Revolver and
Crossbow names, but with lasersight.
Revolver + LaserSight
UzisAmmoName, RevolverAmmoName, SGNormAmmoName, SGWideAmmoName,
GrenadeNormAmmoName, GrenadeSuperAmmoName, GrenadeFlashAmmoName,
XBowNormAmmoName, XBowPoisonAmmoName, XBowExplAmmoName
for all ammos.
SmallMedkitName, BinocularsName, FlaresName, CrowbarName
item names. For ex., if in one part of your game Lara have knife
in her crowbar slot, and in the next level she uses something else
in the same slot, you can change its name.