========================================================================== Function Reference ========================================================================== A function is denoted by the @ symbol. The @ sign is required for the function to be recognized and evaluated. In the following part of the document, the following type conventions are used: ALL CAPS means that the text is part of the function means that the text specified should be replaced by text that you enter (the angle brackets should be replaced also, so that they aren't used in the function.) @BEST( , ) -------------------------- Rolls each die in individually, taking the best of them for the result. For example, @BEST(3,4d6) would roll four individual d6 and take the best three of them. This function is capable of working with the results of another function. @CAP( , , ) ------------------------------------------- Rolls each die in individually, and caps (limits) each die so that no individual die result will be lower than the value, and no individual die result will be higher than the value. For example, @CAP(3,4,3d6) would roll each die in the 3d6 individually, and make sure that any results lower than 3 were changed to 3, and any results higher than 4 were changed to 4. This function is capable of working with the results of another function. @LCAP( , ) ----------------------------- Rolls each die in individually, and caps (limits) each die so that no individual die result will be lower than the . For example, @LCAP(3,3d6) would roll each die in the 3d6 individually, and make sure that any results lower than 3 were changed to 3. This function is capable of working with the results of another function. @LIMIT( , , ) ------------------------------------------------- Rolls the and evaluates the result, limiting the final outcome so that it can not fall below the value, or rise above the value. This limits the result from falling outside of the set limiting values, and unlike @CAP, it works on the total result, not each individual die roll. This function is capable of working with the results of another function. @LLIMIT( , ) ----------------------------------- Rolls the and evaluates the result, limiting the final outcome so that it can not fall below the of the function. This limits the result from falling below some value, and unlike @LCAP, it works on the result of , not each individual die result. This function is capable of working with the results of another function. @SWWILD( ) -------------------- Rolls in accordance with the wild die rules of the Star Wars Role Playing Game. In other words, it rolls and looks at the last die, which it considers the wild die. If that die is a one, it removes that die and the highest other die (changes them to zeroes) before returning the total. If the wild die is a six (or the max for the die if not rolling d6) instead of a one, it rolls another die and adds it on, rolling again each time a six is returned. This function requires an actual die value for , and while it can feed into another function, it can not use input from another function. @UCAP( , ) ----------------------------- Rolls each die in individually, and caps (limits) each die so that no individual die result will be higher than the . For example, @UCAP(3,3d6) would roll each die in the 3d6 individually, and make sure that any die results higher than 3 were changed to 3. This function is capable of working with the results of another function. @ULIMIT( , ) ----------------------------------- Rolls the and evaluates the result, limiting the final outcome so that it can not exceed the of the function. This limits the result from rising above some value, and unlike @UCAP, it works on the result of , not each individual die result. This function is capable of working with the results of another function. @WILD( ) ------------------ Rolls and, if it gets the maximum possible result, rolls again and adds the new roll on to the total. If the new roll is also the maximum possible result, it will roll again and add until it no longer gets the maximum possible result on a roll. This function requires an actual die value for , and while it can feed into another function, it can not use input from another function. @WILDDICE( ) ---------------------- Rolls each die in individually and, for each die result that comes up at the die maximum, it rolls again and adds in the new roll, rolling and adding again if the new roll is also at the die maximum. This function requires an actual die value for , and while it can feed into another function, it can not use input from another function. @WORST( , ) --------------------------- Rolls each die in individually, taking the worst of them for the result. For example, @WORST(3,4d6) would roll four individual d6 and take the worst three of them. This function is capable of working with the results of another function. Function Notes ============== All of the functions in the CAP family (@CAP, @LCAP, @UCAP) work on individual die results within the roll. This means that the function looks at each of the dice rolled, and adjusts that particular die according to the capping values given in the function. Only individual die results are important to these functions, so the function works before the total of the portion of the function is calculated, but after the dice are rolled. All of the functions in the LIMIT family (@LIMIT, @LLIMIT, @ULIMIT) work on the total results of the die roll. This means that the function rolls the dice in the portion of the function, then adds them all together, then applies the limiting values given in the function. It is very important that you remember that the CAP functions work on individual dice, and the LIMIT functions work on total results. ========================================================================== Script Reference ========================================================================== In the following part of the document, the following type conventions are used: ALL CAPS means that the text is part of the command means that the text specified should be replaced by text that you enter (the angle brackets should be replaced also, so that they aren't used in the command.) [square brackets] means that the part of the command used inside the square brackets is optional. If you use the part of the command inside the brackets, you do not include the square brackets as part of the command. | within {curly braces} means that you have a choice between the available options for that command. You may only select one of the options within the curly braces that are separated by the | signs. So, if the command was { YES | NO | MAYBE }, you could pick any one of the choices, but only one per occurance of the command. BreakOn/BreakOff ---------------- BREAKON BREAKOFF Allows for exiting from a script by pressing the ESC key. By default, this is turned on. BREAKOFF turns it off, BREAKON turns it on again. ClearLog -------- CLEARLOG Clears the information waiting to go into the long results box, allowing you to maintain only the desired information in the long results box. This command becomes *extremely* important if you are using a continuous or looping script, because failure to use it may allow the information for the long results box to use up all of the program's available memory, crashing your script. Clear Window ------------ CLEAR WINDOW is the name of an output window specified in an OPEN WINDOW command earlier in the script CLEAR WINDOW allows you to clear the specified window of all text that it currently contains. Close File ---------- CLOSE FILE is the name of an output file specified in an OPEN FILE command earlier in the script CLOSE FILE allows you to close the specified . Note that this is the used by the script to direct output, *not* the that is used to store the file on your disk. Close Window ------------ CLOSE WINDOW is the name of an output window specified in an OPEN WINDOW command earlier in the script CLOSE WINDOW allows you to close the specified . Comments -------- ; is any text that you want to include in the script, but that should be ignored by DP Anything following a semicolon (;) is considered to be a comment and is ignored. This includes if the semicolon is inside of a quoted text block, because the script parser isn't very smart. Die Type -------- DIE= should be the number of sides for the die. Allows for changing the default die type, and affects the entire program. The last 'die=' command encountered is always the one used by the program, whether the command was found in the Preferences dialog or a script. For example: DIE=10 changes the default die type (that used if no type is specified) to a d10 instead of a d6. Define Die ---------- DEFINE = to or DEFINE = is the name you want to assign to the die. All dice start with the letter 'd,' so if you don't include it in your die name, it will be added for you. is the low number for the range of results when using the range definition is the high number for the range of results when using the range definition is the list of possible result numbers when you are using the list definition, each number of which should be separated from the others by a comma Allows for defining a type of die that does not normally exist, or does not have a '1' for the lowest number of the result range. Using the range definition will generate a random number within the range defined by at the low end, and at the high end. For example: DEFINE d00 = 0 to 99 would define a die called 'd00' that would generate a random number between 0 and 99, while DEFINE dN5 = -5 to 5 would define a die called 'dN5' that would generate a random number between -5 and 5. Using the list definition will randomly return any number from the list of possible results, giving every item in the list an equal chance of being the returned value. For example, DEFINE dSeq = 0,1,2,4,8,16 would randomly return any one of the numbers in the list, each with the same 1 out of 6 chance of being returned. This definition allows for almost any possible type of die result to be generated. Display ------- DISPLAY Causes the result and long result boxes to be updated immediately, instead of waiting for the end of the script to occur. This is useful if you want to have a looping script that never ends, but still want to see what is going on. Looping scripts should *definitely* make use of CLEARLOG, or you will run out of memory trying to hold all the results from the script in the long results box. End --- END END causes the script to end immediately at the current line. The script will also end if it passes the last line in the script, so an explicit END is not required if your script is designed to run straight through to the last line. For..Next --------- FOR = TO [ STEP ] [EXIT FOR] NEXT is the name of a variable, previously defined with a VAR statement is the starting value for is the ending value for ; in other words, when exceeds this value, the loop is exited. is the amount to increment or decrement on every pass of the loop are any script statements A FOR..NEXT loop allows you to process a block of statements a specific number of times. FOR uses a variable, , which it changes every time the loop reaches the NEXT statement. Initially, is set to the value held in the value. When the variable exceeds the value, the loop ends and the script continues execution at the line following the NEXT statement. The STEP part of the statement is optional. If you do not include it, Dice! Plus automatically assigns a . If is less than , the automatic is assigned 1. If is greater than , then the automatic is assigned -1. If you include the STEP portion of the statement, the you assign will be used to increment or decrement the value of . Note that Dice! Plus does not check to see if your is negative if is greater than , so make sure that you use a correct if you want to count backwards in a FOR..NEXT loop. The optional EXIT FOR statement can appear anywhere inside the FOR block, and allows you to immediately jump outside the FOR..NEXT loop and continue executing the script with the first line after the NEXT statement. Get --- GET [ , ] is the name of a variable, previously defined with a VAR statement is a string of text to use as a prompt for the user to input a value for GET allows the script to get input from the user. The user will be prompted with a window asking for a number to be input. If you include the optional portion of the statement, your text will be used to prompt the user for input, otherwise a default prompt will be used. The number entered by the user will be stored in the variable, for use elsewhere in the script. GoTo ---- GOTO is the name of any label in the script, do *not* include the starting colon in the name of the label. Allows the script to jump from the current line to any line label in the script. When the GOTO is encountered, the script immediately finds the line label specified in and begins executing the script again at that point. If..EndIF --------- IF ENDIF is a statement that is evaluated to either true or false. are any script statements The IF looks at the following , and if it is true, it processes the lines following the IF statement. If the statement is false, it ignores all lines until it reaches its matching ENDIF statement. The script evaluator keeps track of the IFs and ENDIFs that it encounters, so it will properly match up ENDIFs to their corresponding IFs. You will get an error message if you don't match them up properly yourself, so use indenting to help keep you straight. The IF..ENDIF must be in block form as shown. The IF and ENDIF can never be on the same line. Item ---- See Lists below. Line Labels ----------- : is text constituting the label for the line Starting a line with a colon marks that line as a label. Labels are ignored by the script evaluator unless it encounters a GOTO, in which case it looks for a line label matching the one specified in the GOTO statement. List ---- List Begin ---------- List End -------- See Lists below. Lists ----- LIST is the name of the list that will be used later in the script Lists are a means for you to maintain lists of text or variable items that you can use in other places in the script. At this time, lists are the only way to use text variables. Also, lists are needed to allow selection of items from a pick list window. While the LIST command creates the list, the items of the list are defined in the LIST BEGIN..END block containing the appropriate ITEMS. Using a LIST command on a that already exists will erase the items currently in the list and restore the list to zero items. LIST BEGIN ITEM "" LIST END is the name of the list previously created with a LIST command. is an item to be added to the list. LIST BEGIN starts a block wherein all ITEM lines will be added to the list named in the part of the LIST BEGIN line. LIST END ends the block of items being added to a particular list. Any ITEM commands found outside of a LIST BEGIN..END block are ignored. ITEM tells Dice! Plus to add the item text following the command to the list of items. Text should be enclosed in quote marks. Logical Operators ----------------- & | There are two logical operators currently recognized by the script evaluator: AND, which uses the symbol '&' and OR, which uses the symbol '|' These operators are almost always used exclusively within an IF..ENDIF block to test if AND satisfy the test, or to test if OR satisfies the test. You must use the symbol for the operator, using the text AND or OR will not perform the logical operation. LogOn/LogOff ------------ LOGON LOGOFF Allows for much finer control over what goes into the Long Results box. While CLEARLOG clears everything in the Long Results box when it is used, LOGOFF turns off what gets sent to the Long Results box in the first place. When LOGOFF is used, no more long results will be sent to the Long Results box until the Long Results are turned on again with a LOGON command. While LOGOFF is in effect, it is the same as if you had turned off Long Results in your Preferences dialog box. By default, results are sent to the Long Results box according to the setting in your Preferences dialog box. Open File --------- OPEN FILE , [, { OVER | OVERWRITE | APPEND } ] is the name of an output file to open is the name for the DOS file that will contain items sent to . This name must be a legal DOS file name, but does not have to be the same as . OPEN FILE allows you to open a file to which you can send output from a script running in Dice! Plus. You must specify a , which will be used within your script to address output to the specific output device (file or window) that you wish to use. Using this name is important because you can have multiple output files or windows open at one time. You must specify a as well, so that Dice! Plus will know where to save any output that is being sent to the output device. You can use one of the optional commands to tell Dice! Plus whether the file you are opening should be overwritten, or simply appended to. If you specify OVER or OVERWRITE as the optional command, the DOS file specified will be overwritten with any new data if it already exists. If you specify APPEND as the optional command, the DOS file specifed will simply have any new information appended to the end of the file as it is sent from the script. If you do not specify one of the optional commands, data will be appended to the file by default. You send information to an open file by using the PRINT or PRINTNL commands. See the WINDOWS.DIE script for an example of this set of commands. Open Window ----------- OPEN WINDOW is the name of an output window to open OPEN WINDOW allows you to open an output window to which you can send output from a script running in Dice! Plus. You must specify a , which will be used within your script to address output to the specific output device (file or window) that you wish to use. Using this name is important because you can have multiple output files or windows open at one time. Windows are automatically closed when the script ends, or Dice! Plus is closed, so you will probably need to use a PAUSE command to allow you to view any output sent to a window. You send information to an open window by using the PRINT or PRINTNL commands. See the WINDOWS.DIE script for an example of this set of commands. Pause ----- PAUSE PAUSE allows you to pause the execution of the script, so that you can do such things as read or resize an output window. The PAUSE command will pop up a small window that will stay on top of all the other windows, so that you will be able to continue on with your script again once you are finished. Clicking on the Cancel button during the pause will immediately end your script. Pick List --------- PICKLIST , , [ , ] is the name of a list containing items to choose from is the name of the variable that will be used to contain the user's selection number from the list is the number of the item that should be initially selected for the user. An invalid item number will be set to a valid number automatically. is a string of text to use as a prompt for the selection list PICKLIST allows the script to get input from the user in a different way than that of the GET command. The user will be prompted with a window asking for a selection to be made from the list of available options. If you include the optional portion of the statement, your text will be used to prompt the user for input, otherwise a default prompt will be used. The number of the item in the list corresponding to the selection made by the user will be stored in the variable, for use elsewhere in the script. Items displayed in the pick list will be alphabetized automatically, but the number returned by the script as the users selection will be based on the order of the items as they were added to the list. For example, if a list like this is created: list .Weapons. list begin .Weapons. item "sword" item "knife" item "axe" item "mace" item "hands" item "crossbow" list end the list presented to the user will be alphabetized, so that 'axe' would appear as the first item on the list, and 'sword' would be the last item on the list. However, if the user selects 'sword' from the pick list, the number returned in the would be 1, since 'sword' is the first item added to the list. Likewise, picking 'axe' from the pick list would cause a 3 to be returned in . This allows you to make lists and perform operations based on the order of the list, even if the order you use is not the same order presented to the user. See the example scripts WEAPONS.DIE and DICELIST.DIE for examples of how to use pick lists in conjunction with lists. Print and PrintNL ----------------- PRINT , ["] ["] PRINTNL , ["] ["] is the name of a previously opened file or window is text to be sent to the selected output device PRINT and PRINTNL allow you to print to a previously opened output window or file. The PRINTNL command does the print and adds a carriage return- linefeed combination to move to the next line, while the PRINT command does not, allowing the next print command to add to the current line of the file or the window. As with other commands that deal with text, you should use double quotes to surround any text items that you don't want Dice! Plus to mess with. See the WINDOWS.DIE script for an example of this set of commands. Select Case ----------- SELECT [CASE] [CASE ELSE] [ ] CASE { | } [EXIT SELECT] CASE { IS | TO } [EXIT SELECT] END SELECT is the value that will be used for the following comparisons are any script statements is the value to compare with is a list of values to compare with is a type of comparison to make between and . Comparisons are things like '>=' and '<'. is always considered to be on the left side of the comparison. is a value that marks the low end of a range that is to be checked against is a value that marks the high end of a range that is to be checked against SELECT CASE is a block statement, and it allows you to quickly evaluate the against a variety of options, as if you were using a bunch of IF..ENDIF statements. The SELECT CASE line tells the program that the is the value that should be used in the comparisons that follow in the CASE statements. In this line, the CASE is optional. END SELECT tells the program that the SELECT CASE block has ended, and it can return to processing script lines normally. The CASE statements tell the program what it should be comparing to to see if it should evaluate the . Using the CASE form tells the program to evaluate the only if is equal to . This form of the statement might look like this: CASE 1 Using the CASE form tells the program to evaluate the only if equals any of the values given in the . This form of the statement might look like this: CASE 1,2,3 Using the CASE IS form tells the program to evaluate the only if the between the and the is True. When using this form of the CASE statement, you may not make more than a single comparison, and you may not include any list of values or comparisons; only one comparison is allowed per statement. This kind of statement might look like this: CASE IS <= 3 Using the CASE TO form tells the program to evaluate the only if the is greater than or equal to the value, AND less than or equal to the value. This kind of statement might look like this: CASE 1 TO 3 You can combine the CASE TO and the CASE statement types. This combination may look like this: CASE 1 TO 3, 6, 9 The CASE ELSE option is a special case form, and must be the first CASE option in the SELECT CASE statement, if you choose to use it. CASE ELSE guarantees a true result, so that any statements in the block for a CASE ELSE block will always be executed. This is why it must be first: putting it last will cause it to always override any previous settings from other CASE blocks. NOTE: If you are sure to use EXIT SELECT in each of your CASE statements, you can place the CASE ELSE statement last, because it will never be seen if some other block is true and exits the SELECT CASE block. EXIT SELECT is an optional command that will immediately cause the script to jump down to the END SELECT line. Using EXIT SELECT will increase the speed of your script slightly, because DICE! PLUS will not have to evaluate any more lines after the first True CASE block. NOTE: Like IF..ENDIF statements, just because one of your CASE statements was true does not mean that others will be ignored. If you arrange your CASE statements so that there is some overlap between the values that they are checking, the program will happily execute every CASE that results in a True result. Make sure your statements are ordered the way they need to be to give the results that you want. When using EXIT SELECT commands in your CASE blocks, make sure that your CASE statements are ordered so the proper blocks come first. Time ---- TIME TIME sends the current time to your Long Results box. TIME ignores the settings regarding Long Results, so the results of a TIME command will always appear in the Long Results box. Variables --------- VAR is the name of a variable that will be used later in the script Allows for the definition of a variable. Variables can be any type of text (it ignores capitalization, so it considers lowercase and uppercase to be identical), but it is *STRONGLY* recommended that you pick one consistant variable format and stick with it. If you don't, you may find that you have variable values that are inserted into the inside of what is supposed to be another variable name, rendering it useless and returning a mess. Look at the following example: var r var other r = 5 other = 10 r = other When this example is executed, it will accept 'r' and 'other' as valid variable names, but when it looks at the last two lines, it will do its variable replacement to solve any math in the statement, and then see, internally, these lines: othe5 = 10 r = othe5 The first line doesn't equate to anything, as far as the script is concerned, and the second line is just garbage, so 'r' will end up with a value of 0 at the end of the script. I like to start and end all of my variable names with a period, because it is simple, easy to type, and will rarely become a problem. Starting and ending all variable names with a period, as in '.varname.' will allow you to recognize variables, and makes it very unlikely that one variable will accidentally get placed into the name of another. Using this on the example above would look like this: var .r. var .other. .r. = 5 .other. = 10 .r. = .other. Now, when the variable replacement is done, the 'r' in 'other' does not match the variable name of '.r.' so it is not replaced with the value of '.r.' This means that when the script ends, .r. would be equal to 10. There are two special variables that are used to tell Dice! Plus what to display as the result of a script. 'Result' and 'winresult' are their names. 'Result' will make whatever value it contains appear in the result box when the script ends or a Display command is encountered. 'Winresult' will function like 'result,' but it also causes a message box to pop up containing the value it was assigned.