💾 Archived View for gemini.spam.works › mirrors › textfiles › computers › DOCUMENTATION › dcscrref.t… captured on 2022-06-12 at 06:32:11.
-=-=-=-=-=-=-
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)