Hauptseite
Downloads
Handbuch
DRACO patches
eSSe scripting
FAQ
Anti-TREP
Bugs Denkmal
Preset archive
Kontakt

eSSe scripting reference (updated 13 Jun 2007)

Table of contents:

 1. Overview
   1.1. I am italian / french / german / etc. user! Esse isn't working with my PC! What should I do?
 2. Am I limited?
 3. How to edit script and strings file?
   3.1. Script reference
      3.1.1. Graphics
      3.1.2. Gameplay
      3.1.3. Weapon settings
      3.1.4. Objects and traps
      3.1.5. Enemy HP and attack power
      3.1.6. Level-specific inventory item names

1.: OVERVIEW

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:

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.
Under log window there is six options to choose from, divided into two sections:

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 option.

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 know.

1.1.: I AM ITALIAN / FRENCH / GERMAN / ETC. USER! ESSE ISN'T WORKING WITH MY PC! WHAT SHOULD I DO?

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 text:

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.

2.: 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. No more.

3.: 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...

3.1.: SCRIPT REFERENCE
Please note that most of SCRIPT2.TXT parameters will overwrite corresponding native TREP settings.

3.1.1.: Graphics

DD
Drawing Distance. Values are same as in the main TREP window. I. e., by default it's 20480.
Example: DD= 20480

DF
Distant Fog. Values are same as in the main TREP window. I. e., by default it's 12288.
Example: DF= 12288

DFThresh
Distant 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 circumstances:

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.
Example: DFThresh= 20480

VolFX
Sets 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.
Example: VolFX= ENABLED

WUVScroll
Original 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.
Example: WUVScroll= 7

AnimTextInterval
This 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 textures speed.
Example: AnimTextInterval= 5

MistRGB1, MistRGB2
Similar 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.
Example: MistRGB1= C0C0C0

MistSize, MistDensity, MistAmount
Another three parameters for waterfall mist appearance. Similar to corresponding TREP settings.
Example: MistSize= 12

PistolFlashArea, RevolverFlashArea, ShotgunFlashArea, FlameEmitterArea, BlinkingLightArea
Sets effective areas for corresponding dynamic lights. Similar to TREP Light Customizer's settings.
Example: PistolFlashArea= 10

BlinkingLightRGB
Hexadecimal 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.
Example: BlinkingLightRGB= FFC010

3.1.2.: Gameplay

PonytailMode
Sets 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. e. intact).
Example: PonytailMode= 2

HealthAtStartup, AirAtStartup
Overrides level start-up health and air. Similar to corresponding Inventory Customizer settings.
Example: HealthAtStartup= 1000

Gravity
Changes 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.
Example: Gravity= 5

MotorbikeHeadlight
ENABLED or DISABLED. With it, you can disable motorbike headlight in specific levels (if you have motorbike in both day and night levels).
Example: MotorbikeHeadlight= DISABLED

SwimSpeed
Speed 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, etc.
Example: SwimSpeed= 200

AudioPath
This 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 1\Episode 5\%s

MPBarRGB1, MPBarRGB2, 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 to magenta
Example 2: MPBarRGB2=       FF00FF ; sets MP bar fade colour to magenta 
Example 3: MPBarDecSpeed=   30     ; sets MP bar value decrease speed to 30 (max. 127)
Example 4: MPBarIncSpeed=   15     ; sets MP bar value restore speed to 15 (max. 127) 
Example 5: MPBarHPDecSpeed= 100    ; sets HP drain speed to 100 (max. 32767)

3.1.3.: Weapon settings

PistolDmg, UziDmg, RevolverDmg, ShotgunDmg, CrossbowDmg
Sets each weapon's damage. Parameters are similar to TREP's Weapon Customizer weapon table and overrides it.
Example: PistolDmg= 1

PistolRate, UziRate, RevolverRate
Sets each weapon's firing rate. Parameters are similar to TREP's Weapon Customizer weapon table and overrides it.
Example: PistolRate= 9

PistolDisp, UziDisp, RevolverDisp
Sets each weapon's bullet dispersion (accuracy). Parameters are similar to TREP'S Weapon Customizer weapon table and overrides it.
Example: PistolDisp= 5

PistolFlashDur, UziFlashDur, RevolverFlashDur, ShotgunFlashDur
Sets each weapon's gunflash duration. Parameters are similar to TREP's Weapon Customizer weapon table and overrides it.
Example: PistolFlashDur= 1

ExplosiveDamage
Sets explosive weapons (explosive crossbow and grenade gun) damage.
Example: ExplosiveDamage= 30

PistolDisp, UziDisp, RevolverDisp
Sets each weapon's bullet dispersion (accuracy). Parameters are similar to TREP's Weapon Customizer weapon table and overrides it.
Example: PistolDisp= 5

ShotgunShots
Amount of shotgun shots.
Example: ShotgunShots= 6

CrossbowBoltSpeed
Crossbow bolt speed. Useful when swapping weapons in crossbow slot between levels.
Example: CrossbowBoltSpeed= 512

