textfiles/computers/DOCUMENTATION/dcscrref.txt

Introduction 	1 

Abs 	3 

Action 	3 

Adjustments 	4 

Button 	5 

Continue 	5 

Copy 	6 

Dec 	7 

DefCaveBlk 	7 

DefLandBlk 	8 

DefSpookBlk 	8 

DefWaterBlk 	9 

DefStat 	9 

DefPack 	10 

Display 	11 

DoText 	13 

Drop 	14 

Edit_Player 	15 

EndGame 	16 

Enter 	16 

Failure 	16 

Fight 	17 

Fighting 	17 

Find 	18 

For 	19 

Foreach 	20 

Frame 	21 

GetAction 	22 

GetNum 	23 

GetStr 	24 

Goto 	25 

Gosub 	26 

If 	27 

Inc 	28 

Join 	28 

Leave 	29 

LoadHint 	29 

LoadText 	30 

Locate 	30 

Min, Max 	31 

Move 	32 

Music 	33 

On x Goto, On x Gosub 	34 

Paint 	35 

Pause 	35 

Random 	36 

ReadText 	37 

Restart 	38 

Restore 	39 

Return 	39 

Save 	40 

SavePCX 	40 

Select 	41 

SetBody 	43 

SetBp 	44 

Sgn 	45 

SOUND 	45 

Stats 	46 

Stop 	47 

Success 	47 

System 	48 

Teleport 	49 

Vanish 	50 

Version 	51 

ViewFLI 	52 

ViewPCX 	53 

Voice 	54 

VPlay 	55 

Wait 	55 

While 	56 

Write[ln] 	57 



















D C  -  G A M E S 





Version 4.0







SCRIPT LANGUAGE REFERENCE GUIDE

























(c) DC Software, 1989-1995

7908 Kettlewood Court

Plano Tx 75025

(214) 491-1579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 why 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) and abs(2) are both
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, sign

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	expr1, ...

Is one or more expressions separated by comma that result each
in a number between 0 and 255.

Returns	The sum of the adjustments computed for each value
independently.

Remarks	The adjustment is computed using the values in the
[ATTRIBUTE MODIFIERS] section of the DCCTOKEN.DAT file. The
default  values are:

	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..) 



	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.

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;

Button

Syntax	retval =  button;

Purpose	Find out which mouse button was pressed.

Remarks	When a mouse event is sent to the CONTROL script, the
button function tells you which button was pressed. 1 = Right
Button, 2 = Left Button, 3 = Middle Button.

See Also	keypress, pointx, pointy

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

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

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



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;

Edit_Player

Syntax	edit_player( which [, points, min, max, [flags, ...]]  );

Purpose	Allow access to the player editing screen from the
scripts.

Parameters	which

Indicates which party member is to be edited.  The value is in
the range 1 to 6.

	points

You may specify the number of points that the player may
allocate to the different attributes.  Default is 25.

	min

The player may not set any attribute below this threshold.
Default 9.

	max

The player may not set any attribute above this threshold.
Default 20.

	flags

Edit flags. A 1  allows editing of that field, a 0 does not.
Default is 1. The list of flags is shown in the example.

Remarks	Usually called from the INITGAME script during game
initialization to allow the player to configure his/her
character.  See that script for an extended example.

Example	! Allow player to customize his character within the
limits:

setplayer(1);

player.class = ELF;  ! Fixed class

player.mstr = 12;      ! Fix Strength

edit_player( 1,	! Main Character

	25,		! Distribute 30 points

	8,		! Don't allow a value lower than 8

	25,		! Don;t allow a value higher than 25

	1,		! Allow edit "NAME"

	0,		! Don't allow edit of character class

	1,		! Allow player to select a tile (graphics block)

	0		! Don't allow edit of the first attribute (Strength)

	);		! Allow edit of all other attributes

	

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	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	! Search the npc's backpack for an object (could use
find instead!).

for L0 = 0 to 15 do

    setbp( npc, L0 );

    if npc.bp.count > 0 and npc.bp.name = "The Thing" then

       writeln( "I found it!" );

    endif;

endfor;

if L0 = 16 then writeln( "Didn't find it!" ); endif;

