Function section, “where” can be LEFT, RIGHT, TOP, BOTTOM, SUB
TipType can be TEXT, ELEMENT, GROUP
TipText depends on TipType.
If TipType is TEXT then TipText can be any Text.
If TipType is ELEMENT of GROUP then TipText can be the ID of an Element or a Group.
PictureType can be TEXT, ELEMENT, ELEMENTNAME, GROUP, GROUPNAME, NUMBER, STRING, NEWLINE
PictureText depends on PictureType.
If PictureType is TEXT then PictureText can be any Text.
If PictureType is ELEMENT, ELEMENTNAME, GROUP or GROUPNAME then PictureText can be the ID of an Element or a Group.
If PictureType is NUMBER then PictureText can be a Variable.
MENU where ADD TipType TipText PictureType PictureText Trigger
will add a simple Button.
MENU where ADDBORDER TipType TipText PictureType PictureText Trigger ColorR ColorG ColorB
will add a Button with a border.
MENU where ADDDRAG TipType TipText PictureType PictureText Trigger
will add a Button that can be dragged.
NEW STUFFS EXAMPLE
MENU where ADD TEXT ”“ SEPARATOR 30 Trigger
Will create a separator (blank) with a length of 30 pixels. 0 Len will make it autosized.
MENU where ADD TEXT ”“ NEWLINE 30 Trigger
Will create a new line with a len of 30 pixels. The new line will be horizontal or vertical depending on the type of menu. Use 0 as the len, for an autosized line.
MENU where ADD TEXT ”“ STAMP StampID Trigger
This will display the STAMP StampID as the image of the menu. The stamp must have been created before using it.
MENU where ADD TEXT ”“ TEXT MESSAGE Trigger
Will display the content of the MESSAGE command as the text of the menu.
MENU where CLEAR
will clear a menu.
MENU REFRESH
will refresh a Menu. This should only be used for refreshing Buttons that display a Variable.
SUBMENU
will show the Submenu. The Submenu must contain one or more buttons.
SUBMENU x y
will show the Submenu at the given coordinates. The Submenu must contain one or more buttons.
* NEW STUFFS *
General Syntax:
SUBMENU [HORIZONTAL/VERTICAL] x y [STAY]
SUBMENU HORIZONTAL x y
will show the Submenu at the given coordinates and horizontally, for multilines menus. The Submenu must contain one or more buttons. Put VERTICAL to show it vertically. When using NEWLINE, the submenu will create the newline depending on its orientation.
SUBMENU HORIZONTAL x y STAY
will do exactly the same as above, but the submenu will stay open even if clicked on a menuitem. You have to close it using: SUBMENU CLOSE
Triggername can be any text.
Function must be a valid function.
A condition must be the name of an variable or an expression.
ON triggername function
will add the function to the list of actions that are executed when trigger is called. Will also automatically create a new trigger if it doesn't exist.
TRIGGER triggername {
…
}
will at first erase all actions from the trigger and then add several function to the list of actions that are executed when trigger is called. Will also automatically create a new trigger if it doesn't exist.
This function can not be nested! “ON triggerabc TRIGGER { … }” will be the same as “TRIGGER { … }”.
TRIGGER triggername EXTENDS othertriggername {
…
}
will at first erase all actions from the trigger, copy all actions from othertrigger to trigger and then add several function to the list of actions that are executed when trigger is called. Will also automatically create a new trigger if it doesn't exist.
This function can not be nested! “ON triggerabc TRIGGER { … }” will be the same as “TRIGGER { … }”.
EXEC triggername
will execute the trigger.
TIMER num FRAMES triggername
will execute the trigger after num frames.
TIMER CLEAR
will clear all timers.
TIMER REMOVE triggername
will clear all timers then execute the trigger triggername.
TIMER REMOVEALL triggername
will clear the next timer that executes the trigger triggername.
REMOVETRIGGER triggername
will remove the trigger. This should always be called before defining a trigger (otherwise the trigger would call every function several times if you reinclude the file).
WHILE condition triggername
will execute triggername while condition is not 0.
IF condition triggername
will execute triggername if condition is not 0.
IF condition triggername ELSE elsetriggername
will execute triggername if condition is not 0 and elsetriggername when condition is 0. the triggers can NOT have parameters.
IF condition {
…trueactions…
} ELSE {
…falseactions…
}
will execute trueactions if condition is not 0 and falseactions when condition is 0.
FOR variable FROM startingvalue TO endvalue [STEP stepwidth]DO triggername
will execute triggername with the variable starting from startingvalue increasing to endvalue.
FOR variable FROM startingvalue DOWNTO endvalue [STEP stepwidth] DO triggername
will execute triggername with the variable starting from startingvalue decreasing to endvalue.
FOR EACH elementid DO triggername
will execute triggername for every pixel of the specified element.
RETURN number
will end the execution of the trigger. If the trigger was called as a function number will be returned.the specified element.
EXAMPLE
TRIGGER GetCosX {
RETURN (COS ($0 * 1000))
}
MyVar = (*GetCosX 60)
MESSAGE CLEAR
MESSAGE ADDTEXT "MyVar="
MESSAGE ADDNUMBER MyVar
MESSAGE MESSAGEBOX
This example will return the COS of the given parameters. Here the parameter is 60, so this will return the COS(60).
To use it, you must assign the returned value to a variable.
Calling the sub between () and using a * before the trigger name.
The MESSAGE part is just to display the result in a MESSAGEBOX.
Group can be any text.
Elementname can be any text.
ELEMENT group elementname color-red color-green color-blue weight spray slide viscousity deathrate die to menuorder Picturetype Picturetext
will create/modify an element.
Color-red, color-green, color-blue must be a value between 0 and 255.
The next values are optional:
Weight must be a value between -30000 and +32000. Default value is 0.
Spray must be a value between 1 and 32000. Default value is 1.
Slide must be a value between 1 and 32000. Default value is 1.
Viscousity must be a value between 1 and 32000. Default value is 1.
Deathrate must be a value between 1 and 32768. Default value is 0.
Die to must be the name of an element. Default value is 0.
Picturetype and Picturetext see Menu Commands. Default value is “TEXT” elementname.
NOBIAS elementid
will change an element to a nobias element. These elements react in every direction with the same rate.
QUICK ELEMENT
You can define quickly a solid element using this way:
ELEMENT groupname elementname Red Green Blue
ELEMENT none TEST 255 0 0
This is very usefull when you only want an element for its colors.
INTERACTION elementname1a elementname1b newelementname1a newelementname1b rate1 [newelementname2a newelementname2b rate2 […]] exception
will create new interactions.
INTERACTIONAT pos elementname1 elementname2 newelementname1 newelementname2 rate exception
will create a new interaction at pos.
INTERACTIONTRIGGER elementname1a elementname1b trigger1 rate1 [trigger2 rate2 […]] exception
will create new triggerinteractions.
INTERACTIONTRIGGER pos elementname1 elementname2 trigger rate exception
will create a new triggerinteraction at pos.
Instead of elementname1, elementname2, newelementname1 or newelementname2 you can also use groups by writing “GROUP:” before the groupname. These groups have to be filled when the command is executed, so it would be best it would be placed after all elements are created.
INTERACTIONCLEAR elementname
will remove all Interactions from the element.
INTERACTIONREMOVE elementname pos
will remove the Interaction at pos from the element.
ELEMENT elementname DIE dietoelement dierate
will add cause the element to die to dietoelement at rate.
DIECLEAR elementname
will remove all Dies from the element.
ELEMENTSCLEAR
will remove all Elements.
GROUP groupname order icontype icontext
will create a group with the name groupname.
GROUP groupname ADD elementname order
will add an element to a group.
GROUP groupname CLEAR
will clear the group.
GROUP CLEARALL
will clear all groups.
DRAW elementid POINT x y
will draw a POINT at x/y.
DRAW elementid POINTS xoffset yoffset x1 y1 x2 y2 x3 y3 … …
will draw several POINTs at the coordinates (x1+xoffset)/(y1+yoffset), (x2+xoffset)/(y2+yoffset), ….
The x/y coordinates can NOT be variables. They must be static numbers.
DRAW elementid CIRCLE x y r
will draw a not filled CIRCLE with the center at x/y and a radius of r.
DRAW elementid FILLEDCIRCLE x y r
will draw a filled CIRCLE with the center at x/y and a radius of r.
DRAW elementid ELLIPSE x y horizontaldiameter verticaldiameter
will draw a not filled ELLIPSE with the center at x/y.
DRAW elementid FILLEDELLIPSE x y horizontaldiameter verticaldiameter
will draw a filled ELLIPSE with the center at x/y.
DRAW elementid RANDOMFILLEDCIRCLE x y r rate
will draw a randomly filled CIRCLE with the center at x/y and a radius of r.
DRAW elementid RANDOMFILLEDELLIPSE x y r rate
will draw a randomly filled ELLIPSE with the center at x/y.
DRAW elementid REPLACEFILLEDCIRCLE x y r 0 replaceelementid
will draw a filled CIRCLE with the center at x/y and a radius of r. Only replaces pixels from type replaceelementid.
DRAW elementid REPLACEFILLEDELLIPSE x y r 0 replaceelementid
will draw a filled ELLIPSE with the center at x/y. Only replaces pixels from type replaceelementid.
DRAW elementid RECT x y width height
will draw a not filled RECT with the startingpoint at x/y.
DRAW elementid FILLEDRECT x y width height
will draw a filled RECT with the startingpoint at x/y.
DRAW elementid LINE x y dx dy
will draw a LINE from x/y to (x+dx)/(y+dy).
DRAW elementid REPLACELINE x y dx dy replaceelementid
will draw a LINE from x/y to (x+dx)/(y+dy).Only replaces pixels from type replaceelementid.
DRAW elementid FILL x y zx zy
will draw a line from x/y to zx/zy and fill anything it crosses.
DRAW elementid COPYRECT x y width height tox toy
will copy the RECT with the startingpoint at x/y to tox/toy.
DRAW elementid ROTATE x y width height 1
will rotate the RECT with the startingpoint at x/y clockwise.
DRAW elementid ROTATE x y width height -1
will rotate the RECT with the startingpoint at x/y anticlockwise.
DRAW elementid ROTATE x y width height 2
will rotate the RECT with the startingpoint at x/y by 180°.
DRAW elementid ROTATE x y width height 3
will do a point reflection to the RECT with the startingpoint at x/y.
DRAW elementid ROTATE x y width height 4
will flip the RECT with the startingpoint at x/y horizontally.
DRAW elementid ROTATE x y width height 5
will flip the RECT with the startingpoint at x/y vertically.
DRAW elementid COPYSTAMP x y width height stampid
will copy the RECT with the startingpoint at x/y to the stamp with the stampid.
DRAW elementid PASTESTAMP x y width height stampid
will copy the stamp with the stampid to the startingpoint at x/y to. Will not overwrite elementid pixels. Use 1 for elementid to overwrite all pixels.
DRAW elementid SWAPPOINTS x1 y1 x2 y2
will swap the two points with the coordinates x/y and x2/y2 to.
DRAW elementid OBJECT xoffset yoffset [SIZE sizemultiplicator] [SIZEX sizexmultiplicator] [SIZEY sizeymultiplicator] element1char element1id element2char element2id … {
DATA
}
will draw an object. If sizemultiplicator is positive the object will be scaled up. a negative value will scale it down.
OBJECT EXAMPLES
Here is the best way to use an OBJECT into a trigger
TRIGGER DrawMyObject {
DRAW 0 OBJECT $0 $1 SIZE $2 "E" ELEMENT:Earth "W" ELEMENT:Water {
"EEEEE"
"EWWWE"
"EWWWE"
"EWWWE"
"EEEEE"
}
}
This is how you should create the trigger. The $0,$1 and $2 parameters correspond to: X,Y and SIZE.
So to draw it at x,y 210,210 and with a normal size of 1 you use:
EXEC DrawMyObject 210 210 1
Then if you want to draw it at 100,100 and with 5 times its normal size you use:
EXEC DrawMyObject 100 100 5
WRITE elementid x y size [CENTER] TEXT text
will write the text with size starting from x/y. Will also set WRITEWIDTH to the textwidth and WRITEHEIGHT to the textheight.
WRITE elementid x y size [CENTER] NUMBER var
will write the number with size starting from x/y. Will also set WRITEWIDTH to the textwidth and WRITEHEIGHT to the textheight.
WRITE elementid x y size [CENTER] ELEMENT elementname
will write the elementname of the element with the elementid with size starting from x/y. Will also set WRITEWIDTH to the textwidth and WRITEHEIGHT to the textheight.
WRITE elementid x y size [CENTER] GROUP groupid
will write the groupname of the element with the groupid with size starting from x/y. Will also set WRITEWIDTH to the textwidth and WRITEHEIGHT to the textheight.
WRITE elementid x y size [CENTER] STRING stringid
will write a string with size starting from x/y. Will also set WRITEWIDTH to the textwidth and WRITEHEIGHT to the textheight.
WRITE elementid x y size [CENTER] MESSAGE 0
will write the groupname of the element with the groupid with size starting from x/y. Will also set WRITEWIDTH to the textwidth and WRITEHEIGHT to the textheight.
SET varname new value
will set value of the variable varname to a new value.
varname = new value
will set value of the variable varname to a new value.
INC varname
will increase the variable varname by 1.
This is much faster than SET varname (varname + 1).
GET varname
will show the value of the variable varname.
LIST ELEMENTS
will list all elements.
LIST VARS
will list all variables.
LIST GROUPS
will list all groups.
LIST GROUP groupname
will list all elements of a group.
LIST INTERACTIONS elementname
will list all interactions of an element.
LIST ELEMENTGROUPS groupname
will list all groups of an element.
LIST TRIGGERS
will list all triggers.
LIST TRIGGEREXECS
will list all triggers with the number of executions.
LIST ACTIONS triggername
will list all actions of a trigger.
LIST TIMERS
will list all timers.
GETFILE filename
will show the content of the file. Only for network.
INCLUDE filename
will include the file.
INCLUDE url
will download the file from url and include it. It supports webpages from wikis and forums.
COUNT varname elementid
will count the pixels of the element and saves the result in the variable.
COUNT varname elementid IN RECT x y width height
will count the pixels of the element in the defined rect and saves the result in the variable.
CLOSEST elementid X Y max
will find the nearest element to X/Y. Searches a maximum distance of max.
RESIZE width height
will resize the sandbox to width and height.
EXIT
will exit Burning Sand 2.
RESTART
will restart Burning Sand 2.
RESTART configfile
will restart Burning Sand 2 and load the configfile.
SYSTEM command
will show a confirmation dialog and evetually run the command. Several commands can be seperated by ”;”.
STATUS CLEAR
will clear the statustext.
STATUS ADDTEXT text
will add text to the statustext.
STATUS ADDNUMBER variable
will add a number to the statustext.
STATUS ADDELEMENT elementid
will add the elementname to the statustext.
STATUS ADDGROUP groupid
will add the groupname to the statustext.
STATUS ADDMOUSEOVER
will add the tooltip/elementname of the cursorposition.
KEYCODE keycode key
will assign the key to the keycode.
FILE OPEN filename
will open the file. (Append to File)
FILE OPEN filename NEW
will open a NEW file. (Blank File)
FILE CLOSE
will close the currently open file.
FILE DELETE filename
will delete the file.
In BS2 you can ask for a FILEDIALOG to be displayed. This will show the normal window load/save file dialog.
You can use it to load any local file. For example to load a specific savegame file type.
INCLUDE FILEDIALOG "TEXT|*.txt|DOCUMENT|*.doc"
This example will load a file, displaying only .txt or .doc file.
The Syntax for the filter function work like this:
NAME OF THE FILTER|Dos type wildcard filter|
To create many type to choose from, you separate them using the pipe | separator.
For example to show both images type file, and .bs2 type file you would use:
INCLUDE FILEDIALOG "IMAGES|*.bmp;*.png|BS2 FILES|*.bs2|"
Dont forget the last pipe |, this will ensure you get all filter in case of multiple type for a filer (like the image filter)
You can also use it to open a file (Filters work too):
FILE OPEN FILEDIALOG
Or to save a file (Filters work as always) :
SAVE SAND FILEDIALOG
Anywhere you can use a filename you can use FILEDIALOG instead !
SAVE SAND filename
will save the Sandbox to the file.
LOAD SAND filename
will load the Sandbox from the file.
SAVE QUICKSAND quicksandid
will save the Sandbox to RAM. This is more than 100 times faster than saving to file.
LOAD QUICKSAND quicksandid
will load the Sandbox from ROM.
SAVE STAMP filename stampid
will save the stamp with the stampid to the file.
LOAD STAMP filename stampid
will load the stamp with the stampid from the file.
SAVE TIMERS
will save all timers to the currently open file.
SAVE VAR varname value
will add “SET varname value” to the currently open file.
to load the value use INCLUDE filename
LOAD BGLAYER filename
will load the a .bmp file as background layer.
LOAD FGLAYER filename
will load the a .bmp file as foreground layer.
LOAD FONT filename
will load a TTFont for the WRITE command.
LOAD MENUFONT filename size
will load a TTFont for the menu. Will also set the fontsize of menuitems.
Message text
will popup a window containing the text.
MESSAGE CLEAR
will clear the current message.
MESSAGE ADDTEXT text
will add a text to the current message.
MESSAGE ADDNUMBER variable
will add a number to the current message.
MESSAGE ADDELEMENT elementid
will add an elementname to the current message.
MESSAGE ADDELEMENTTEXT elementid
will add an elementtext to the current message.
MESSAGE ADDGROUP groupid
will add a groupname to the current message.
MESSAGE ADDLINE
will add a new line to the current message.
MESSAGE ADDSTRING stringid
will add a string to the current message.
MESSAGE SEND messageid
will send the message to the log with the messageid.
MESSAGE SEND
will send the message to your own message log.
MESSAGE SENDTEXT text messageid
will send the text to the log with the messageid.
MESSAGE SENDTEXT text
will send the text to your own message log.
MESSAGE SAVE
will save the message to the currently open file.
MESSAGE SAVESTRING stringid
will save the message to a string.
The EXEC function is very slow. Don't use it in timers or interactions.
MESSAGE EXEC messageid
will execute the message and sets the default messageid.
MESSAGE EXEC
will execute the message and sets the default messageid to your own messageid.
MESSAGE SYSTEM
will run the message as a system command.
CONNECT hostname port messageidvar
will establish a connection and save the messageid for this connection in messageidvar.
REMOTE messageidvar SET varname value
will set the variable varname to value on a remote BS2.
REMOTE messageidvar EXEC triggername
will execute a trigger on a remote BS2.
Everywhere you can specify a filename you can now use zip files. so if you have a file called “verylarge.bmp” put it into a zip file called “verylarge.bmp.zip” and simply specify the name of the zip file in your bs2 file.