Shadowgrounds banner


Shadowgrounds Level Editor Menu

 Level Editor Sections How To Use The Level Editor
 Level Editor Home Part 1:Getting Started
 Downloads Part 2:Terrain mode explained
 Installation and Mod Setup Part 3:Scene mode explained
 Creating Missions & Campaigns Part 4:Objects mode explained
 Mission Basics Part 4b:Creating buildings with blocks  
Tutorials Part 5:Buildings mode explained
 Troubleshooting Part 6:Units/Scripts mode explained
Distributing Mods
Part 7:Lights mode explained


Tutorials

Here we will give tutorials on creating various things, such as PDAs or computer screens for your mods. Tutorial list:

* General scripts/missions/locale string information
* How to create dialogue in a mission, part 1: the basics
* How to create dialogue in a mission, part 2: advanced
* How to create a PDA / computer screen log
* Building blocks with different texture sets
* How to set environmental effects like rain or snowfall
* How to create a simple monster spawn
* How to create a multi-purpose trigger
* Sample script for one-press terminal execute
* Sample script for progress bar script


General scripts/missions/locale string information
Before you start creating your mod and reading these tutorials, it is recommended that you read the following general information.

"mission.dhm" (such as mymission1.dhm which is located in \Data\Missions\mymission1\ ) is the file that includes all the scripts for any given mission. The order in which the scripts are included is important but the default order should be ok (and all tutorials have been written with the default order in mind). Normally you don't need to modify this file at all.

"newgame.dhs" is the script that defines which mission is loaded when the player starts a new game. You should check the two lines:
setLoadMissionFile "Data/Missions/mymission1/mymission1.dhm"
setMissionId "mymission1"
Make changes to them if needed.

sp directory in \Data\Missions\mymission1\ is the place for all the script files. All the general scripts and also the conversations script are stored here (but not the actual conversation text).