See Also	foreach, find



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. Warning: when you
are fighting, the list of npcs refers to the monsters you are
fighting. Other npcs are not available.

	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;

GetAction

Syntax	retval = getaction;

Purpose	Allows the player to point with the mouse cursor and
click at something, or to type a character on the keyboard.

Returns	retval

Contains the value of the key pressed or mouse event. In the
control script, the keypress variable contains the current
action, so see that script to figure out how to interpret the
retval information.

See Also	keypress, pointx, pointy, button

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 value is returned if you press the ENTER key.

	The value -1 is returned if you press the ESC (escape) key.

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" ,... );

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 list of up to 255 keywords.

Returns	The getstr command will compare the keyword typed by the
player to the list of words provided as parameters and return
the position of the word in the list (if found).

Remarks	You can list up to 255 strings may be listed.

	Only the first 8 characters of the string are compared.

	The comparison is case insensitive (i.e. "Hello" is equal to
"HELLO").

	If you press the ESCape key, the value returned is -1.

	If the word is not found, the value returned is -2 and the word
is left in the string variable s0.

Examples	! Everyone died, so...

writeln( "What do you want to do (Restore, Restart, Quit)" );

L3 = getstr( "Restore", "Restart", "Quit");

on L3 goto :my_restore, :my_restart, :my_quit;

if L3 = -2 then writeln( "I don't know what you mean by ", s0 );

stop;

	:my_quit

	endgame;

	:my_restore

	...

	:my_restart

	...

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 [, x, y  ] ) ] ;

Purpose	If no X,Y is given, the player is asked to point on the
screen using the keyboard or the mouse. If an object or npc is
found at that location, it becomes the current object or npc
respectively.

Returns	ret-val

The distance from the object or npc found (largest of x or y
distance).

Remarks	If the first 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.

	When you specify the X/Y location, that location is verified
immediatly, and the user is NOT asked to point at all. See the
code in the CONTROL script for handling movement and checking
for guards!.

Examples	! Attack someone

writeln( "Attack who?" );

L2 = locate(npc);

if L2 < 0 then stop; ! No one

if L2 > 2 then  writeln( "You must get closer.." );

! goto attack_code;

	! Check before you move to the right..

if locate(npc,player.x + 1, player.y) then

  writeln( "Can't go there!" );..

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 | stop );

Purpose	Starts playing a CMF music

Parameters	filename

The name of the music file. May include a DOS path and be up to
64 chars in length.

	stop

If you use the stop keyword instead of a file name, any music
currently playing is stopped.

Remarks	The filename must be a string constant (surrounded by
double quotes).

	You must have a Sound Blaster compatible card to play music. If
none is present the command is ignored.

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 );

	! Play some music while talking to a character..

music( "healer.cmf" );

... do stuff here ...

:XSTOP

    writeln( "Y'all come back, now!" );

    music( stop );

    stop;

See Also	wait, pause

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.

	%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 first saving to slot 0 and
then 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 last entered the current world.

See Also	restore, restart

SavePCX

Syntax	savepcx( "fname.pcx" );

Purpose	Saves the screen as a PCX format graphics file to the
given filename.

Parameters	"fname.pcx"

A string constant containing a valid DOS filename.

Remarks	The system does not check to make sure the filename is a
valid DOS filename, nor does it add the .PCX extension if it is
not provided.

	If the file already exists, it is overwritten.

Example	! Save the current screen

savepcx( "scrndump.pcx" ); 

See Also	viewpcx

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.

Sgn