CrossbowFlags, GrenadeFlags
Crossbow 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.
Example: CrossbowFlags= 010203

GrenadeTimeout, GrenadeWeight, GrenadeLaunchPower
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).
Example: GrenadeWeight= 3

GrenadeOneTouch, GrenadeRotation
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.
Example: GrenadeOneTouch= DISABLED

PistolTargDistance, UziTargDistance, RevolverTargDistance, ShotgunTargDistance, GrenadeTargDistance, CrossbowTargDistance
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.
Example: PistolTargDistance= 8192

ShotgunShots
Amount of shotgun shots.
Example: ShotgunShots= 6

3.1.4.: Objects and traps

JobySpikesSpeed
Speed of Joby Spikes object stretching.
Example: JobySpikesSpeed= 3

NormalSpikesTimer, NormalSpikesSpeed
Spikes retraction interval and retraction speed. Useful when creating different spike types for various levels.
Example: NormalSpikesTimer= 64

DartsInterval, DartsSpeed
Darts interval and speed.
Example: DartsInterval= 24

DartsRGB
Darts colour. Note that format is hexadecimal raw string, i. e. you ALWAYS should preserve 6-char length and use hexadecimal colour values.
Example: DartsRGB= 783C14

BoulderGravity
Rolling 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.
Example: BoulderGravity= 6

ConductorInterval
Lightning Conductor interval.
Example: DartsInterval= 24

FallingBlockTimeout, FallingBlockTremble
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.

RaisingBlockHeight
Sets 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.

TwoBlockGoDown
ENABLED 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...

TwoBlockDeprDist, TwoBlockDeprSpeed, TwoBlockReprSpeed
Various settings for two-block platform in OCB 0 mode. Same as with native TREP settings.

3.1.5.: 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.

SkeletonHP, Baddy1HP, Baddy2HP, ScorpionHP, MummyHP, KnightTemplarHP, SphinxHP, SethHP, HorsemenHP, HammerheadHP, CrocHP, MutantHP, GuideHP, Demigod1HP, Demigod2HP, Demigod3HP, TroopsHP, SASHP, HarpyHP, WildBoarHP, DogHP, AhmetHP, BaboonHP, BatHP, BigBeetleHP, VonCroyHP
HPs for all TR4 enemies (except doomed Small Scorpion). Values are same as with native TREP settings, except GuideHP, which is signed integer instead of unsigned.

BaddyUZIDmg, SASMachinegunDmg, TurretDmg, BatDmg, CrocUWDmg, CrocLandDmg, LocustDmg, MummyDmg, BaddySwordDmg, SmallScorpionDmg, DogDmg, SkeletonAttack1Dmg, SkeletonAttack2Dmg, WildBoarDmg, HarpyDmg, ScorpionDmg, HammerheadDmg, KnightTemplarDmg, BigBeetleDmg, SphinxDmg, SethAttack1Dmg, SethAttack2Dmg
Attack power for each TR4 enemy. Values are similar to TREP's Damage Customizer.

3.1.6.: 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:

Uziiiiiiiiiiiiiiiiiiiiiii

Pistolsssssssssssssssssss

Shotgunnnnnnnnnnnnnnnnnnn

Revolverrrrrrrrrrrrrrrrrr

Revolver + LaserSighttttt

Crossbowwwwwwwwwwwwwwwwww

Crossbow + LaserSighttttt

Grenade Gunnnnnnnnnnnnnnn

Shotgun Normal Ammooooooo

Shotgun Wideshot Ammooooo

Grenadegun Normal Ammoooo

Grenadegun Super Ammooooo

Grenadegun Flash Ammooooo

Crossbow Normal Ammoooooo

Crossbow Poison Ammoooooo

Crossbow Explosive Ammooo

Revolver Ammooooooooooooo

Uzi Ammoooooooooooooooooo

Pistol Ammooooooooooooooo
LaserSightttttttttttttttt

Large Medipackkkkkkkkkkkk

Small Medipackkkkkkkkkkkk

Binocularssssssssssssssss

Flaressssssssssssssssssss
Crowbarrrrrrrrrrrrrrrrrrr

Don't worry, you won't get these funny weapon names in game, since SCRIPT.TXT names will be overwritten in ANY WAY.

PistolsName, UzisName, ShotgunName, RevolverName, CrossbowName, GrenadeName
Names for all weapons. As mentioned above, if your game have different weapons in different episodes, you can change their name with these parameters.
Example: PistolsName= Ultra-Cool Guns 2007

RevolverLaserName, CrossbowLaserName
Same names as with standard Revolver and Crossbow names, but with lasersight.
Example: RevolverLaserName= Revolver + LaserSight

PistolsAmmoName, UzisAmmoName, RevolverAmmoName, SGNormAmmoName, SGWideAmmoName, GrenadeNormAmmoName, GrenadeSuperAmmoName, GrenadeFlashAmmoName, XBowNormAmmoName, XBowPoisonAmmoName, XBowExplAmmoName
Names for all ammos.

LasersightName, LargeMedkitName, SmallMedkitName, BinocularsName, FlaresName, CrowbarName
Different 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.