Master commands
 
These are the main commands in SinScript. Their role is mainly to handle thread flow control and general purpose functions (gameX86 source code reference: scriptmaster.cpp). They all share a common syntax trait: they are always typed at the beginning of the command line before any command arguments (when applicable). There is only one command which can stray from this rule: thread.

As an optional syntax variant, the thread command will accept the $targetname of an actor entity before the command itself. This will make the actor own the thread called by the command.

Master commands are colored in orange in my custom SinScript syntax coloring wordfile for UltraEdit32.


airclamp  
 
Function
 
Toggle command. This sets whether the player's has airborne movement control or not in deathmatch mode. Default is on.

Syntax
 
airclamp 0|1

Notes & examples
 
airclamp 0 : airborne control off
airclamp 1 : airborne control on


cachemodel
 
Function
 
Pre-caches a model file to avoid unnecessary delays in the game when those need to be displayed.

Syntax
 
cachemodel "<modelname>.def"

Notes & examples
 
This command is normally used in a thread named 'precache' which is placed at the very end of the script. This thread is automatically called when the map loads. The implicit directory for models is 'base/models'.


cachesound
 
Function
 
Pre-caches a .wav file to avoid unnecessary delays in the game when those need to be played.

Syntax
 
cachesound "<path>/<soundname>.wav"

Notes & examples
 
This command is normally used in a thread named 'precache' which is placed at the very end of the script. This thread is automatically called when the map loads. The implicit root directory for sounds is 'base/sounds'.


cinematic
 
Function
 
Tells the script that the following is a cinematic sequence and places the game in cinematic mode.

Syntax
 
cinematic

Notes & examples
 
The opposite of this command is noncinematic.


clearscreenprintfile  
 
Function
 
Clears the output of the previous screenprintfile command from the screen.

Syntax
 
clearscreenprintfile

Notes & examples
 

crucialdialog  
 
Function
 
Executes an on-screen character dialog. This does the same thing and works exactly the same way as the dialog command except that the dialog text, icon and sound will be seen and heard even if the dialogs are set to off in the game options menu. The dialog will also play even if the jc_not_hearable command was issued previously.

Syntax
 
crucialdialog "<icon_name>" "<text_string>" "<path>/<soundname>.wav"

Notes & examples
 
This should be used when a dialog contains information crucial to the player such as a clue to solve a puzzle or an important warning.


cuecamera
 
Function
 
