The Best of Select: Games 3

home *** CD-ROM | disk | FTP | other *** search

/ The Best of Select: Games 3 / cd.iso / games / dcg303 / dcscrref.doc < prev next >

Wrap

Text File | 1993-04-08 | 66KB | 2,557 lines

NOTE: This manual was written in a graphics word processing system (Ami Pro 2.0). This text file contains most of the text in the manual, but the graphics are lost and the tables are not formated. When you register, you can get a copy of the documentation for only $5 to cover the cost of printing and shipping. See INVOICE.DOC for details --------------------------------------------------------------------- Introduction ..................................1 Abs ...........................................3 action ........................................3 adjustments ...................................4 continue ......................................5 Dec ...........................................5 DefCaveBlk ....................................6 DefLandBlk ....................................6 DefSpookBlk ...................................7 DefWaterBlk ...................................7 DefStat .......................................8 DefPack .......................................8 Copy ..........................................9 Display .......................................10 DoText ........................................12 Drop ..........................................13 EndGame .......................................14 Enter .........................................14 Failure .......................................14 Fight .........................................15 Fighting ......................................15 Find ..........................................16 For ...........................................17 Foreach .......................................18 Frame .........................................19 GetNum ........................................20 GetStr ........................................21 Goto ..........................................22 Gosub .........................................23 If ............................................24 Inc ...........................................25 Join ..........................................25 Leave .........................................26 LoadHint ......................................26 LoadText ......................................27 Locate ........................................27 Min, Max ......................................28 Move ..........................................29 Music .........................................30 On x Goto, On x Gosub .........................31 Paint .........................................32 Pause .........................................32 Random ........................................33 ReadText ......................................34 Restart .......................................35 Restore .......................................36 Return ........................................36 Save ..........................................37 Select ........................................38 SetBody .......................................41 SetBp .........................................41 Sign ..........................................42 Stats .........................................43 Stop ..........................................44 Success .......................................44 system ........................................45 Teleport ......................................46 Vanish ........................................47 Version .......................................47 ViewPcx .......................................48 Voice .........................................49 VPlay .........................................50 Wait ..........................................50 While .........................................51 Write[ln] .....................................52 D C - G A M E S Version 3.0 SCRIPT LANGUAGE REFERENCE GUIDE (c) DC Software, 1992 6705 Laramie Dr Plano Tx 75023 (214)517-0428 Introduction Purpose This manual presents all of the language commands and functions in alphabetical order and using a consistent presentation for all of them. It is not intended to teach you how to write a script, but rather to describe in detail each and every command and function in the language. The Script Language User's Guide is a more general document that tries to teach you how to write scripts. That manual talks about the different types of scripts, the reasons for writing them, etc. The examples in it include many different commands, since they try to show how to do something rather than teach you how many different things you can do with a single command. The best way to use these manuals is to read the User's Guide from begining to end, and consult the Reference Guide only when you want to know more about a particular command or function. If you are comfortable with programming languages, you can probably read this manual from side to side and end up knowing a lot about the script language itself, but you will NOT find out here the how, when or how of writing scripts. Sincerely, David A. Hernandez Abs Syntax ret-val = abs( expr ); Purpose Returns the absolute value of the numeric expression. Parameters expr Is an arithmetic expression. Returns The absolute value (positive number) of the expression. Remarks The absolute value of a number is the same number, but always with a positive sign. Thus, abs(-2) is 2. Example ! Check to see if there is a great disparity between the character's ! experience and the npc's experience. if abs( player.exp - npc.exp ) > 3 then writeln( "Perhaps another time.." ); else join; ! NPC joins the party.. endif; See Also min, max, random action Syntax ret-val = action; Purpose Find out what action invoked the script. Returns The numeric action code which is actually the number of the entry point at which execution of the script will begin. See Entry Points in the User's Guide for more information on these values. Example ! The following code handles both LOOK and EXAMINE, but EXAMINE ! prints more detail than LOOK. :LOOKING writeln("You see a ", object.name, ". Type ", object.type ); if action = EXAMINE then writeln( ", Class ", object.class, ", Weight: ", object.weight ); endif; ... adjustments Syntax ret-val = adjustments( expr1, ... ); Purpose Compute the adjustments to character attributes indicated by the given set of values. Parameters exprN Is one or more expressions separated by comma that result each in a number between 0 and 255. Returns The sum of the character attribute adjustments indicated by values of each of the expressions in it's arguments. Remarks During regular game play, a character's class determines such factors as the weight it can carry, the type of weapons and/or armor it can use, it's ability to strike moving targets, etc. In addition to the character class, it's standard attributes (such as strength, aim, dexterity, iq, etc.) may increase or decrease these factors. For example, the stronger a character is, the more weight it can carry. The adjustments function will compute the adjustments that should be made to any factor that depends on one or more of these attributes as follows: Value Range Effect 0 8 Decrease by 1 point 9 15 No change 16 18 Increase by 1 point 19 20 Increase by 2 points 21 30 Increase by 3 points 31 40 Increase by 4 points (and so on..) Example ! An ELF has a 1 in 4 chance to detect a trap, adjusted by it's dexterity and ! intelligence. All others have a 1 in 2 chance adjusted by dexterity. if player.type = ELF then L28 = 4 + adjustments( player.dex, player.iq ); else L28 = 2 + adjustments( player.dex ); endif; if random(L28) = 0 then ... trap activated ... else ... trap found ... endif; continue Syntax continue; Purpose Terminate execution of the current script. Remarks This command informs the game driver that while the script has performed some actions, the DEFAULT action should still be taken, if any. Warning Because the OBJECT script contains the default action for objects, that script should never end with a continue. Doing so would indicate that default action is needed, which may result in the object script being run twice for the same action. See Also stop, fight Dec Syntax dec( variable [, expr] ) Parameters variable is any numeric variable or attribute that can be modified from within a script. expr is an optional expression that results in a number that will be substracted from the variable. If omited, the default is 1. Remarks The decrement command will substract the amount indicated (1 if none is given) from the variable or attribute specified. If the expression is negative, then the double substraction results in an addition. Example ! An NPC strikes the player dec( player.hp, npc.weapon.damage ); DefCaveBlk Syntax ret-val = DefCaveBlk( which ); Purpose Returns a graphics block number for cave and dungeon monsters. (Class CAVE_MONSTER) Parameters which Identifies which of the five graphics blocks for random monsters you want. The value must be between 0 and 4, with 0 being the smallest monster and 4 being the toughest. Returns ret-val Is a graphics block record number (between 0 and 255) to be used for random monsters that are found in caves or dungeons. Remarks The DCWORLD parameter configuration screen is used to set the graphics blocks that will be used to generate random monsters. See Also DefLandBlk, DefWaterBlk, DefSpookBlk, DefStat, DefPack DefLandBlk Syntax ret-val = DefLandBlk( which ); Purpose Returns a graphics block number for outdoor, land based monsters. (Class LAND_MONSTER). Parameters which Identifies which of the five graphics blocks for random monsters you want. The value must be between 0 and 4, with 0 being the smallest monster and 4 being the toughest. Returns ret-val Is a graphics block record number (between 0 and 255) to be used for random monsters that are land based. Remarks The DCWORLD parameter configuration screen is used to set the graphics blocks that will be used to generate random monsters. See Also DefCaveBlk, DefWaterBlk, DefSpookBlk, DefStat, DefPack DefSpookBlk Syntax ret-val = DefSpookBlk( which ); Purpose Returns a graphics block number for monsters that you might find in places like hounted houses or cementeries (Class SPOOK_MONSTER). Parameters which Identifies which of the five graphics blocks for random monsters you want. The value must be between 0 and 4, with 0 being the smallest monster and 4 being the toughest. Returns ret-val Is a graphics block record number (between 0 and 255) to be used for random monsters of this type.. Remarks The DCWORLD parameter configuration screen is used to set the graphics blocks that will be used to generate random monsters. See Also DefLandBlk, DefCaveBlk, DefWaterBlk, DefStat, DefPack DefWaterBlk Syntax ret-val = DefWaterBlk( which ); Purpose Returns a graphics block number for aquatic monsters (monsters that swim, class WATER_MONSTER). Parameters which Identifies which of the five graphics blocks for random monsters you want. The value must be between 0 and 4, with 0 being the smallest monster and 3 being the toughest. Number 4 is used to represent a Pirate's Ship, which requires special handling to make sure a pirate's ship doesn't appear on a small pond of water in the middle of town! Returns ret-val Is a graphics block record number (between 0 and 255) to be used for random monsters that are land based. Remarks The DCWORLD parameter configuration screen is used to set the graphics blocks that will be used to generate random monsters. See Also DefLandBlk, DefCaveBlk, DefSpookBlk, DefStat, DefPack DefStat Syntax ret-val = DefStat( which ); Purpose Returns an index into the statistics file (PLAYER.DTA) which holds the statistics that will be used for small, medium, large and pirate monsters. Parameters which Is the size of the character you are creating. 0=Small, 1=Medium and 2=Large, 3=Pirates. Returns ret-val Is the statistics record number (npc.stats) which holds the generic statistics for the size of character you indicated. Remarks The DCWORLD parameter configuration screen is used to set the 4 values that will be used as statistics records for random monsters. See Also DefLandBlk, DefCaveBlk, DefSpookBlk, DefPack DefPack Syntax ret-val = DefPack( which ); Purpose Returns an index into the statistics file (PLAYER.DTA) which holds the statistics record whose backpack contains the items that will be used to generate random treasure. Parameters which Is which of the 3 backpacks should be used (0, 1 or 2). Returns ret-val Is the statistics record number (npc.stats) whose backpack contains items to be used for random treasure. Remarks The DCWORLD parameter configuration screen is used to select the statistics records to be used. The statistics screen is used to modify the records themselves. The default records contain Potions, Rings & Amulets, and Magic Staffs respectively. See Also DefLandBlk, DefCaveBlk, DefSpookBlk, DefStat Copy Syntax copy( source, destination [, count] ); Purpose To create a copy of an object and place it in a given location. Parameters source The copy command can copy an object from curritem, object, group.vehicle, npc.bp, npc.body, npc.weapon, npc.armor, npc.shield, npc.ring, npc.amulet, npc.staff, player.bp, player.body, player.weapon, player.armor, player.shield, player.ring, player.amulet and player.staff. destination The destination can be any of the above, except for the generic locations curritem and object. count This is the number of copies of the object that are placed at the destination. It is an expression that results in a value between 1 and 255. If omited, the default is the number of copies in the source. Remarks The destination must be appropriate to the type of object, for example, you can't move an object of type amulet to player.shield. When an object is copied or moved to the generic destination .body, it will be placed in the correct body section according to the object's type. When the count is greater than one, copies are moved one by one. The character's load is checked before each move to verify that the character can carry the object. If the character's maximum load is reached before all objects have been copied, the failure variable is set to the actual number of copies moved. Examples ! Copy 5 instances of an object from npc.bp to player.bp copy( npc.bp, player.bp, 5 ); if failure then L6 = failure; writeln( player.name, " could only carry ", L6 ); drop( npc.bp, - L6 ); ! Place the rest on the floor.. ! endif; See Also move, failure, drop Display Syntax display ( group );1 display [$[2]] ( {player|npc} [, {matching|type}] );2 display [$[2]] ( {player.body|npc.body} );3 display [$] ( string [, value] [, string ... ] );4 Purpose Display a list of characters, items, etc, on the menu area. Parameters group, player, npc, player.body and npc.body Identify what you want to display in the menu area. matching Used to indicate that only items that match the items of the type carried by the current npc should be displayed. (Used by merchants) type is a number between 0 and 255 (tokens may be used). string is a text string enclosed in quotes. value is either a number (constant or token) or a single variable or attribute whose value is numeric. No arithmetic expressions are permited. Remarks The display command is a powerful tool to display a list of values in the menu area of the screen. If a $ is specified, then values will be displayed as gold or silver pieces (1gp = 10sp). The 2 following the $ indicates that the values should be divided by 2 before being displayed. 1) Displays the current members of the playing party 2) Displays the contents of a character's backpack. If matching is specified, it indicates that only items that match the types of items in the current npc's backpack should be displayed. If type is provided, only items of the specified type are displayed. 3) Displays the set of items being worn by a character (weapon, armor, shield, amulet, ring and staff). 4) Displays a list of strings with or without values associated with it. Examples ! Display the current members display( group ); ! Display the current player's inventory display( player ); ! Display a merchant's inventory (with prices) display$( npc ); ! Display the player's items that the merchant might want to buy.. display$2( player, matching ); ! Display a list of items and a price (numbers in silver pieces) display$( "Magic Ring", 300, "Short Sword", 150, "Banana", 1 ); ! Display a list with numbers (not $) display( "Age", 27, "Strength", npc.str, "Max Weight", npc.mload); See Also select DoText Syntax ret-val = dotext( str-val ); Purpose To perform keyword analysis compatible with pervious prior versions of the DCGAMES system. Parameters str-val Is either a word surrounded by double quotes (string constant), or the string variable S0. Returns ret-val Returns the index of the keyword in the text record (1-16) if found, 0 if not found. Remarks This compares the keyword str-val against the first 8 characters of the string variables S1 through S16. If a match is found, then the text found in the variable that had the matching keyword (minus the keyword) is displayed on the screen and the number (1-16) of the string that had the match is returned. Otherwise, a 0 is returned and no message is displayed. If a SoundBlaster card is present, and the current character or object being processed has a voice file associated with it (voice attribute), then the voice file (VOICE###.VFL, where ### is the value of the voice attribute), is searched for the same keyword, and if present, the corresponding recorded voice is played. If the voice file is not present or the keyword is not found in the voice file, but the SBTALKER text-to-speach translator is present (memory resident), then the text that followed the keyword will be spoken in addition to being displayed. Example ! Talk to the player.. :TALKHERE L9 = getstr( "Hello", "King", "Queen", "Treasure", "Key", "Door" ); if NOT dotext( s0 ) then ! The text record didn't handle the keyword.. on L9 gosub XHELLO, XKING, XQUEEN, XGOLD, XKEY, XDOOR; endif; if S0 <> "Bye" goto TALKHERE; stop; See Also voice, vplay, write, writeln Drop Syntax drop( item [, howmany [, x [, y]]] ); Purpose Get rid of an item that a character is carrying or riding. Parameters item Is the item to be dropped, which must be one of: group.vehicle, curritem, player.bp, player.body, player.weapon, player.armor, player.shield, player.ring, player.amulet, player.staff, npc.bp, npc.body, etc. howmany Is the number of items to be dropped. 0 means all. A negative means that the objects are not to be removed, but rather duplicated. The default value is 1. x, y Is the location in the world where the object will be placed. The default values are the current player's location. Remarks The item will be added to the world's list of objects with a count attribute as indicated by the howmany parameter. If the howmany parameter is 0, the current count attribute of the item being dropped is used. If the howmany parameter is negative, it indicates that a copy should be made of the items. The originals are left intact. If the absolute value of the howmany parameter is greater than the count attribute of the item, then howmany is used. (i.e., you end up with more copies than you had!). Examples ! The following are all equivalent drop( curritem ); ! If the current item is the current backpack item drop( player.bp ); drop( player.bp, 1 ); drop( player.bp, 1, player.x, player.y ); ! If the npc has a weapon, drop it one square to the right of the player if npc.weapon.count then drop( npc.weapon, npc.count, player.x+1, player.y ); endif; EndGame Syntax endgame; Purpose Terminate the game. You have either won or lost, but you cannot continue. Remarks The game displays the copyright screen and returns the user to DOS. The assumption is that an appropriate ending scenario has been executed by the script. Enter Syntax enter( door# ); Purpose Send the playing party through a specific door, wherever it might lead. Parameters door# A numeric expression that indicates which door should in the current world you want to take. Remarks The transfer through the door does not take place until after the script ends execution. You still need to use the stop or continue option to end the script. Failure Syntax ret-val = failure; Purpose To find out if the last major operation failed. Returns ret-val The returns will be non-zero (TRUE) if the last major operation failed to complete successfuly. Example ! A merchant sells an item to a player.. writeln( "Here is your ", npc.bp.name ); copy( npc.bp, player.bp ); if failure then writeln( "The ", npc.bp.name, " is placed on the floor.." ); drop( npc.bp ); endif; See Also success Fight Syntax fight; Purpose Go into fighting mode against the currently selected npc character. Remarks The type of the npc does not have to be HOSTILE. The fight may be against any character of any type. The script is immediatly ended and the fight starts right away. No stop or continue command is needed. Warning Do not use fight after you have done enter. The fight takes place before the transfer is made, but the scripts that execute during and immediately after the fight may get confused. The desired behaviour for this situation is yet to be determined.. See Also fighting Fighting Syntax ret-val = fighting; Purpose To find out if the script is executing during a fight. Returns ret-val A non-zero value (TRUE) is returned when a fight is taking place. Remarks Your script may behave differently depending on whether you are in a fight or not. For example, certain spells may not work during a fight. During a fight, the party and the npc are separated into their respective individuals, and all other characters are removed from the screen. The party may not leave the area during a fight, but pressing the ESC key will exit fighting mode and allow the party to attempt to out-run the enemy. See Also fight Find Syntax retval = find( where [, what [, type]] ); Purpose Find an object or character. Parameters where Identifies where you want to search for the object. It can be one of group, object, npc, player, npc.bp, player.bp, npc.body or player.body. what Is the name of the item or person you are looking for. It must either be a string constant ("like this") or a string attribute of a character or object. type If present, it indicates that the item must not only have the given name, but must also have the given type attribute. The value is either a numeric constant, a numeric token or the type attribute of a character or object. Returns The index attribute of the item (starts with 0), or negative if the item was not found. Remarks When group is searched, what is a character name, and success indicates that the character is a member of the group. When object is searched, the current world is searched for an object with the given name (and type, if given). When npc is searched, the current world is searched for an object with the given name (and type, if given). When player is given, the backpacks of every player in the current group is searched for the given object. The value returned is the index of the player carrying the object, not the index of the object in the backpack. When npc.bp or player.bp is specified, the backpack of the character is searched for the given object. When npc.body or player.body is specified, the items currently worn by the character are searched (weapon, armor, shield, ring, amulet and staff). For Syntax for localvar = expr1 to expr2 [by value] do statements; endfor; Purpose Execute a set of statements a given number of times. Parameters localvar Is a local variable which will be used to hold the loop's current value. expr1 Is the initial value that will be assigned to the local variable. expr2 Is an expression against which the local variable is compared to determine if the statements should be executed or if the loop has ended. value Is a numeric constant (may be negative) which is added to the local variable at the end of every iteration (after the statements are executed). Remarks Note that expr1 is evaluated once, at the begining of the loop, but expr2 is evaluated every time after the value has been added to localvar. The statements between the do and endfor keywords will be executed again and again until local variable's value becomes greater (or less if the value is negative) than expr2. Examples ! Drop all the weapons of all the player's in the group for L7 = 0 to group.size do group.current = L0; if player.weapon.count then drop(player.weapon); endif; endfor; ! Search the npc's backpack for an object (in reverse, to make it fun). for L0 = 15 to 0 by -1 do setbp( npc, L0 ); if npc.bp.count > 0 and npc.bp.name = "The Thing" then writeln( "I found it!" ); endif; endfor; if L0 < 0 then writeln( "Didn't find it!" ); endif; Foreach Syntax foreach item do statements; endfor; Purpose Allow you to process all players, npcs or objects, in order. Parameters item Is one of player, npc or object. Remarks If the item is player, then the player variable will be set to each of the members of the group, consecutively. If the item is npc, then the npc variable will be set to every character in the current world, consecutively. If the item is object, then the object variable will be set to each of the objects in the current world, consecutively. Examples ! Drop the weapons carried by every member of the group foreach player do if player.weapon.count then drop( player.weapon ); endif; endif; ! Check to see if there is a character named 'Morris' in this world. ! (Could have used the find command) foreach npc do if npc.name = "Morris" then writeln( "Found Him!" ); endif; endfor; ! Find out if there is any object at a specific location in the world foreach object do if object.x = 30 and object.y = 23 then writeln("Object ", object.name, " is on the hot spot.." ); endif; endfor; Frame Syntax frame( x, y, block# ); Purpose Display a system graphics block over the current graphics block at the x and y location within the current world. Parameters x Is the horizontal position for the frame. May be an expression. y Is the vertical position for the frame. May be an expression. block# Is the graphics block record number from the system graphics file which contains the frame you wish to display. Remarks If the x, y position is not on the screen, the frame is not shown. The frame is X-ORed (over-imposed) on top of the graphics at the given location. To remove the frame, you re-display the frame at the same location. Example ! Draw a SPLAT type frame on top of the group to indicate they have ! been hit by something (i.e. the members suffered some damage) frame( group.x, group.y, SYS_SPLAT ); wait(1); frame( group.x, group.y, SYS_SPLAT ); ! Draw a bullet being shot from the current player to an npc. ! (This algorithm doesn't really work very well. It is just an example) if player.x < npc.x then L0 = 1; else L0 = -1; endif; if player.y < npc.y then L1 = 1; else L1 = -1; endif; for L3 = player.x to npc.x by L0 do for L4 = player.y to npc.y by L1 do frame( L3, L4, SYS_BULLET ); wait(1); frame(L3, L4, SYS_BULLET ); endfor; endfor; GetNum Syntax retval = getnum( string [, low [, high] ] ); Purpose This function displays a message and asks the user to enter a numeric value between low and high inclusive. The value that the user types is returned as the function's value. Parameters string Is a string to be displayed in the text area of the game screen, before the user is asked to enter a number. low Is the minimum allowed value. It may be an expression. The default is 0. high Is the maximum allowed value. It may be an expression. The default value is 32767. Returns This function returns a number between low and high as typed by the game player, or -1 if the game player pressed the ESCape key. Remarks The low and high values must be between 0 and 32767 inclusive. If low is higher than high, their values are reversed. Example ! Drop some (or all) of a certain object L6 = getnum( "Drop how many", 0, player.bp.count ); if L6 > 0 then drop( player.bp.count, L6 ); endif; GetStr Syntax retval = getstr( "string" [, "string"] ... ); Purpose Asks the user to type in something (a word), then compares the keyword entered with the list of strings and returns the numeric index of the string that matches (if any). Parameters string Is a single word enclosed in double quotes. Returns The getstr command will compare the keyword typed by the player and return the position (starting with 0) of that keyword in the list. If no match is found, a -1 is returned. Remarks You can list up to 255 strings may be listed. Only the first 8 characters of the string are compared. The rest are discarded. The comparison is case insensitive (i.e. "Hello" is equal to "HELLO"). Examples ! Everyone died, so... writeln( "What do you want to do (Restore, Restart, Quit)" ); L3 = getstr( "Restore", "Restart", "Quit"); if L3 = 0 then ... elsif L3 = 1 then ... else endgame; endif; See Also select, on x goto Goto Syntax goto LABEL; Purpose Within the script, transfer the execution to the indicated label. Remarks The LABEL must be defined elsewhere in the script as follows :LABEL Execution of the script continues on the first statement after the indicated label. Example ! Transfer execution goto SKIP; writeln( "You should NOT see this line" ); :SKIP writeln( "You should see this one instead" ); See Also on x goto, if expr goto, gosub, on x gosub and if expr gosub Gosub Syntax gosub LABEL; Purpose Within the script, transfer the execution to the indicated label. Remarks The LABEL must be defined elsewhere in the script as follows :LABEL Execution of the script continues on the first statement after the indicated label. When the return statement is found, execution returns to the first statement after the gosub statement. This statement is used to perform a series of statements at many different points within the same script. Example ! Transfer execution gosub SKIP; writeln( "You should see this message SECOND" ); stop; :SKIP writeln( "You should see this message FIRST!" ); return; writeln( "You should NOT see this message at all" ); See Also return, on x gosub and if expr gosub If Syntax if expr1 then statements1; [elsif expr2 then statements2; ...] [else statements3;] endif; or if expr1 goto label; or if expr1 gosub label; Purpose Execute a group of statements only if the expresion expr is true. Parameters expr1, expr2, ... These are logical expressions which evaluate to a True or False value. True is any non-zero value. False is zero. statements1, statements2, ... These are the statements to be executed the related expression is true. statments3 These are the statements to be executed if NONE of the given expressions are true (i.e. they are all false). Remarks In the second and third form, the goto or gosub are executed only if the expression expr1 evaluates to a non-zero value. Examples ! Drop the current player's weapon if player.weapon.count > 0 then drop( player.weapon ); else writeln( "You are not wielding a weapon" ); endif; Inc Syntax inc( variable [, expr] ) Parameters variable is any numeric variable or attribute that can be modified from within a script. expr is an optional expression that results in a number that will be added to the variable. If omited, the default is 1. Remarks The increment command will add the amount indicated (1 if none is given) to the variable or attribute specified. If the expression is negative, the effect will be to decrement the value. Example ! An player drinked some healing potion, so restore some points.. inc( player.hp, curritem.units ); Join Syntax join; Purpose Cause the npc character to join the current party. Remarks The current npc is removed from the world in which it exists and added to the player's party. The npc variable is cleared (i.e. no npc is selected any longer). The party can hold a maximum of 6 players. If the party is full, the npc will NOT join the party. Leave Syntax leave( whom ); Purpose Cause a player to leave the party. Remarks The player with index whom in the group will leave the party. Note that the main player (index 0 is not allowed to leave the party. Note also that the player's script is NOT invoked to give it a chance to refuse to leave. This is in contrast to the game driver's V)acate command (player pressed letter V), which invokes the player's script, and if the script either does not handle the action, or terminates with continue, then invokes the CONTROL script which in turn executes the a leave command. Example ! When the party enters the King's Castle, if the king is a member of the ! party it means that the King has been rescued and now should leave the ! party and go sit with the queen.. if world.name = "King's Castle" then L0 = find( group, "The King" ); if L0 > 0 then ! Found the king writeln( "The king leaves you and heads for the throne room.." ); L1 = find( npc, "The Queen" ); ! Find out where the Queen is npc.index = L1; ! Select her as current npc. leave( L0, npc.x+1, npc.y ); ! Place the king next to the queen. endif; endif; LoadHint Syntax loadhint; Purpose Load a one-line 'hint' from the hint file (HINT.DTA). Remarks Hints are placed in the HINT.DTA file using the DCWORLD game builder. The hint is selected at random and placed in variable S0. Example ! Display a hint loadhint; writeln( "The beggar gives you a hint:", S0 ); LoadText Syntax loadtext( text-record-# ); Purpose To load a text record (16 lines of text) from the TEXT.DTA file into the 16 string variables S1 through S16. Remarks The text-record-# is an expression that evaluates to a number between 0 and the number of text records in the TEXT.DTA file (minus one). The given record is loaded into the S1 through S16 (not S0). See Also dotext Locate Syntax ret-val = locate [ ( object|npc ) ] ; Purpose To allow the player to point on the screen to an object or character, which becomes the current object or npc. Remarks If the parameter is omited, the player is allowed to point to either an object or a character. If it is given, then the player must point to an object or an npc depending on the parameter that was specified. The returns is the distance (in squares) from the selected object or npc, or -1 if non was selected. Min, Max Syntax ret-val = min( expr [, expr ...] ); or ret-val = max( expr [, expr ...] ); Purpose To obtain the smallest (or largest) of a set of values. Parameters expr Two or more arithmetic expressions separated by commas. A maximum of 255 expressions are allowed. Examples ! Look for the object with the highest weight in the player's backpack L0 = -1; foreach player.bp do L0 = max( L0, player.bp.weight ); endfor; if L0 > 0 then writeln( "The heavyest object has a weight of ", L0, "lbs" ); endif; Move Syntax move( source, destination [, count] ); Purpose To create a copy of an object and place it in a given location. Parameters source The move command can move an object from curritem, object, group.vehicle, npc.bp, npc.body, npc.weapon, npc.armor, npc.shield, npc.ring, npc.amulet, npc.staff, player.bp, player.body, player.weapon, player.armor, player.shield, player.ring, player.amulet and player.staff. destination The destination can be any of the above, except for the generic locations curritem and object. count This is the number of copies of the object to be moved. It must be a value between 1 and the actual number of copies (.count attribute). Remarks The destination must be appropriate to the type of object, for example, you can't move an object of type amulet to player.shield. When an object is copied or moved to the generic destination .body, it will be placed in the correct body section according to the object's type. If there is no space to put the object in the destination, the operation fails, and the number of objects that were actually moved is stored in the failure variable. The backpack can hold 16 items. Each body part can hold only one item. See Also copy, drop, vanish, failure Music Syntax music( filename ); Purpose Starts playing a CMF music file using the Sound Blaster music driver SBFMDRV. Parameters The name of the music file. The filename is a legal DOS filename, and may include a disk drive and path specification. Up to 64 characters long. Remarks The filename must be a string constant (surrounded by double quotes). To enable music, you must have a Sound Blaster card and you must load the memory resident driver SBFMDRV. Consult your Sound Blaster owner's manual for more informatino on SBFMDRV. NOTE: I do not have a program for creating CMF music files. The Sound Blaster card I purchased did not include one either, but I have a basic model and the newer models may include one. I do have access to some shareware and/or public domain programs that can translate ROLAND music files (ROL format) into CMF files, and a few other similar utilities. If you have or know of any shareware or public domain utilities to create music in CMF format I would appreciate a call. Examples ! Play some music and wait until either the music ends, ! the player presses a key or 2 minutes have elapsed. music( "Intro.cmf" ); wait( 180 ); ! Play some music in the background, display a picture and then ! Wait for 2 minutes or until the player presses a key, even if the ! music ends. music( "c:/game/sound/mymusic.cmf"); pause( 180 ); On x Goto, On x Gosub Syntax on expr {goto|gosub} label0, label1, label2, ... labeln; Purpose To support the transfer of control to one of a set of labels depending on the value of an expression. Parameters expr This expression evaluates to a number between 0 and n. label0, label1, .. These are the labels that have been declared elsewhere in the script to receive control of execution. Remarks The difference between goto and gosub is that the return statement will return execution to the statement following the on statement.. If the expression has a negative value or a value greater than n, no transfer takes place, and execution continues on the statement following the on statement. Example ! Talk to the player.. :TALKHERE L9 = getstr( "Hello", "King", "Queen", "Treasure", "Key", "Door" ); loadtext( player.text ); if NOT dotext( s0 ) then ! The text record didn't handle the keyword.. on L9 gosub XHELLO, XKING, XQUEEN, XGOLD, XKEY, XDOOR; endif; if S0 <> "Bye" goto TALKHERE; stop; See Also goto, gosub, if x goto, if x gosub, return Paint Syntax paint( { screen | window } ); Purpose To re-paint either the entire screen or just the game playing window because the script has performed some actions that have probably erased all or part of the window. Remarks This statement is useful when you move the player of the screen by modifying it's x and y attributes. It is also a good idea after running a DOS program, or after you display a PCX graphics file on the screen. See Also viewpcx Pause Syntax pause( time ); Purpose Pauses script execution until the user presses the space key or the specified time has elapsed. Parameters time This parameter is optional. It specifies a limit on the time that the command will wait. (In seconds). Any numeric expression that results in a number between 0 and 32000 seconds. A value of 0 means that no time limit is present. The user MUST press a key to continue. Note that pause(0); can also be written pause;. Remarks Used to wait for the user to read something on the screen or to see a graphics file that is being displayed, Examples ! Display a character's picture, then wait for 2 minutes or until the ! player presses a key if player.picture > 0 then viewpcx( player ); pause(120); paint(screen); endif; See Also wait Random Syntax ret-val = random( expr ); Purpose Return a random number between 0 and expr-1. Parameters expr Is an arithmetic expression that results in a positive number larger than 1. Returns ret-val Is a value between 0 and expr-1. Remarks The expr is value is the number of alternatives you want to consider. Example ! 3 out of every 10 times, write a message if random( 10 ) < 3 then ! 0,1 and 2 writeln( "We have a winner!" ); endif; ! generate a monster of random size on random(5) gosub XTINY, XSMALL, XMEDIUM, XLARGE, XHUGE; ... ! Once out of every 7 times.. if random(7) = 0 then ! or 1 or 2 or .. 6, but just one of them ! gosub DOSOMETHING; endif; ReadText Syntax readtext( block# [, line#] ); or readtext( "filename" ); Purpose To read and display some text on the screen Parameters block# Is the record number from the TEXT.DTA file. line# Is the line number within the block (1 to 16) or 0 (default) which means that the entire text record should be displayed. filename Is the name of a text file to be read and displayed. Remarks If block# is given, the record is read into variables S1 through S16. If line# is non zero, only that line is displayed. The entire lines are displayed, the lines are not expected to contain keywords of any kind (unlike dotext) If a filename is provided, the screen is cleared and the text is displayed in full screen (but still graphics) mode. The paint command should be used to re-paint the screen after the text has been read. Also, the pause command may be used before the paint command to give a chance to the player to read the last page. The text file may contain some control commands that start with the % sign as follows: %MUSIC musicfile.cmf Plays the CMF format file musicfile in the background (The SoundBlaster SBFMDRV.COM must be memory resident). %VIEWPCX pcxfile.pcx Show the PCX graphics file on the screen in the resolution and with the pallete closest to the one specified in the PCX file that is available in the computer. %VPLAY vocfile.voc Plays the VOC format file on the foreground if a SoundBlaster card is present. %READ textfile The DOS text file is read through the SoundBlaster text-to-speach driver (SBTALKER) if installed. %SPEAK a line of text Speaks the line of text through the SoundBlaster text-to-speach driver (SBTALKER) if installed. %PAGE Say "press <SPACE> to continue" and clear the screen when the player does press the space bar. %WAIT time Wait a maximum of time seconds or until all music and/or voice has finished playing. If the time expires before the music or voice is over, the music or voice is stopped. Also, if the user presses SPACE while waiting, the voice and music are stoped and the wait expires. Restart Syntax restart; Purpose Restart the game from the begining, but does not re-run the introduction or cause the player to have to re-create his/her character. Remarks From the DOS prompt, you can re-start the game by typing: C:\games> del sav*.* If you also want to re-create the playing party, type also: C:\games> del party.dta Restore Syntax restore( slot# ); Purpose Restores the game to a previously saved possition. Parameters slot# The # of the saved game, which may be in the range 1 through 999. Remarks The restore command works by first deleting all files with name SAV*.000 from the current directory, and then copying all files of name SAV*.### (the saved game) to files names SAV*.000. The current game is held in slot # 0. Every time you transfer from one world to another, the current game is saved to slot 0. This means that if your game is interrupted for any reason (for example, you accidentaly press Ctrl-Alt-Del), your game state is restored to the time at which you entered the current world. See Also save, restart Return Syntax return; Purpose Returns execution control to the instruction following the last gosub that was executed. Remarks To write a subroutine, you declare a label (which will be used by the gosub statement to invoke it), followed by some script statements, followed by the return statement. Example ! Subroutine to move one step to the right. MOVERIGHT: if group.x < world.x-1 and world.density <= VERY_ROUGH then inc(group.x); endif; return; Save Syntax save( slot# ); Purpose Saves the current game in the given slot. Parameters slot# The slot to be used to save the game. May be in the range 1 through 999. Remarks The save command works by copying all files with name SAV*.000 to files of name SAV*.###. The current game is held in slot # 0. Every time you transfer from one world to another, the current game is saved to slot 0. This means that if your game is interrupted for any reason (for example, you accidentaly press Ctrl-Alt-Del), your game state is restored to the time at which you entered the current world. See Also restore, restart Select Syntax retval = select ( group );1 retval = select [$[2]] ( {player|npc} [, {matching|type}] );2 retval = select [$[2]] ( {player.body|npc.body} );3 retval = select [$] ( string [, value] [, string ... ] );4 Purpose Display a list of characters, items, etc, on the menu area, and then allow the player to select one of the displayed items. The item selected becomes the current generic item of the appropriate type. Parameters group, player, npc, player.body and npc.body Tells the select command what you want to select from. matching Used to indicate that only items that match the items of the type carried by the current npc should be displayed. type is a number or token with a value between 0 and 255. string is a text string enclosed in quotes. value is either a number (constant or token) or a single variable or attribute whose value is numeric. No arithmetic expressions are permited. Returns The number that returns is the index to the selected item. Remarks If a $ is specified, then values will be displayed as gold or silver pieces (1gp = 10sp). The 2 following the $ indicates that the values should be divided by 2 before being displayed. 1) Select a member of the playing party. The selected member (if any) becomes the current player. 2) Select one of the items in the character's backpack. If matching is specified, only items that match the type of items in the current npc's backpack will be displayed. If type is provided, only items of the specified type are displayed. The selected item becomes the character's current .bp item. 3) Select one of the items being worn by the current character. The item selected becomes the current player.body item. If the character is not wearing any items (weapon, armor, shield, ring, amulet or staff), no menu is displayed and the function return a -1. 4) Displays a menu with the options listed (strings), and allows the player to select one of them. It returns the index to the selected one. The first item is 0. If no item is selected (player pressed <ESC> key) the function returns -1. If the list is empty (no item is being carried in the backpack or being worn), the function also returns -1. Examples ! Select the current spokes-person... L3 = select( group ); ! Show list of potions being carried and give it to the npc L8 = display( player, POTION ); If L8 >= 0 then move( player.bp, npc ); endif; ! A merchant offers to sell something. L39 = select$( npc ); if L39 >= 0 then if group.gold >= npc.bp.value then writeln( "Sold ", npc.bp.count, " ", npc.bp.name ); copy( npc.bp, player ); if failure then writeln( "I'll just put it here on the floor.." ); drop( npc.bp ); endif; dec( group.gold, npc.bp.value ); else writeln( "You don't have enough money!" ); endif; else writeln( "Ok.." ); endif; ! Display the player's items that the merchant might want to buy. L39 = select$2( player, matching ); if L39 >= 0 then writleln( "Here is ", $player.bp.value," for your ",player.bp.name); inc( group.gold, player.bp.value / 2 ); move( player.bp, npc ); endif; ! Give the player a choice and take the appropriate action.. :XAGAIN on select("Yes", "No","Maybe") goto XYES, XNO, XMAYBE; goto XNONE; :XYES writeln( "Good stuff..." ); goto SOMEWHERE; :XNO writeln("Too bad..." ); goto SOMEWHERE; :MAYBE writeln( "Will you make up your mind?" ); goto XAGAIN; :SOMEWHERE ! Now do something else.. See Also display SetBody Syntax setbody( which, type ); Purpose Select the worn item represented by the generic variable player.body or npc.body. Parameters which Is one of the npc or player attributes .body, .weapon, .armor, .shield, .ring, .amulet or .staff. type Is an expression that evaluates to one of the six relevant types (represented by tokens WEAPON, ARMOR, SHIELD, RING, AMULET or STAFF). Any other value is invalid. Remarks When specifying npc.body or player.body, the type is required. When specifying npc.weapon, npc.armor, etc, the type is invalid, since it is implied by the attribute itself. SetBp Syntax setbp( which, expr ); Purpose Select the backpack item represented by the generic variable player.bp or npc.bp. Parameters which Is one of npc.bp or player.bp, to identify which backpack you want to set. expr Is an expression resulting in a number between 0 and 15, which indicates the position within the backpack that is to be represented by the generic variable. Remarks The backpack position may be empty (i.e. not contain a valid item). You can tell if an item is present by testing the count attribute. A value of zero always implies that the item does not exist. Sign Syntax ret-val = sign( expr ); Purpose To determine whether an expression is negative, positive or zero. Parameters expr A single expression whose numeric value may be negative, positive or exactly zero. Returns Returns -1 (minus one) if the expression is negative, +1 (plus one) if the expression is positive and 0 (zero) if the expression is exactly zero. Remarks This function may be useful when it is not important to know the magnitude of the difference between two values, but just whether one of them is greater than the other. Examples ! The character is about to hit the npc. The npc has a 1 in 4 chance of ! blocking the attack (25%), but it may be modified to 1 in 3 if the npc has ! a higher dexterity than the player, or to 1 in 5 if the player has the better ! dexterity. L7 = 4 + sign( player.dex - npc.dex ); ! Another version of the above computes an adjustment based on the ! player's AND npc's dexterity using the adjustments function, and adds ! or substracts the adjustment based on who is better. This means that ! A high player dexterity OR a low npc dexterity will decrease the ability ! of the npc to block the attack. L7 = 4 + sign(player.dex-npc.dex) * adjustments(player.dex,npc.dex); Stats Syntax stats; or stats( who ); Purpose Tells the system to display character statistics in the menu area, if they are not currently being displayed. Parameters who Tells the system whose statistics you want to display. -1 means that the system should re-display the statistics we were already showing. This is useful when the menu area has been used for something else, like the display command. 0 to group.size-1 indicates that you wish to display detailed statistics for the given player (usually group.current) group.size (or any number larger than the number of players in the group), indicates that you want to see the group summary statistics (a couple of lines for each character in the group). Remarks Statistics are displayed more or less automaticly, but during the execution of a script, you can use the menu area for other things. If you want to restore the statistics at any time, you may use the stats function. If you omit the parameter (stats;), the group summary statistics are displayed. Example ! Refresh the statistics area stats(-1); ! Display the current player's detailed statistics stats( group.current );Stop Syntax stop; Purpose Terminates execution of the script. Remarks Indicates that the script has performed all required actions. See Also continue, fight Success Syntax ret-val = success; Purpose To find out if the last major operation was successful. Returns ret-val The returns will be non-zero (TRUE) if the last major operation completed successfuly. Example ! A merchant sells an item to a player.. writeln( "Here is your ", npc.bp.name ); copy( npc.bp, player.bp ); if success then writeln( "Sold!" ); else writeln( "The ", npc.bp.name, " is placed on the floor.." ); drop( npc.bp ); endif; See Also failure system Syntax system( argument1 [ , argument2 ... ] ); Purpose Execute a DOS command. Parameters argumentN Is a a string constant, variable or attribute, or a numeric constant, token, variable or attribute. No expressions are allowed. Remarks The system command will create a single string by concatenating the values of the arguments in very much the same way that the writeln command does. The resulting string is assumed to be a DOS command that needs to be executed. If the numeric attributes type or class are displayed, the associated string listed in the token file (DCCTOKEN.DAT) is used, instead of the numeric value. If a numeric argument is preceeded by a $ sign, the value is represented in gold or silver pieces. The failure will be set to the value returned by the DOS command. The value can be tested for non-zero (i.e. just a failure) or for it's numeric value, which can have any meaning that the DOS command chose to give that value. Examples ! Assuming you have a CASINO game that receives as parameters the ! name of the player and the amount of money to start with: system( "CASINO ", player.name, " ", group.gold / 10 ); group.gold = failure * 10; ! Earnings stored in the return value ! Another example. Asume you have a DOS program that manages your ! saved games, you can call: save(0); ! Save current game system( "SAVER SAVE" ); ! Store it somewhere ! or: system( "SAVER RESTORE" ); ! Retrieve a saved game to slot 0 restore(0); ! Cause the system to re-load slot 0. Teleport Syntax teleport( dest_world [, dest_door] ); teleport( dest_world, dest_x, dest_y ); Purpose When the current script finishes execution, the party will be transfered to the given world at the location indicated by the given door. Parameters dest_world Is the index number of the destination world (0-999) dest_door Is the door in the destination world, over which the party will be placed. The default is door 0. dest_x, dest_y The coordinates in the destination world at which the party will be placed (No door is needed). Remarks Unlike the enter command, no door leading from the current world to the destination world is used. The transfer is made directly to the world and location indicated. Examples ! Transfer the party to one of 3 worlds at random L3 = random(3); if L3 = 0 then teleport( 38 ); ! Teleport to world 38, door 0 elsif L3 = 1 then teleport( 5, random(2) ); ! Teleport to world 5, door 0 or 1 (random) else teleport( 43, 25, 32 ); ! Teleport to world 43, location X=25, Y=32 endif; See Also enter Vanish Syntax vanish( object ); Purpose Destroy an object. Parameters object Is the object to be destroyed. It can be any of the following: player.bp, player.body, player.weapon, player.shield, player.armor, player.ring, player.amulet, player.staff, npc.bp, npc.body, npc.weapon, npc.shield, npc.armor, npc.ring, npc.amulet, npc.staff, object, curritem or group.vehicle. Remarks The object is removed and will no longer be available anywhere. This is almost equivalent to setting the count attribute of the object to 0, which in effect means that the object is no longer there. See Also drop, move, copy Version Syntax ret-val = version; Purpose Determine the current version of the DCGAMES software being used to run the adventure. Returns The version of the game driver in use. Remarks The version number is in the hundreds. Version 3.00 is returned as 300 (three hundred). Version 3.01 would be returned as 301 (three hundred and one). Since version 3.0 of DCGAMES is the first version to support scripts, there should be little use for this function. As later versions become available which add new features, you might want to verify that the correct version of the driver is being used. Example if version < 300 then writeln( "Something strange is going on here!" ); endif; ViewPcx Syntax viewpcx( character ); or viewpcx( object ); or viewpcx( world ); or viewpcx( "filename.pcx" ); Purpose Display a PCX graphics file on the screen Parameters character If you specify player or npc, the characters picture attribute will be used to create a filename of the form CPICT###.PCX, where ### is the numeric value of the picture attribute. object If you specify an object (object, curritem, player.bp, etc..) then the object's picture attribute will be used to create a filename of the form OPICT###.PCX, where ### is the numeric value of the picture attribute. world If you specify world, the index attribute of the world (i.e the world's number) will be used to create a filename of the form WORLD###.PCX, where ### is the world's index value. "filename.pcx" Is a quoted string which contains a valid DOS filename. The filename is used exactly as given. (i.e. an extension of .PCX is NOT automaticly added). See Also paint Voice Syntax voice( "keyword" [, vfl ] ); Purpose Play back a voice recording. Parameters keyword The keyword is a one 1 to 8 character word that identifies the voice recording in the VFL file. Each VFL file may contain up to 64 voices of 64K each. vfl Is the voice file (VFL) that contains the voice you want to play. If not specified, then the voice file associated with the current npc (if any) is assumed. Remarks If the character has an associated voice file (voice attribute), the voice file (VOICEnnn.VFL) is searched for a recording with the given keyword. If present, the voice is played back. If the character's voice attribute is -1, it indicates that no voice file is associated with the character. The voice attribute may have values between 0 and 999. If a vfl parameter is proviced, a value of 1000 may be used to indicate that the voice file DCSOUNDS.VFL should be searched instead. This file contains generic sound effects that are used during battles and may be used anywhere by any script. Examples ! The character tried to open a chest and it was trapped.. if rand(3) = 0 then ! Trap voice( "Explode", 1000 ); writeln( "Argh..." ); endif; See Also dotext, vplay, music VPlay Syntax vplay( "voicefile.voc" ); Purpose Play back a voice recording file. Parameters voicefile.voc The file voicefile.voc is loaded and played through the SoundBlastertm if it is present. Remarks Only the SoundBlaster series of audio cards is supported at this time. The file must be stored in the .VOC format, must be shorter than 64K and must fit in available memory. See Also dotext, voice, music Wait Syntax wait( time ); Purpose Wait until all voice and music has finished playing, or time seconds have passed. Parameters time The maximum number of seconds to wait. May be in the range 0 to 32000. Remarks A time of 0 indicates that there is no time limit. If no music is present, this is equivalent to pause(0); The wait ends when either no more voice or music is playing, the user pressed the SPACE bar or the specified time has elapsed. If the time limit is reached or the player presses a key, the music and voice still playing is stoped. Example ! Play some Background music music( "overture.cmf" ); ! Start playing music viewpcx( "map.pcx" ); ! Display a picture on the screen wait(0); ! Wait until the music ends or SPACE bar paint( SCREEN ); ! re-paint the screen. See Also pause, music, voice, vplay, viewpcx, dotext, paint While Syntax while expr do statements; endwhile; Purpose Execute a set of statements as long as the expression is non-zero Parameters expr Is a logical expression which results in a numeric value. Remarks The expression expr is evaluated and the statements are executed until the expression results in a value of zero. Examples ! Ask a question, demand an answer. writeln( "Do you agree? (Yes/No)" ); L3 = getstr( "yes", "no" ); while L3 < 0 do writeln( "You must say Yes or No" ); L3 = getstr( "yes", "no" ); endwhile; Write[ln] Syntax write( argument [ , argument ... ] ); writeln[( argument [, argument] )]; Purpose Display a line of text on the text area of the screen. Parameters argument Is a a string constant, variable or attribute, or a numeric constant, token, variable or attribute. No expressions are allowed. Remarks The write command is used to indicate that subsequent write or writeln commands will continue writing on the same line as this one, unless the line is full. The writeln command indicates that subsequent write or writeln commands will start writing on a new line. If the numeric attributes type or class are displayed, the associated string listed in the token file (DCCTOKEN.DAT) is displayed, instead of the numeric value. If a numeric argument is preceeded by a $ sign, it is displayed in gold/silver pieces. Examples ! The following command writeln( "Sold ", L7, " ", npc.bp.name, " at ", $npc.bp.value ); ! might display Sold 5 Pumkin Pies for 3gp ! if npc.bp.name = "Pumkin Pies" and npc.bp.value = 30 ! The following command write( "You see a ", object.name, " (", object.type, ")" ); if object.type = WEAPON and object.hands = 2 then writeln( " (Two-Handed) " ); else writeln; ! End the line.. endif; ! might display You see a Rusty Knife (Weapon)