Syntax	ret-val = sgn( 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 + sgn( 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 + sgn(player.dex-npc.dex) *
adjustments(player.dex,npc.dex);

Sound

Syntax	sound = boolean-value

if sound then ...

Purpose	If this variable has a non-zero value, sounds are
enabled. It is enabled by default, unless you use the -S run
time argument. You can change the value any time you want to
enable/disable sound.

Remarks	If you don't have a sound card, sound can still be
played through the PC speaker if you convert the voices using
the VOC2PWM and PACK utility.

Example	sound = not sound; ! Turn sound on and off	

Stats

Syntax	stats; or stats ( [ player|npc, ] who );

Purpose	Tells the system to display character statistics in the
menu area, if they are not currently being displayed.

Parameters	player|npc

Specifies whether you want to display a player's statistics or
an NPCs statistics. Note: During a fight, the npcs are the
monsters you are fighting with. The default is player.

	who

Is the index of the player (or npc) whose statistics you want to
display. If you want to display stats on the current player use
group.current or player.index (same thing) or use npc.index for
the current npc.

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.

	If you specify a who of -1, the system will 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.

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

	! The following examples are for save/restore using a DOS
program..

save(0);				! Save current game 

system(  "MYSAVE SAVE" );	! Store it somewhere 

! or:

system( "MYSAVE RESTORE" );! Retrieve a saved game to slot 0

restore(0);				! Cause the system to re-load slot 0.

! or:

group.current = 0;

inc( player.v7 );

save(0);

system( "pkzip.exe ", player.v7, " SAV*.000 " );

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 exactly equivalent to setting the count attribute of
the object to 0, which in effect means that the object is no
longer there.

Example	! 

! Destroy a staff after it has no charges left..

if staff.charges > 1 then

    dec( staff.charges );

else

    writeln( "The ", staff.name, " flashes and disappears.." );

    vanish( staff );

    ! Note that staff.count = 0 has the same effect !

endif;

   

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). The current version as of August
1995 is 4.00 (or 400).

Example	if version < 400 then

   writeln( "ACK! You are using an old (incompatibile) driver!!"
);

   stop;

endif;

ViewFLI

Syntax	viewfli( "filename.fli" [, framedelay] ); 

Purpose	Play a FLI (or FLC) animation on the screen

Parameters	"filename.fli"

Is a quoted string which contains name of the FLI or FLC file to
be played. The filename is used exactly as given. (i.e. an
extension of .FLI or .FLC is NOT automaticly added).

	framedelay

Allows you to override the delay between frames when playing
back the flic.  It is specified in units which occur 18.2 times
per second, so if you want to delay 2 seconds between each
frame, the framedelay would be specified as 36 (closest number
to 36.4). If not specified, the system plays the FLI according
to the information in the file itself.

Remarks	This routine only works in 256 color modes. Thus, if you
are running in VHI resolution (a 16 color mode), the system will
try to play it in VLO mode.

	If the movie fits within the world window, it will be played in
that area.  If it doesn't, but it fits within the screen, the
screen will be cleared to play it.

	The system will re-build call PAINT(WINDOW) or PAINT(SCREEN) as
needed before returning to the script.

See Also	viewpcx

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).

Remarks	Warning: After the image is displayed, control returns
to the script leaving the image displayed on the screen. It is
up to the script writter to decide when the screen should be
re-freshed by calling the PAINT function.

	Note also that you can call PAINT(WINDOW) or PAINT(SCREEN)
depending on whether the image you displayed fits within the
world view window or whether the whole screen is required.

See Also	paint

Voice

Syntax	voice( "keyword" , rsc );

Purpose	Play back a voice recording.

Parameters	keyword

The keyword is a one 1 to 8 character word that identifies the
voice recording stored in a voice resource file.

	rsc

Is the number of the voice resource file (VOICEnnn.RSC) that
contains the voice you want to play. The value must be in the
range 0 to 999 with two exceptions: A value of 1000 indicates
that the system sounds file DCSOUNDS.RSC should be used; and a
value of -1 is ignored and no sound is played.  This parameter
is no longer optional! 

Remarks	Previous versions of DCGAMES (3.x) would use the
npc.voice attribute as the default voice, but that is no longer
supported because you can now do a lot more interaction between
npcs and players.

	Since a -1 is allowed and indicates that no sound should be
played, you don't have to check the npc.voice or player.voice
attribute when you invoke voice. If none is given, nothing
happens!

Examples	! The character tried to open a chest and it was
trapped..

if rand(3) = 0 then ! Trap

    voice( "Explode", 1000 );  ! System Sound !

    writeln( "Argh..." );

endif;

	! Talking to a character

:XTALK

  L0 = getstr( "Hello", "Bye", "Job", "Name", ... );

  if L0 >= 0 then 

     voice( s0, npc.voice );

     on L0 goto XHELLO, XBYE, XJOB, XNAME,...;

  endif;

  writeln( "Beg Pardon?" );

  goto :XTALK

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)