Camera view switching command. This sets the game view on the screen to the current location and pointing angle of the func_camera entity invoked in the command. The game view remains tied to that camera until the next cuecamera command (switching to another camera view) or a cueplayer command (switching to the actual player's view).

Syntax
 
cuecamera $<camera_name>

Notes & examples
 
For fixed camera shots, it is common practice to move a camera to the required location, fix its position (unless you want to use follow mode) and point in the right direction before cueing it. IOW, all this is done while another camera in the map or the player's view is cued.

For moving camera shots, the usual method is to preset the pointing direction and mode of the camera (none, lookat or watch), issue the needed displacement commands (move, follow or orbit) and cue the camera immediately afterwards. Afterwards, the pause and continue commands can be used to interrupt and resume the camera's movements as required. The stop command will stop the camera from executing the previous move, follow or orbit command altogether.


cueplayer
 
Function
 
Switches the game view back to the player's point of view if the current view is a camera view. Useful in maps where cinematic sequences are intermixed with interactive player action and the game view needs to be changed from a camera view to the player's view.

Syntax
 
cueplayer

Notes & examples
 

dialog
 
Function
 
Executes an on-screen character dialog. This does 3 things: display the icon of the character who's talking at the bottom left of the screen, display a box next to the icon containing the printed text of what the character is saying and playing a .wav file of the character's comments.

Syntax
 
dialog "<icon_name>" "<text_string>" "<path>/<soundname>.wav"

Notes & examples
 
The icon name refers to a graphic icon in the pics folder of the game PAK file. These icon pics are always named: "i_<character's_name>"

Although the dialog command can be used anywhere in the main script, it is common practice to place all of the map's dialogs inside individual threads in an external dialog script file. Whenever a thread from an external file is called, the :: notation must be used.

The dialog is then called with the following command in the main script:

thread dialog::<thread_name>

Please not that for dialog threads to work when called this way, you must set the dialog script file to refer to at the beginning of the script with the setdialogscript command.

Note:
The output from the dialog command will only be seen and heard if the dialogs are enabled in the game options menu. Similarly, if the jc_not_hearable command was issued previously, the dialog will NOT be seen or heard either. For crucial dialogs that must absolutely play regardless of the dialogs setting in the game options or the jc_not_hearable command, use the crucialdialog command.



dialogsound  
 
Function
 
This simply plays a sound that can be heard by the player wherever he is in the map.

Syntax
 
dialogsound "<path>/<soundname>.wav"

Notes & examples
 
The sound played by this command will only be heard if the dialog sound is enabled in the game options menu. It will not be heard if the jc_not_hearable command was issued previously.


end
 
Function
 
Mandatory thread syntax requirement which tells the script that a thread has ended. All threads must be terminated with an end command.

Syntax
 
end

Notes & examples
 
The end command is absolutely essential at the end of a thread regardless of whether the execution of the commands in the thread can reach the end command or not (some threads loop continuously and never really end). Omitting this command can cause a thread to be incapable of running when called.


fadein
 
Function
 
Produces a cinematic fade-in effect in the player's view.

Syntax
 
fadein <fadein_time> <Red_value> <Green_value> <Blue_value>

Notes & examples
 
<fadein_time> is the duration in seconds of the fade-in effect. The following 3 values is the RGB value of the color to fade in from. For example, 0 0 0 means black and 1 1 1 means white.


fadeout
 
Function
 
Produces a cinematic fade-out effect in the player's view.

Syntax
 
fadeout <fadeout_time> <Red_value> <Green_value> <Blue_value>

Notes & examples
 
<fadeout_time> is the duration in seconds of the fade-out effect. The following 3 values is the RGB value of the color to fade out to. For example, 0 0 0 means black and 1 1 1 means white.

Note:
Do not confuse this command with the fadeout Entity command. It is an entirely different command with a different function even though it has the same name.


forcemusic  
 
Function
 
This forces a .wav file alias name from the currently set .mus file to play regardless of the current action in the game.

Syntax
 
forcemusic <wav_aliasname>

Notes & examples
 
For more information on the possible .wav file alias names to use, refer to the music command.


freezeplayer
 
Function
 
This will freeze all the player's movement controls so he can't move or look around in the game during a cinematic sequence. This command is used at the beginning of a cinematic sequence right after the cinematic command.

Syntax
 
freezeplayer

Notes & examples
 
This command only works when the game is in cinematic mode. To un-freeze the player's controls, use the releaseplayer command.


goto
 
Function
 
Makes the thread execution jump to a label line which can be located anywhere in the script. The goto command can also point to the name of the thread in which it's located since a thread name is followed by a colon and counts as a label too. It can point to the name of another thread as well. Useful for controlling the order of execution of commands within a thread, jumping to another thread and making threads loop continuously.

Syntax
 
goto <label_name>|<thread_name>

Notes & examples
 
Label lines, like the first line of a thread definition, must always be followed by a colon (:).

Example of use of the goto command:

example1_thread:
goto camera2_shot
camera1_shot:
cuecamera $camera1
wait 6.8
goto end_of_thread
camera2_shot:
cuecamera $camera2
wait 15.2
goto camera1_shot
end_of_thread:
end

In the previous example, the goto commands are used for the sole purpose of inverting the order of execution of the camera1 and camera2 shots.

Note:
In practice, the above thread is unnecessarily convoluted and not a very efficient way to do things. I just wrote it that way to illustrate what the command does.


Example of the typical use of a goto command after a variable conditional test:

example1_thread:
local.playcount = 1
play_it_again_sam:
cuecamera $camera1
wait 6.8
cuecamera $camera2
wait 6.8
local.playcount += 1
local.playcount ifnotequal 3 goto play_it_again_sam
end

In this example, the thread will make the game the view cue to camera1, remain 6.8 seconds in that view, then cue to camera2 and remain there for 6.8 seconds. Since the first time around, the value of local.playcount will be 2 (therefore not equal to 3), the conditional test will return "true" and the "goto play_it_again_sam" will be executed. This will make the camera cueing command be executed a second time. Afterwards, the value of the variable local.playcount will be incremented to 3 which will make the conditional test return "false" and the goto command will not be executed. The thread will then be able to move on to the next command which ends its execution.

Important distinction: although the goto command can be used to jump to the beginning of another thread, a goto <thread_name> is not the same thing as a thread <thread_name> command. Here are 2 examples using the same threads:

Jumping to another thread using the goto command:

camera1_thread:
cuecamera $camera1
wait 6.8
goto camera2_thread
$camera1 playsound "weapons/camgun/newmix.wav"
end

camera2_thread:
cuecamera $camera2
end

In this example, the thread will execute the "cuecamera" and "wait" commands. Then the following "goto" command will jump straight to "camera2_thread:" and the "$camera1 playsound" command in the first thread will not be executed (the sound won't be played). The second thread will terminate but the first one will remain open indefinitely.

Calling another thread using the thread command:

camera1_thread:
cuecamera $camera1
wait 6.8
thread camera2_thread
$camera1 playsound "weapons/camgun/newmix.wav"
end

camera2_thread:
camera2:
cuecamera $camera2
end

Now in this example, the thread will execute the "cuecamera" and "wait" commands just like in the previous example. BUT, unlike in the previous example, the following "thread" command will call the thread "camera2_thread:" and then execute the "$camera1 playsound" command. At the same time than the sound is played, the command in "camera2_thread" will also be executed. In this case, both threads will be able to terminate.

The main difference is that a "goto" just causes the execution of the commands to jump to a specific place in the script. A "thread" command starts a new thread of execution which runs independently of the thread from which it was called.


hud
 
Function
 
Toggle command. Determines whether the player's hud is displayed on the screen or not.

Syntax
 
hud 0|1

Notes & examples
 
hud 0 : hud off
hud 1 : hud on


intermissionlayout  
 
Function
 
This tells the game to display a layout string on the the intermission screen between 2 levels in SP mode. This command should be used inside a thread named "LevelComplete" in the script.

Syntax
 
intermissionlayout "<layout_string>"

Notes & examples
 
The "LevelComplete" thread is called by default when the player touches the trigger_changelevel trigger in the map. This is the reason why the command should be used inside that thread. There is an excellent example of the use of this command in Ritual's script for the "SinTek Chemical Plant security" level: chem1.scr.

The function of this command is basically the same as the loadintermission command. The difference is that this command uses a layout string as its argument, the loadintermission command uses a layout file as its argument. A layout file is a text file which contains layout strings.


jc_hearable  
 
Function
 
This re-enables the game dialogs if those were previously disabled by the jc_not_hearable command.

Syntax
 
jc_hearable

Notes & examples
 
This command will not re-enable the dialogs if those were turned off in the game options menu.


jc_not_hearable  
 
Function
 
This command will prevent the normal game dialogs from being played. It disables the output of the dialog and dialogsound commands but it does not disable the output of the crucialdialog command.

Syntax
 
jc_not_hearable

Notes & examples
 
To re-enable the dialogs in the game, use the jc_hearable command.


killclass  
 
Function
 
This will kill all the entities in the game that belong to common server classname. Only works with living things: players, actors and all sentients. Those will play their usual death animation and die.

Syntax
 
killclass <server_classname>

Notes & examples
 
This command will not work with non-living things such as plain objects. To remove those types of entity classes, use the removeclass command instead.

The argument required for this command is the server classname of the model. Do not confuse this name with the entity's classname in SinEd. In order to determine the server classname of a particular entity, open that entity's .def file with a text editor and look for a command that goes:

server classname <name>

The <name> in the command is what you must use as the argument for the killclass command. Typically (for sentients), it should be something like "actor", "monster", "animal", etc.


killent  
 
Function
 
This will kill any entity in the game. It does the same thing as the killclass command when used on living things. But unlike the killclass command, it can be used on non-living things as well. This will simply remove them from the game the same way as if you had used a removeent command.

Syntax
 
killent <entity_number>

Notes & examples
 
This command cannot use the entity's targetname (preceded by a $) as its argument. It requires the entity's sequence number but the * in front of the number is omitted. Determining the sequence number requires turning on the sv_showentnums option at the game console prompt:

sv_showentnums 1

This will display all the entity's sequence number over them in the game. However, in order for this option to work, you need a 3D card which has a real OpenGL driver (Glide and 3Dfx GL mini-drivers are NOT real OpenGL drivers). This will work no problem with a TNT or TNT2 card.

It can be made to work with a Voodoo2 card using 3Dfx's Beta 1.2 OpenGL driver (Warning: very unstable - use at your own risk). To install the driver, extract the file named 3dfxopengl.dll from the .exe archive and copy it to your game's Sin folder. Rename it to opengl32.dll (backup any existing file by the same name first).

However, this cannot be made to work with Voodoo, Voodoo Rush, Banshee, Matrox G200/G400 or Voodoo3 cards since there are no real OpenGL drivers available for them (yet).

Fortunately, there is a much more convenient and easy way to kill an actor in the game which lets you refering to it by its targetname instead. For this, I suggest you use the hurt entity command.


loadintermission  
 
Function
 
This tells the game to display a layout file on the the intermission screen between 2 levels in SP mode. This command should be used inside a thread named "LevelComplete" in the script. The command assumes it root folder as "base/layouts" and the file extension is omitted in the command.

Syntax
 
loadintermission "<layout_file_name>"

Notes & examples
 
The "LevelComplete" thread is called by default when the player touches the trigger_changelevel trigger in the map. This is the reason why the command should be used inside that thread. There is an excellent example of the use of this command in Ritual's script for the "SinTek Chemical Plant security" level: chem1.scr.

The function of this command is basically the same as the intermissionlayout command. The difference is that this command uses a layout file as its argument, the intermissionlayout command uses a layout string as its argument. A layout file is a text file which contains layout strings.


loadoverlay
 
Function
 
This is used to overlay a layout file on the normal game screen. The layout file contains the layout string commands for the overlay. A typical example of an overlay file is the border lines and blinking "record" text you can see on the screen when you look through a security camera view.

Syntax
 
loadoverlay "<overlay_filename>"

Notes & examples
 
If you make custom overlay files, it's recommended to put them in the 'base/layouts' folder of the game. Ritual supplies both a high and low resolution version of each standard overlay file. Both files have the same name but the hi-res file has a .hdh extension and the low-res a .hdl extension. Please note that the file extension is omitted in the command.


map
 
Function
 
Switches the game to a new map by loading a .bsp file.

Syntax
 
map <bspfile_name>$<playerstart_name>

Notes & examples
 
This is exactly the same as the well known game console command. The .bsp file extension is omitted. The $<playerstart_name> option can be used when there are 2 or more info_player_start entities in your map. It's the targetname of that info_player_start entity and determines where the player will spawn in the map. Don't put a space between the map name and playerstart name.

Please note that if you place 2 or more info-player_start entities in the same map, you must give each of them a targetname.


menu
 
Function
 
This will freeze the player's movements and brings up the content of a menu file on the screen the same way as if he would be using an in-game console. The menu items can be scrolled through and selected the same way as in a normal console. Hitting the esc key will unfreeze the player's movements and clear the menu from the screen.

Syntax
 
menu "<menu_file_name>"

Notes & examples
 
The menu filename must have the .mnu file extension. The file extension is omitted in the command. .


missionfailed  
 
Function
 
This will print the text "Mission Failed" on the center of the screen, wait for a second or so and bring the player the loadgame menu. This is used in the script when you want to force the player to re-start the game or re-load the last saved game because he failed to accomplish a task essential to the completion of the map.

Syntax
 
missionfailed

Notes & examples
 
Please use this command sparingly and with careful planning. A while ago, I have seen an example of an amateur SP map where this was used in the worst possible way...

Try to reserve this for mission objectives which absolutely essential to the successful completion of the map or something the player absolutely needs to accomplish in preparation to the following maps.

OR, if you use it for less important mission objectives, at least, give the player a decent chance to attain it. Saving a hostage in an "impossible odds" situation hardly qualifies as a being a reasonable "essential mission objective".

It's a simple question of balance: if he's low on weapons, give him more ammo. If he's low on ammo, give him a more powerful weapon. If he's low on both, give him enough time and health to "duke it out" the hard way. His opponents also have to proportionned to the player's current health, weapons and ammo status. But if take everything away from him, this is not a challenge, it's plain stupid and total lack of judgment.

When used inappropriately, this command can become the worst possible source of frustration for a player.


music
 
Function
 
This tells the game what .wav file alias name to play from the currently set .mus music configuration file for the map. All the .mus files are plain text files which contain aliases which point to a .wav file to play in the game based on the current type of action. These files are located in the game's "base/music" folder.

Syntax
 
music <wav_aliasname>

Notes & examples
 
The available alias names vary from one .mus file to another. To determine the actual choice of aliases for the .mus file set for your map, you must open the .mus file with a text editor and browse through the list of available aliases for that particular file.

The most current use of this command at the beginning of a map is:

music normal

This plays the .wav file associated to "normal" which is when everything is quiet and no action occurs (no shooting and killing). After the "normal" track plays once, it will start over is things are still quiet but if the action gets heated, the music will automatically change to the .wav file associated to the "action" alias. So IOW, the music "track change" is automatic as long as it's initiated by the above command at the beginning of the script. If you want to force a the playing of specific .wav alias, use the forcemusic command.

To turn the music off completely, use the command:

music none

The name of the .mus file used by the map can be set either by the "soundtrack" key of the worldspawn entity in the editor or by using the soundtrack command.


newline
 
Function
 
Developer line feed command. The output of this command will only be visible if developer mode is set to 1 (enabled). Normally used after print* type command to bring the cursor to the beginning of the next line. Does the same thing as the \n character placed at the end of the text string in print or layout strings commands.

Syntax
 
newline

Notes & examples
 
There is a "user" variant of this command which does exactly the same thing except that its output will be visible regardless if developer mode is on or off: the unewline command.


noncinematic
 
Function
 
Signals the end of a in-game cinematic sequence and brings the player back in normal play mode.

Syntax
 
noncinematic

Notes & examples
 
This command will also disable the previous skipthread command. The opposite of this command is cinematic.


overlay
 
Function
 
Toggles the previously loaded overlay file on or off.

Syntax
 
overlay 0|1

Notes & examples
 
overlay 0: off
overlay 1: on


pause
 
Function
 
Makes a thread pause and wait for the ocurrence of a game event such as a entity being triggered, used, touched or damaged. It can also be used to make actor wait for a game event to occur for which a state is defined in its default or user-defined AI.

Syntax
 
pause

Notes & examples
 
A typical example of use the pause command in a thread:

$<object_name> onuse <label_name>
pause

Here, the thread will pause until the scriptobject entity is used by the player in the game. When this occurs, the thread will jump to the label following the onuse command.

Note:
Do not confuse this command with the pause Camera command. It is an entirely different command with a different function even though it has the same name.


print
 
Function
 
Developer print command. The output of this command will only be visible if developer mode is set to 1 (enabled). This will print a text string or the value of a string variable on the top left part of the screen. When an explicit text string is used as the argument of the command, it must be enclosed between double quotes.

Syntax
 
print "<text_string>"|<variable_name>

Notes & examples
 
You can use \n (newline) at the end of the text string argument if the command. If the text string was previously stored in a string variable, that variable can be used as the command argument.

There is a "user" variant of this command which does exactly the same thing except that its output will be visible regardless if developer mode is on or off: the uprint command.


printfloat
 
Function
 
Developer print command. The output of this command will only be visible if developer mode is set to 1 (enabled). This will print a floating point number or the value of a floating point number variable on the screen.

Syntax
 
printfloat <floating_point_number>|<variable_name>

Notes & examples
 
If the floating point value was previously stored in a number variable, that variable can be used as the command argument.

There is a "user" variant of this command which does exactly the same thing except that its output will be visible regardless if developer mode is on or off: the uprintfloat command.


printint
 
Function
 
Developer print command. The output of this command will only be visible if developer mode is set to 1 (enabled). This will print a integer number or the value of an integer number variable on the screen.

Syntax
 
printint <integer_number>|<variable_name>

Notes & examples
 
If the integer was previously stored in a number variable, that variable can be used as the command argument.

There is a "user" variant of this command which does exactly the same thing except that its output will be visible regardless if developer mode is on or off: the uprintint command.


printvector
 
Function
 
Developer print command. The output of this command will only be visible if developer mode is set to 1 (enabled). This will print a vector or the value of a vector variable on the screen.

Syntax
 
printvector "(<X Y Z>)"|<vector_variable_name>

Notes & examples
 
Vector notation in Sin takes the form of a numeric triplet enclosed in parentheses and double-quotes. If the vector was previously stored in a vector variable, that variable can be used as the command argument. For more info on vector variables, please refer to the variables page.

There is a "user" variant of this command which does exactly the same thing except that its output will be visible regardless if developer mode is on or off: the uprintvector command.


releaseplayer
 
Function
 
This will un-freeze the player's movement controls when previously disabled by the freezeplayer command during a cinematic sequence. This command is used at the end of a cinematic sequence right before the noncinematic command.

Syntax
 
releaseplayer

Notes & examples
 
This command only works when the game is in cinematic mode.


removeclass  
 
Function
 
This will remove all the entities in the game that belong to common server classname.

Syntax
 
removeclass <server_classname>

Notes & examples
 
This command, unlike the killclass command, will not "kill" living things such as actors and sentients. IOW, the actors will not play their death animations and die, they will simply be removed from the game. Also, unlike the killclass command, this command works with any type of entity, not just living things.

The argument required for this command is the server classname of the model. Do not confuse this name with the entity's classname in SinEd. In order to determine the server classname of a particular entity, open that entity's .def file with a text editor and look for a command that goes:

server classname <name>

The <name> in the command is what you must use as the argument for the removeclass command. Typically (for sentients), it should be something like "actor", "object", "item", etc.


removeent  
 
Function
 
This will remove any entity in the game. This will do the same thing as if you had used a killent command when used on non-living things.

Syntax
 
removeent <entity_number>

Notes & examples
 
This command cannot use the entity's targetname (preceded by a $) as its argument. It requires the entity's sequence number but the * in front of the number is omitted. Determining the sequence number requires turning on the sv_showentnums option at the game console prompt:

sv_showentnums 1

This will display all the entity's sequence number over them in the game. However, in order for this option to work, you need a 3D card which has a real OpenGL driver (Glide and 3Dfx GL mini-drivers are NOT real OpenGL drivers). This will work no problem with a TNT or TNT2 card.

It can be made to work with a Voodoo2 card using 3Dfx's Beta 1.2 OpenGL driver (Warning: very unstable - use at your own risk). To install the driver, extract the file named 3dfxopengl.dll from the .exe archive and copy it to your game's Sin folder. Rename it to opengl32.dll (backup any existing file by the same name first).

However, this cannot be made to work with Voodoo, Voodoo Rush, Banshee, Matrox G200/G400 or Voodoo3 cards since there are no real OpenGL drivers available for them (yet).

Fortunately, there is a much more convenient and easy way to remove an entity from the game by refering to it by its targetname instead. For this, I suggest you use the remove entity command.


screenprint
 
Function
 
This is used to print a layout string on the screen for a duration specified in the <time> argument after which it will fade out. Useful when you need to display text on the screen but want to benefit from all the options possible with layout strings: positioning, color, alpha, blinking, teletype effect, etc.

Syntax
 
screenprint <time> "<layout_string>"

Notes & examples
 
For more info on layout strings, please consult the console and menu documentation in the Console Black Magic and the SinEd tutorial on consoles.


screenprintfile  
 
Function
 
This is used to print a layout file in the screen. The layout file must contain valid layout strings and must have a .txt file extension to be recognized by the command. However, the file extension must be omitted in the command's <filename> argument. The command assumes the "base" folder as its root.

Syntax
 
screenprintfile "<path/filename>"

Notes & examples
 
To clear the screen of the output displayed by this command, use the clearscreenprintfile command.


setcvar
 
Function
 
This command is used to set a game console variable.

Syntax
 
setcvar <cvar_name> <value>

Notes & examples
 
Typical example of game console variables are: cl_autoskins, r_speeds, r_fullbright, etc. Most of them are toggle options meaning they can either be set to 0 or 1. To get a complete list of all possible cvars, drop the console while in the game by pressing the ~ (tilde) key. Then type the following commands:

logfile 1
cvarlist
logfile 0
quit


This will dump the output of the console to a text file named qconsole.log in the game's Sin/base folder. You can then open a file with a text editor to browse through all the possible cvars. You can also rename qconsole.log to a something like cvar.txt and keep it in a convenient folder for future reference.

To find out the current value of a cvar, simply type it at the console prompt with no argument. Then hit enter, the console will return its current value.


setdialogscript
 
Function
 
This command is used at the beginning of the script. It tells the script from which file to fetch the dialog commands for dialog thread calls (thread::dialog <thread_name> command).

Syntax
 
setdialogscript <path>/<dialog_script_filename>.scr

Notes & examples
 
The <path> must be relative the PAK file's root folder or the 'base' folder of the game (by default, it's the 'base/dialog' folder of the game).

This command must be used at the beginning of the main script or at the very least before any dialog thread call commands in the script. Otherwise, the thread command won't know where to find the dialog thread.


skipthread
 
Function
 
This is used to give to the player the ability to skip a cinematic sequence in a map. When skipthread is enabled, it will go to "listen" mode and call the thread specified in the command when the user presses the "use", "jump" or "fire" key.

Syntax
 
skipthread <thread_name> (enable)
skipthread "" (disable)

Notes & examples
 
The normal use for skipthread is to place it after the cinematic command which enables its use. It is automatically disabled when the noncinematic command is issued. It is possible to disable skipthread while still in the cinematic sequence by making it point to a "null" thread as shown in the syntax above.

Please note that the actual code in the thread called by skipthread is responsible for bringing the player to the beginning of a normal map or the normal "action" part of the same map. The skipthread command is strictly a monitoring command and does not make the player "automatically" skip a cinematic sequence.


soundtrack  
 
Function
 
This tells the game which .mus music configuration file to use for the current map. The command assumes the "base/music" folder as its root. The file extension is omitted in the command argument.

Syntax
 
soundtrack "<.mus_filename>"

Notes & examples
 
Please note that .mus files are NOT sound files or a proprietary audio format. They are text files which contain configuration elements. Specifically, these are .wav file aliases (normal, action, mystery, suspense, etc.) which tell the game what .wav file to associate with what type of action. It is possible to select or force the .wav file alias to play in the game by using the music and forcemusic commands.

The name of the .mus file used by the map can also be set by the "soundtrack" key of the worldspawn entity in the editor.


spawn  
 
Function
 
This will spawn any model based entity in the game. The first argument is the name of the model's .def file and is required. The following arguments are optional and are the spawned entity's key value/pairs. The value following the key name must be enclosed in double quotes and you can enter as many keys as you want provided they apply to the entity that is spawned by the command.

Syntax
 
spawn "<modelname>.def" origin "<XYZ_coord>" <key_arg1> "<value>" ...

Notes & examples
 
The most important argument in this command is the "origin" argument followed by the XYZ position in the map. If origin is omitted, the entity will spawn at XYZ: 0,0,0 by default. A typical example of the use of this "script spawner" would be:

spawn asrifle.def origin "-24 154 64" angles "15 180 60" gravityaxis "3" key "bluecard" scale "0.75" message "Gotcha!" noise "monsters/worker/fart2.wav" thread "mg1_pickedup"

In this example, an assault rifle will be spawned at "-24 154 64" with a pitch-yaw-roll orientation of "15 180 60", a scale of "0.75" (which will make it a tad smaller than normal) and its gravity axis "3" which will make it "fall" on the ceiling and the player will need the Blue Card to pick it up.

When the assault rifle is picked up, the text string "Gotcha!" will be printed on the screen, the sound "monsters/worker/fart2.wav" (a construction worker farting) will be played and the script thread named "mg1_pickedup" will be called.

So this command does exactly the same thing as if you had placed the entity in the map editor and had assigned all the key/value pairs in the entity dialog.


stuffcmd  
 
Function
 
This command will pass any valid console command to the game console. This makes it possible to use game console commands directly inside the script. The command argument (the console command) must be enclosed between double-quotes.

Syntax
 
stuffcmd "<console_command_name> <console_command_argument>"

Notes & examples
 
When the console command itself requires an argument, it must be separated from the command name by a space. Here's a typical example of the stuffcmd command where the console command requires an argument:

stuffcmd "play dialog/general/phone/phone1.wav"


terminate
 
Function
 
This will force a previously called thread to terminate. It must be used after a thread call command and requires the use of the reserved variable parm.previousthread either by using it directly or by passing its value to a user defined local variable first and using that local variable as the command's argument.

Syntax
 
terminate local.<variable_name>
terminate parm.previousthread

Notes & examples
 
The variable parm.previousthread contains a value which is the status of the previously called thread. When the called thread ends, the value of parm.previousthread changes to indicate this. In principle, parm.previousthread can be used directly by the terminate command.

Please note that the value of parm.previousthread will be available as long as the called thread is running BUT if it is halted with a pause or wait command, the value of parm.previousthread will be LOST so be warned that parm.previousthread is temporary by nature.

This is why, if only for the sake of safe practice, it should be passed to a local variable first. Then, that local variable can be refered to the terminate command instead of the parm variable. This is a way to ensure that the variable will always be available no matter what commands are used in the called thread. So to be on the safe side, always use the following scheme:

thread <thread_name>
local.<variable_name> = parm.previousthread
            |
            |
terminate local.<variable_name>


thread
 
Function
 
SinScript's most common command. Starts the execution of a normal thread or a dialog thread inside the same script or in an external script file.

Syntax
 
thread <external_script_filename>::<thread_name>
thread dialog::<dialog_thread_name>

Notes & examples
 
A thread which resides in another script can also be called by using the :: notation and specifying the path and name of the script file as in the following example:

thread global/universal_script.scr::StatusUpdated

As with other commands, the path must be relative the PAK root or the 'base' folder of the game.

If the thread dialog::<dialog_thread_name> variant of the command is used to call dialog threads from an external file, the name of that file must be set in advance at the beginning of the script with the setdialogscript command.

An actor can also call threads, for more details on threads called by actors, refer to the thread command in the Actor commands page.


training  
 
Function
 
Toggles training mode on/off. Default is OFF. Training mode is used in Ritual's HardCorps Training Center maps. When set to ON, it makes an SP game session similar to DM mode respawn: when the player dies, instead of automatically being brought to the loadgame menu, the screen will just remain the same until the player hits the spacebar. When he does, he will be respawn at the location of the info_player_start entity but not at the beginning of the map's action. IOW, just like in DM, the player respawns but the map doesn't reload.

Syntax
 
training 0|1

Notes & examples
 
training 0 : turns training mode OFF (default)
training 1 : turns training mode ON


trigger
 
Function
 
This can be used to trigger most triggerable entities in the map.

Syntax
 
trigger $<triggerable_entity_name>

Notes & examples
 
Most triggerable entities respond to this command but not all. Experiment.


unewline  
 
Function
 
User line feed command. The output of this command will be visible regardless if developer mode is on or off. Normally used after print* type command to bring the cursor to the beginning of the next line. Does the same thing as the \n character placed at the end of the text string in print or layout strings commands.

Syntax
 
unewline

Notes & examples
 
There is a "developer" variant of this command which does exactly the same thing except that its output will be visible only if developer mode is set to 1 (on): the newline command.


uprint  
 
Function
 
User print command. The output of this command will be visible regardless if developer mode is on or off. This will print a text string or the value of a string variable on the top left part of the screen. When an explicit text string is used as the argument of the command, it must be enclosed between double quotes.

Syntax
 
uprint "<text_string>"|<variable_name>

Notes & examples
 
You can use \n (unewline) at the end of the text string argument if the command. If the text string was previously stored in a string variable, that variable can be used as the command argument.

There is a "developer" variant of this command which does exactly the same thing except that its output will be visible only if developer mode is set to 1 (on): the print command.


uprintfloat  
 
Function
 
User print command. The output of this command will be visible regardless if developer mode is on or off. This will print a floating point number or the value of a floating point number variable on the screen.

Syntax
 
printfloat <floating_point_number>|<variable_name>

Notes & examples
 
If the floating point value was previously stored in a number variable, that variable can be used as the command argument.

There is a "developer" variant of this command which does exactly the same thing except that its output will be visible only if developer mode is set to 1 (on): the printfloat command.


uprintint  
 
Function
 
User print command. The output of this command will be visible regardless if developer mode is on or off. This will print a integer number or the value of an integer number variable on the screen.

Syntax
 
uprintint <integer_number>|<variable_name>

Notes & examples
 
If the integer was previously stored in a number variable, that variable can be used as the command argument.

There is a "developer" variant of this command which does exactly the same thing except that its output will be visible only if developer mode is set to 1 (on): the printint command.


uprintvector  
 
Function
 
User print command. The output of this command will be visible regardless if developer mode is on or off. This will print a vector or the value of a vector variable on the screen.

Syntax
 
uprintvector "(<X Y Z>)"|<vector_variable_name>

Notes & examples
 
Vector notation in Sin takes the form of a numeric triplet enclosed in parentheses and double-quotes. If the vector was previously stored in a vector variable, that variable can be used as the command argument. For more info on vector variables, please refer to the variables page.

There is a "developer" variant of this command which does exactly the same thing except that its output will be visible only if developer mode is set to 1 (on): the printvector command.


wait
 
Function
 
Makes the thread wait for a certain amount of time before it resumes excution and processes the next command in the thread. The time is in seconds and floating point values are permitted. Its mainly used for accurate timing of events in the game or to allow enough time for an action to complete before resuming execution of the thread.

Syntax
 
wait <amount_of_time>

Notes & examples
 
This command has an infinite variety of uses in all kinds of threads but it's particularly essential in looping threads to prevent an uncontrolled infinite loop ("possible infinite loop" error message in developer mode).

Here's a simple example of use in a cinematic sequence to control the timing of camera shots (which is an excerpt from the example used in the goto command):

cuecamera $camera1
wait 6.8
cuecamera $camera2
end

In this particular example, the wait command controls the duration of the camera1 shot before camera2 is cued. This also serves to illustrate that the usefulness of the wait command can apply as much to the command that follows it than the command that precedes it.


waitFor
 
Function
 
Makes the thread wait for an entity to complete the action it was instructed to do in the previous command. This can be the translation or rotation movement of a scriptobject or a scriptmodel, an actor reaching a certain pathnode, etc.

Syntax
 
waitFor $<entity_name>

Notes & examples
 
A typical example of use:

$<object_name> moveto $<waypoint_name>
waitFor $<object_name>

In this example, the thread will wait until the object has reached the location of the waypoint entity before moving on to the next command.

If the $object_name is assigned to the value of a string variable, the command can refer to the variable name instead of the object name:

<variable_name> string "$<object_name>"
<variable_name> moveto $<location_name>
waitFor <variable_name>

Note:
This variable technique can be used with all SinScript commands: the argument or preceding entity's targetname can be stored in a variable and the variable can be used as the command argument.


waitForConsole
 
Function
 
Makes a thread wait for a console until a menu item is selected or user data is input at the console prompt. When this happens, the thread will be able to resume and the data entered at the console by the user will be available for processing. This command always precedes a coninput command.

Syntax
 
waitForConsole con<console_name>

Notes & examples
 
An important detail about this command is that unlike regular console commands, it refers to the consolename of the console but without the preceding % symbol.

This is because the %consolename (precededed by the % symbol) is the console object or console entity. The consolename without the % symbol is in fact a variable to which the console data (entered at the console by the user) is passed.

Afterwards, the content of the console variable must be passed to a user defined variable by the coninput command as in the following example:

local.userdata coninput con_console1

The user defined variable "local.userdata" now contains the latest data input from the console. Afterwards, regular variable operators and conditional test commands can be used to process the data and decide on the action to take in the game based on the variable's value. For more information on how to process console input data, please refer to the Consoles tutorial in the SinEd tutorials section.


waitForPlayer
 
Function
 
Makes a thread wait for the player to be spawned in the game. This is useful in the case where one or several initialization threads must run to set up things in the game before the player spawns. The waitForPlayer command is then placed after the initialization thread calls.

Syntax
 
waitForPlayer

Notes & examples
 

waitForSound
 
Function
 
Makes the thread wait for a sound to be finished playing before it resumes excution. This is used right after a playsound or phssound command.

Syntax
 
waitForSound "<path>/<soundname>.wav"

Notes & examples
 
A typical example of use in a thread:

$object playsound "environment/cabinet/cab21.wav" 1 2
waitForSound "environment/cabinet/cab21.wav"


The thread will resume execution only after the sound "cab21.wav" has finished playing.


waitForThread
 
Function
 
Makes a thread wait for the previously called thread to complete its execution and terminate before it resumes the execution of its own command. It is always used after a thread call command and requires the use of the reserved variable "parm.previousthread".

Syntax
 
waitForThread local.<variable_name>
waitForThread parm.<variable_name>

Notes & examples
 
The variable parm.previousthread contains a value which is the status of the previously called thread. When the called thread ends, the value of parm.previousthread changes to indicate this. In principle, parm.previousthread can be used directly by the WaitForThread command.

Please note that the value of parm.previousthread will be available as long as the called thread is running BUT if that thread is halted at one point because it contains a pause or wait* command, the value of parm.previousthread will be LOST. So please remember that parm.previousthread, like all parm variables, is temporary by nature.

This is why the value of parm.previousthread is most often passed to a user defined local variable. Then, the local variable is used in the WaitForThread command instead of parm.previousthread. This is a way to ensure that the variable will always be available no matter what happens in the called thread. So it is good practice to always use the following syntax as in this example:

thread gotta_wait_til_youre_done
local.waitforthread = parm.previousthread
waitForThread local.waitforthread


This way, you will avoid any potential problems.


waitForVariable
 
Function
 
Makes a thread wait until a console variable has changed.

Syntax
 
waitForVariable <console_name_variable>

Notes & examples
 
Sorry if I don't have any more information on this one but I was never able to get it to work and my questions about it were never answered in a way that could have enabled me to find out how it works (assuming it really does). So if anybody out there knows how this works, please email me a decent explanation or even better: point me to a real life example so I can analyze it.

In the mean time, I think it's pretty safe to say that the waitForConsole command can cover most of your needs.