Dark Signs Scripting Guide Back to INDEX Overview of the Dark Signs scripting language, used to write scripts for the game - Dark Signs. It may be useful to print this file. > Contents 1. Introduction 2. Commands - Comments - Variables - Using the IF, ELSE, ELSEIF, and ENDIF keywords - Looping - Input - Parameters - End - Other Commands 3. Functions - Exists 4. Vital Tips & Tricks 5. Example Scanning Script 6. Script Help > (1) Introduction Anything you can do in the console, you can automate with scripts. You can use scripts to do much, much more. Using scripts, basically allows you to write your own software in the game. This guide will show you the syntax and commands needed to write an effective script. It will help a lot if you have had previous programming experience when you write scripts, however it is ok if you haven't. Because of the complex nature of scripts, we understand everyone does not have the time to write their own. Feel free to have a look at the scripts database on the darksigns website at https://darksigns.pf-control.de/forum > (2) Commands -=>COMMENTS<=- You can insert a comment into your scripts by using the well known double slash, // at the beginning of the line. For example... //this is a comment and will be ignored when the script //is run You can also put in comments on the same line as code by adding it to the end of the line. Example... *say 20 Hello //display hello on the screen -=>VARIABLES<=- Variables (you can use a word to represent a numerical value, which you can change in your program). IMPORTANT NOTE: All variables used in scripts are accessable to other scripts if the correct name is used. For this reason, try to give your variables unique names. - and try to get into the habit of setting their value after you declare them. To declare a variable you can use the var keyword, followed by the name of the variable. For example... var myvariable The variable name must start with a letter from a-z, not a numerical character or symbol. To assign a value to a variable you must start a new line with a ! character. For example, if you wanted to assign a value of 10 to 'myvariable', you would... ! myvariable = 10 Below is a short example script of more advanced assigning variables and displaying them on the screen. //begin example.script var myvar1 var myvar2 var myvar3 ! myvar1 = 5 ! myvar2 = myvar1 * 2 ! myvar3 = myvar1 * myvar2 ? myvar1 ? myvar2 ? myvar3 //end example.script The above script should produce the following output... 5 10 50 As you can see in the script, you can assign the value of variables to other variables. Dark Signs Scripting currently allows the following mathematical operators: + - * / To use variables in commands such as ping, scan, etc, you can do the following. Usually, you would ping like this ping 12.12.12.12 Using a variable which keeps getting larger, combined with a loop, you can write a scanner. IMPORTANT TO REMEMBER: In ANY command, you can use the following to put in the value of a variable. %variablename% Example... If we had a variable called lastip with a value of five, ping 12.12.12.5 would be the same as... ping 12.12.12.%lastip% And here is a small ping scanner @start ! lastip = lastip + 1 ping 12.12.12.%lastip% goto start Notice that the script will keep looping, each time incrementing the variable - lastip. So in the command window, you would see... ping 12.12.12.1 [ping happens] ping 12.12.12.2 [ping happens] ping 12.12.12.3 Etc... Things to note: -That script would go on forever. You would need to use an IF statement with a GOTO to exit once the lastip variable was at 255. -You could make a much more complex scanner than above, even using a variable for every ip number. EG: ping %number1%.%number2%.%number3%.%number4% As you can see here, scripts can be very interesting to play around with, there is a lot you can do with them. Remember that any variable declared in a script is accessible in all other scripts and even in commands you type in the console. (Again, you can use them by inserting the variable name between % characters). DEFINING VARIABLES ON THE SAME LINE You can define variables on the same line, if they are of the same type (var$ or var) Example: var myVar1, myVar2, myVar3 //all these variables will hold numeric values Example: var$ myVar1, myVar2, myVar3 //all these variables will hold string values DO NOT USE: var myVar1, var myVar2, var$ myVar3 //this is not allowed =Kill variables when you are finished using them= This is optional, although recommended if you use variables a lot, or write scripts. Dark Signs memory is limited (although very high) it could run out after a time and cause variables to not work. To preven this, you can delete unwanted variabled, usually at the end of scripts. Just use the free command, example below. Free myvariable -=>IF STATEMENTS<=- You will probably want to stop a loop at a point, or check a value. Here you can make use of the IF keyword. Here is an example of the IF keyword in use... //begin example.script var int1 ! int1 = 0 @start ! int1 = int1+1 ping 12.12.12.%int1% if int1 = 255 goto end endif goto start @end //end example.script This script will ping 255 IP address before it ends. Have a look at the three lines of the if statement. if int1 = 255 goto end endif If you have done any BASIC programming before, you should be familiar with this. It works on the condition that the argument (int1 = 255) is true. So if int1 = 255 then it will go through each command in the script, until it reaches an ENDIF. (Note that Dark Signs accepts both ENDIF and END IF with a space.) So once int1 is equal to 255, the script will look for a line @end and go directly to it. In IF statements, Dark Signs ccepts the following operators. = Equal to < Less than > More than So in the above script, the line... if int1 = 255 could have said if int1 > 254 and it would have worked just fine. REMEMBER - don't forget to include your ENDIF. If you forget an ENDIF, your program will most likely exit if the IF condition is false, as it will assume every following command shouldn't be run. Or if the condition is true, your program could run forever, and have unexpected results. ENDIF, ENDIF, ENDIF, ENDIF, ENDIF, ENDIF, ENDIF, ENDIF, ENDIF!!! (Use CTRL+X to cancel a running script.) You CANNOT use if statements inside of each other, although it is likely we will support this in the near future. Eg If X > 2 If X < 5 //do things here EndIf EndIf There is no support for using >= and <=, for now you will have to live with <, >, and or course =. You can use ELSE, eg If X > 10 //do things ELSE //do things ENDIF You can use ELSEIF like else, but also include a condition. If X > 10 //do things ELSEIF X > 20 //do more things ENDIF Note that ElSEIF can be used with or without a space (ELSEIF, ELSE IF) Note that ENDIF can be used with or without a space (ENDIF, END IF) -=>LOOPING<=- Loops are impossible to do without if you want to write a scanner, or for that matter almost anything apart from a basic program. Make sure you use with the IF statement to prevent infinite loops. If you do get yourself into an infinite loop, you can cancel running scripts by using the CTRL+X key combination. Here is an example script which will run forever, incrementing the variable by 1 each time. //begin var thevar ! thevar=12 @inc ! thevar=thevar+1 ? thevar goto inc //end Notice the keyword GOTO is used when you want to jump back to another part of the script. The program must know where you want to goto, you can specify this by using the : symbol, followed by a name to identify the position in the script. Remember, if you type... GOTO something You must also have... @something in the script. This is where the script will jump to when it reaches the GOTO command. IMPORTANT NOTE ABOUT USING GOTO We can call the lines '@something' a label. It is highly recommended that you do not put your labels in the middle of an if statement or multiple if statements, as this could cause hard to find errors. -=>INPUT<=- It is often necessary to retrieve information from the player. For example, a script could allow the player to specify what range of IP addresses they would like to scan. First, you must create a variable which will store the input from the user. var myvariable Now you can use the following command input myvariable Enter a number... Notice - first you need to use the keyword INPUT, followed by the name of the variable you want the input to go into. Lastly, some text will be shown to the player, which can be used to show them what the data they are entering will be used for. -=>PARAMETERS<=- When running a script, you can allow the player to specify extra parameters. Eg: > run my.script param1 param2 This helps you get initial input from the user. Any script will accept parameters, however they will be ignored unless optionally use them in your script. When scripts are run, any specified parameters are put into a variable ext Example: > run my.script 255 255 0 72 Before Dark Signs runs the script my.script, the following will happen. A variable %ext1% will be created, with the value 255 A variable %ext2% will be created, with the value 255 A variable %ext3% will be created, with the value 0 A variable %ext4% will be created, with the value 72 You can use these variables in your program as normal variables without the need to declare them. Remember, if you scripts requires these variables to run, you may want to check they exist first (check they were specified by the player). Dark Signs supports up to 20 parameters to be used with each script. -=>END<=- While a script is running, to end it at any time, you can the END command on a single line by itself. -=>OTHER COMMANDS<=- Pause - Displays 'Press A Key To Continue..." on the screen, and pauses script until a key is pressed. A variable called %path% is always in the Dark Signs memory. It will also contain your local directory path. > (3) Functions Functions are like normal commands which were developed for the purpose of scripting. When you use them, they will not display anything on the screen, but instead, will create a variable with a result depending on the given parameters. EXAMPLE //check if a file exists var thefile input thefile enter a file exists thefile //now there will be a variable called exists which was automatically created with the function if exists=false *say 20 bad filename goto start endif //end example EXISTS Return Variable Name: exists The variable will contain either 'true' or 'false' Usage: exists [filename] For more information on variable functions, check the file variable_function on the dark signs database. > (4) Vital Tips & Tricks =Send Invisible commands which will not show in the console= There is a way to make it so the command line is not shown, but is still executed. To do this, simply add a * to the beginning of the line. =Increase the value of variables by 1= Often you need to set the variable to one more than it already is. You can use the following trick, by assigning the variable to itself plus one more. theVariable = theVariable + 1 =Disable Cancel= Sometimes there may a need to disable the user from cancelling the script running. You can do this by using the following commands in the script //disable cancel cancel true //enable cancel cancel false =Case Sensitive= Variables are not case sensitive. X is the same as x, and MYVAR is the same as MyVaR, etc. Please remind us if there is something else that should be here... Or if we haven't explained something very well. > (5) Example Scanning Script The below script is a basic script which can be used to scan a range of computers (255) to see if there are any servers there. Below, we use the new pingscan command. The pingscan command is similar to ping, however is much faster and has the ability to output positive results to a file - making it perfect for use with a scanning script. //begin subnetscan.script clear *say 20 Welcome to Subnet Scanner, Version 1.0 *say 20 IP Address (x.x.x.x) = (Part1.Part2.Part3.Part4) var ip_part_1 var ip_part_2 var ip_part_3 var ip_last_part input ip_part_1 Input the first part of the IP Address input ip_part_2 Input the second part of the IP Address input ip_part_3 Input the third part of the IP Address ! ip_last_part = 0 @start ! ip_last_part = ip_last_part + 1 *pingscan %ip_part_1%.%ip_part_2%.%ip_part_3%.%ip_last_part% output.txt if ip_last_part < 255 goto start end if @end *say 20 Scan Complete (255 hosts scanned) //end subnetscan.script > (6) Scripting Help? We have found that we make common mistakes when writin scripts. Here is a checklist of what you should check if your script isn't working the way you think it should. - Make sure you don't have a THEN at the end of your IF statements, example INCORRECT: If myVar = 1 Then CORRECT: If myVar = 1 - Check all your variable names are spelt correctly. - When assigning variables, check there is a ! symbol, followed by a space at the beginning of each line, example INCORRECT: myVar = myVar + 1 CORRECT: ! myVar = myVar + 1 If you have a problem with your script, and it is not too complex, send it off to scripts@darksigns.pf-control.de and we will have a look at it for you. For announcements on new scripting features which may not be included in this file, check the forums. https://darksigns.pf-control.de/forum https://darksigns.pf-control.de/forum =end= Thankyou for reading this guide. If you have any more questions about Dark Signs or the scripting language, you can ask us on the forums so everyone can benefit from the response, or email us using the links below. Forums: https://darksigns.pf-control.de/forum Back to INDEX