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.

-=>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.com 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.

http://www.darksigns.com/forums/viewforum.php?f=39
http://www.darksigns.com/forums/

=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: http://www.darksigns.com/invision/

Back to INDEX