.dhs and .dhps files are the actual script files. .dhs is the file you want to edit (it's clean compared to the other file). .dhps is the file that the game generates from the .dhs and then uses. The game automatically generates the scripts, no need to worry about that. (For the curious ones, the "precalc" settings are found in \Data\Misc\default_game_options.txt .)

Locales/Common directory in \Data\ is the place for the actual conversation texts. gui_mod.txt file should be used for all non-dialogue texts, meaning user interface texts (mission briefings etc), log files and so on. subtitles_mod.txt should be used for dialogue texts.

"locale string" means a line (or many) of text that are stored in a handy "call signal" so to speak. An example would be "mymission1_01_testing_talk = Testing talk" where the mymission1_01_testing_talk is the string, and Testing talk is the text stored in the string. These locale strings are used in the conversation scripts (mymission1_01_testing_talk), and the full text in the actual conversation text files (mymission1_01_testing_talk = Testing talk). Experiment a little and you'll get the hang of this very quickly.

NOTE: The game always searches for a matching speech file to the locale string. So if your locale string is "mymission1_01_testing_talk", the game will search for "mymission1_01_testing_talk.wav" in \Data\Sounds\Vocals\ (in your Mods\mymod\ directory). Of course, if you don't want to use speech, then don't worry about this. The speech files are not required.

NOTE2: In Shadowgrounds, we used mission01_01_tyler_what_he_says format, in which the first one is the mission number, the second one is the mission dialogue number counter, then the character's name is displayed and finally the first three words of what the dialogue says (those words are not changed even if the dialogue changes). This was very useful and allowed us to keep track of the files easily. (It was also extremely important during the localization process.) Small mods can probably get away with a simpler format.



How to create dialogue in a mission, part 1: the basics
There are a couple of ways to create dialogue. In this tutorial we focus on the easiest: mission triggers that start a conversation. We will make Tyler say a test oneliner.

Please note that this tutorial assumes that your mod's first mission's directory/script name is "mymission1". If this is not the case, keep this difference in mind when you read the tutorial.

Also, be sure to read the general scripts/missions/locale string information above.

Alright, we're all set. Now let's do the easy part and go place a trigger in the Level Editor. Open your map, select the Units/Scripts tab, and browse for C, Trigger, General, x1, 0250cm, Circle, Full, 0. Place this circle on the map - it's the trigger. (There are other sizes too, as you probably already noticed.)

After placing the trigger, select it with a mouse-click. Now check the left-hand sidebar. Choose Triggered script process in the Main dropdown box. . Then click Properties, and a dialog pops up. Select script_name instead of extra_commands1. Now write something like this to the open text area (which should be for the script_name): mymission1_conversation_testtalk and click ok. That's it, you're done with the editor. Save your map and export it.



Now comes the harder part. We are going to do the dialogue in a similar manner as in Shadowgrounds, although only using the simpler method. This might seem a little complex at first, but it will be your second nature after a little while.

The trigger we placed on the map is going to call a script called mymission1_conversation_testtalk. This script starts the dialogue process and uses locale strings to make the final call to the actual conversation texts that are going to be displayed.

The final step is to edit the mymission1_conversations.dhs file which includes the dialogue script (it's in \Data\Missions\mymission1\sp\ ). So, for now you can just copy paste the following:

script mymission1_conversation_testtalk

sub main
start_conversation_single(player1)
set_face_noise(player1, NOISE_RADIO_WEAK)
set_face_animation(player1, idle_normal, expression_calm)
char_say2(player1, mymission1_01_testing_talk)
waitAccurate 5000
end_conversation()
endSub

endScript

That should be it! Now let's start the game (remember to have your mod activated) and see it in action:




How to create dialogue in a mission, part 2: advanced
Ok, so now you should be familiar with the basic dialogue scripting. Let's up the ante and add another character in the mix, to create a proper dialogue. We will use Tyler and Arwyn in this example.

Before a character is displayed properly in the dialogue box, the character must be placed in the mission. So you need to add the character physically to your level. List of characters:

C, Human, Baxter - Ltn. Dan Baxter
C, Human, Jane Arwyn - Jane Arwyn
C, Human, Smith - Roger Smith Place one of these in the level. Then click it again and edit the Properties, and write one of these as the id name:

arwyn
baxter
smith
work in progress...




That's all in the Level Editor. Now let's just get down to the example script first and then explain what it does.
script mymission1_conversation_testtalk2

sub main
start_conversation(arwyn, player1)
set_face_noise(arwyn, NOISE_RADIO_WEAK)
set_face_animation(player1, idle_normal, expression_calm)
set_face_animation(arwyn, idle_normal, expression_calm)
char_say2_wait(arwyn, mission11_08_arwyn_where_are_you)
//waitAccurate 2000
char_say2_wait(player1, mission11_09_tyler_im_in_the_canyons)
//waitAccurate 5000
char_say2_wait(arwyn, mission11_10_arwyn_the_doctor_and)
//waitAccurate 6000
end_conversation()
endSub

endScript


So basically the differences are quite minimal. The monologue conversation (Tyler speaking to himself) is started with start_conversation_single(player1), whereas a dialogue between two characters is started with start_conversation(arwyn, player1). You probably realized that the characters (or their heads to be more specific) that appear in the dialogue boxes are defined in the parenthesis. Tyler is called "player1" and Arwyn is simply "arwyn". Note that they are case sensitive. (It's possible to create new characters but more on that later.)

set_face_noise sets radio noise to the talking head. Note that we only used it for Arwyn - basically Tyler does not need face noise because his speech is not heard through the radio. (So basically Tyler's single monologue in the first example is a bit faulty!)

set_face_animation uses one of the animations. The different faces/emotions aren't really that noticeable but of course it's something to play with. A full list of the animations can be found at... MOREINFO

One of the most important differences between the example dialogues is the use of char_say2 and char_say2_wait. With the first one you also have to use waitAccurate command to set the dialogue box to be on the screen for 2,000 seconds (or you could use wait 2 for 2 seconds also, but waitAccurate is obviously more accurate). The char_say2_wait command will automatically parse the speech file and determine the correct length to show the dialogue box. If it can't find a speech file, then it will make an approximation based on the number of characters in the locale text.



How to create a PDA / computer screen log
Creating a PDA / computer screen log is easy if you follow the steps here.

First, open your map, then go to the Units/Scripts tab. There select C, Item, PDA and click on the place in the map where you want your PDA to appear. Now, click on this location again to select this PDA. Click on Properties in the left sidebar and select item_special_string from the dropdown menu. Now enter something unique in the textbox below. Let's enter "mission01pda01" for this tutorial.

Alternatively, you can select C, Item, Computer screen if you want to place a bright green invisible box to indicate a computer screen log (preferably "attached" to a computer screen in your mission). This invisible box has the same functionality as a PDA item.

Everything you need to do in the editor is done now. You can save and export your map.




Now there will be a PDA / computer screen log in your map that can be picked up / read, but we still need to provide content for this PDA / computer screen log.

Let's assume that your mod only needs to support one language (English in our example). If you want to support multiple languages (called locales), you will place the texts in a different folder, please see the proper documentation for that.

In your mod's Data folder, go to Locales and then Common. Open "gui_mod" in your favorite text editor. Notepad will do, although a more robust editor is recommended. This file should have some text, so just write/copypaste these lines to the end of the file (the location doesn't really matter, though). (Please note that "subtitles_mod" txt file will not work.)

Let's start! You should first create some comment lines by adding 2 slashes in front of it, to make the file better understood by yourself and others if you work in a team. So:

// This is my tutorial PDA!

Now let's add some real content. Just read below what to add, the mission01pda01 needs to be replaced with whatever value you've set item_special_string earlier in the editor. In this case we just use mission01pda01.

// This is my tutorial PDA!
log_entry_desc_mission01pda01 = This is my tutorial PDA
log_entry_type_mission01pda01 = 0
log_entry_style_mission01pda01 = terminal

In the first line you set which title your PDA will have, the other two lines define the style of the PDA. You should change them unless you want to experiment, or create different styles (the styles are defined elsewhere). So for now, just make sure the second one is set to 0 and the third to terminal.

Now on to the readable text. The text is formatted with familiar html tags (but please note that only a select few tags are supported). Also, i and u tags change the color of the font but don't add italics or underline.

// This is my tutorial PDA!

log_entry_desc_mission01pda01 = This is my tutorial PDA
log_entry_type_mission01pda01 = 0
log_entry_style_mission01pda01 = terminal
log_entry_text_mission01pda01
{

<header><img src="Data/GUI/Ingame/Terminals/logo_igto.tga" width="125" height="125" align="left">
<b>Author:</b><br><i>Test person<br>Secret organization</i><br>
<b>Date:</b><br><i>14 May 2006</i><br></header>

<br><br><b>Your first PDA! | Page 1</b>
<img src="Data/GUI/Ingame/Terminals/terminal-line.tga" width="456" height="5" align="left" nowarp="1">

Add your text here.<br><br>
}


Everything between the header tags will be shown in the header of the PDA, normally here you can read the author and date, but you can of course write whatever you want here. In this case we just use the original layout of the PDA. We also use the IGTO logo, but you can also add your own or another logo.

After that we get some kind of title in bold, the text between the b tags. The img tag contains a nice seperator image, and because we keep the original layout we just use the original separator image. Now we can add the message your gamecharacter has entered. We wrote some random stuff just for testing purpose. If all of the above looks too difficult just try to copy paste the text above to your file.

Now save your file and let's have a look ingame! If you've done right it will look like this in the game:



You can also add more pages to the log by using the nextpage tag. Just insert it and all the text written after that will appear on the next page. It's recommended to keep the header formatting as it is, so all the pages look similar... Here's an example:

<nextpage><header><img src="Data/GUI/Ingame/Terminals/logo_igto.tga" width="125" height="125" align="left">
<b>Author:</b><br><i>Test person<br>Secret organization</i><br>
<b>Date:</b><br><i>14 May 2006</i><br></header>

<br><br><b>Your first PDA! | Page 2</b>
<img src="Data/GUI/Ingame/Terminals/terminal-line.tga" width="456" height="5" align="left" nowarp="1">

This is the second test page.<br><br>
}


Please note that all the < and } characters are important to make the file work. If you add a second or more pages to your log, then make sure there's only one { to open the log and one } to end the log.

That's it! Congratulations on creating your first PDA / computer screen log!

Building blocks with different texture sets
When you are creating buildings with the handy building blocks, you might want to use the same blocks with different textures. This is quite easy to do - you can have the same wall with many different texture variations in your object list. Here's a simple tutorial on how to create another set of textures for a building block.

First, you should extract Data3.fbz to a temporary directory and copy \Data\Models\Terrain_objects\Blocks directory to your mod directory (\Mods\yourmod\Data\Models\Terrain_objects\Blocks\ ). Now let's start.

1. Make a copy of the directory where your desired block is located (i.e. Mods\yourmod\Data\Models\Terrain_objects\Blocks\example1 and copy it to Mods\yourmod\Data\Models\Terrain_objects\Blocks\example1_texture2 or so).

2. Delete all the unnecessary stuff, and use the Editor to see which blocks you want to keep.

3. Let's say you want to create a new texture for "blocks_outwall_2_50m" block.

4. Open the file in Notepad or other text editor.

5. You should see some meaningless binary code, but also "concrete_basic_gray_01.dds outerwall_02.dds". These are the texture names.

6. Now, find those files in the game's Data\Textures directory (use search) or from the Data1.fbz file (which can be opened in WinRAR for example).

7. Copy the textures to the new block directory (i.e. \Blocks\example1_texture2\ ), the game prefers the same directory where the model is when it is searching for textures.

8. Edit the copied textures in your favorite editing tool!

NOTE: Do not edit the .s3d files at all - if you try to edit the texture name, the file will become broken.


If you can't open .dds files, download a proper plugin. Nvidia has some plugins for some software, so check out these links: http://developer.nvidia.com/object/dds_utilities.html & http://developer.nvidia.com/object/photoshop_dds_plugins.html (Photoshop plugin works for Jasc Paint Shop Pro, check the page for more information).

If you can't find a plugin for your software directly, download a software that can show the files, for example Irfanview. Then open the .dds in the program, and save it in .bmp. Now you can open the .bmp in your favorite software and edit it - then save it as a .bmp and manually rename the extension to .dds. This "works" but is not recommended because the file size is much larger than a .dds file would be. Of course, if you only have a few textures, this is not a big issue.



How to set environmental effects like rain or snowfall
Shadowgrounds supports several environmental effects. You may have seen Rain in a couple of the original missions. There are a few others, and these effects can greatly enhance your mission. Here is a list of all the effects that are readily available with just a simple script call. As a bonus, a snowfall effect has also been included for modders.

To set an environmental effect in your mission, simply write "setEnvironmentEffectGroup effectgroup" in one of your scripts, such as a dialogue script. Like below:

setEnvironmentEffectGroup Rain
setEnvironmentEffectGroup LightRain
setEnvironmentEffectGroup Sandstorm
setEnvironmentEffectGroup Snowfall
setEnvironmentEffectGroup None


Rain is quite obvious but also includes rainfog and lightnings in addition to normal rain. LightRain is similar but with no rainfog and no lightnings, and there's a bit less rain. Sandstorm is a rather simple but effective sandstorm. Snowfall starts a very nice snow fall with cool flakes. None sets the environmental effect to nothing (basically turns off whatever effect is currently on). There's also fadeEnvironmentEffectGroup, and you may experiment with that on your own. Note that the names are case sensitive - rain will not work but Rain will.

snowfall

Only one environmental effect can be on at the same time. Also, note that each effect also has variations that depend on the user's comfiguration. If the user has Very Low settings, then no environmental effects are used. Low, Medium, High, and Very High feature some kind of environmental effects, and obviously the higher the setting, the better-looking the effect. Also, Weather Effects must be turned on in the Launcher (they are on as default in all settings except Very Low).

To set an environmental effect to start at the beginning of a mission, simply add it to the \Data\Missions\mymission1\mymission1_specials.dhs file, like this:

script mymission1_specials

sub main
// this script will be run right at the beginning of the mission.
// add some script stuff here to start the mission startup cinematic
faded
cinematicScript mymission1_cine_fade_and_zoom_in

setEnvironmentEffectGroup Snowfall

endSub

endScript


If you have trouble with the Snowfall effect but all other effects work ok, there is probably something wrong with your mod's Data directory. As you probably know snow fall was not used in Shadowgrounds and it's not included in the original data files (Data1.fbz). However, snow fall has been added to the sample mod's \Data\Effects\environmental_effect_groups.txt . It should work in your mod, but if it doesn't, then you should check that the file exists and has the snowfall group.

To edit the effects, simply open the file mentioned above and experiment with it.

Note that the effects are somewhat related to the player's position. So when the player moves, the effects follow slightly slower.


How to create a simple monster spawn
Creating a simple monster spawn is fairly simple. The only drawback to this is that we will only be able to spawn one monster per one Level Editor object, so this is not ideal for spawning hundreds of monsters. You can easily spawn ten or more monsters, though, so let's get to it:

We're going to insert an object in the Level Editor and then write a very simple script to activate it.

From the Units/Scripts list, choose C, Triggerpoint, Alien spawn Wrencher. Then choose pre-made settings for Spawnpoint, Alien, Wrencher (near the end of the list). Then click the green Wrencher object, and click Properties. Ignore the id line and choose "trigger_variable" and write "tutorial_spawn1" (we'll use the same name in the script, of course you could use whatever name you want if it's the same in the script).

tutorialspawn

Then you need to create a general trigger, so select for example C, Trigger, General, x1 , 0250cm , Circle Full , 0, place it somewhere on the map, and select Custom main script from the Main scripts drop-down box. Then write "tutorial_spawn_enabled:main" to the custom_main_script box.

tutorialspawn_enabled

Ok, that's all you need to do in the Level Editor. Then go to your mission folder and open the mymission1_specials.dhs file. There's probably some scripts already, so let's make a new script at the end of the file.

script tutorial_spawn_enabled

global int, tutorial_spawn1

sub main
// let's wait until player gets to the trigger area
wait_until_player_closer_than_scriptrange()
// let's output a message just to make sure the script is running
hintMessage "Script is running ok"

// now let's set the variable for the tutorial_spawn1
// so the monster will be spawned
// and let's wait 5 seconds before doing so
wait 5
set_var(tutorial_spawn1, 1)

endSub

endScript


That's it! When the player enters the script's area, and 5 seconds goes by, the monster will be spawned. You can use this for multiple monster spawns as well, simply make more spawn units and give them different names (i.e. tutorial_spawn2, tutorial_spawn3 and so on), and then use the set_var command to enable them (the "1" enables them, "0" is off). Or you can insert multiple spawn units with the same name, in which case they all will be spawned simultaneously.




How to create a multi-purpose trigger
Here we will show how to create a multi-purpose trigger using Custom Main Script.

For example, it's fairly easy to create doors that open when the player arrives to a certain place. So let's do a very simple script that opens a door when the player gets to the trigger zone.

In the Editor, choose C, Trigger, General, x500 and choose Custom main script in the main box. Then click Propertiesand write testmission_trigger1:main in the pop-up box (in the custom_main_script part).

Then let's write a script to the _specials.dhs in the mission directory such as this:

script testmission_trigger1

sub main
// let's wait until player gets to the trigger area
wait_until_player_closer_than_scriptrange()
// let's output a message just to make sure the script is running
hintMessage "Script is running ok"

// now let's open remote door 1
set_var(opened_remote_1, 1)
// then let's wait 10 seconds and close the same door
wait 10
set_var(opened_remote_1, 0)

endSub

endScript


That's it! You can basically do anything in the script, so feel free to experiment.


Sample script for one-press terminal execute
Here's a sample script for a one-press terminal execute. Put a C, Item, Usable object large somewhere in the Editor, click Properties and write testmission_execute1 to the pop-up box in custom_item_script. Then just use this script:

script testmission_execute1

sub execute
// let's disable the item so it can only be used once
disableItem 0
// let's output a message just to make sure the script is running
hintMessage "Script is running ok"

// Let's open for example a door
set_var(opened_remote_1, 1)
// another output message
hintMessage "Door is open"

endSub

endScript





Sample script for progress bar script
Here's a sample script for a progress bar script. Put a C, Item, Usable object large somewhere in the Editor, click Properties and write testmission_execute2 to the pop-up box in custom_item_script. Then just use this script:

script testmission_execute2

sub execute

// let's start a progress bar
startProgress
forceUnitAnimation special8
//// these are just images that are not needed
//// but you can try to experiment with them
// setProgressBarImage "Data/Textures/missing.dds"
// setProgressBarBorderImage "Data/Textures/missing.dds"
setProgressLabel $(testmission_progress_hack)
setProgressDoneLabel $(testmission_progress_hack_done)
setProgressInterruptedLabel $(testmission_progress_hack_terminated)
setProgressTotalTime 9000
setProgressTickTime 500

endSub

sub progress_tick

//// another thing you can experiment with
// if
// getProgressDoneTime
// valueGreaterThan 3000
// then
// set_var(m5_big_attack, 1)
// set_var(m5_start_attack, 1)
// endif

endSub

sub progress_interrupted

// let's stop the player animation
end_forced_unit_animation_for_all_players()

endSub

sub progress_done

//// let's disable the item so it can only be used
//// once and stop player animation
end_forced_unit_animation_for_all_players()
disableItem 0
// let's output a message just to make sure the script is running
hintMessage "Progress bar is done!"

// Let's open for example a door
set_var(opened_remote_1, 1)
// we could start a conversation too, for example
//startScriptProcess conversations_testmission_progressdone

endSub

endScript









Shadowgrounds Level Editor Menu

 Level Editor Sections How To Use The Level Editor
 Level Editor Home Part 1:Getting Started
 Downloads Part 2:Terrain mode explained
 Installation and Mod Setup Part 3:Scene mode explained
 Creating Missions & Campaigns Part 4:Objects mode explained
 Mission Basics Part 4b:Creating buildings with blocks  
Tutorials Part 5:Buildings mode explained
 Troubleshooting Part 6:Units/Scripts mode explained
Distributing Mods
Part 7:Lights mode explained





Hosting provided by Mediatraffic.