This file lists the SYNTAX of new or modified functions not documented
in the DCGAMES 4.00 Script Reference Guide.
-----------------------------------------------------------------------
The LOADIBK function has been added to be able to load instrument
banks (in Sound Blaster IBK format) from the scripts. Two instrument
banks are provided: MT32.IBK and GMIDI.IBK. The default instrument
bank is MT32. The GMIDI file contains the General MIDI standard 
instruments. If you copy any of this files to DCMUSIC.IBK then it
will be loaded automatically when the game driver starts as the 
default instrument bank. This affects only MIDI music files.

Example:
  loadibk( "GMIDI.IBK" );
  music( "mymusic.mid" );
-----------------------------------------------------------------------
The VIEWPCX, VIEWGIF and VIEWFLI commands now support 2 new arguments.
The FRAME argument centers the image inside the currently defined
frame as set by SET_FRAME(). The PALETTE argument causes the image's
palette to be loaded. The default is for the palette NOT to be loaded,
using instead the current palette. In 4.07 the default was for the 
palette to BE loaded.

Example:
   VIEWPCX( FRAME, "myfile.pcx" );
   VIEWGIF( "myimage.gif", PALETTE );
   VIEWFLI( FRAME, "mymovie.fli", PALETTE );
-----------------------------------------------------------------------
The WAITCK() and TIMECK() functions will wait a specified amount of
time. The parameter is in CLOCK TICKS. There are exactly 18.2 clock
ticks in one second. 

Example:
   ! Move the NPC 10 steps to the right, taking one step
   ! roughly every quarter of a second (5 ticks).
   for L0 = 1 to 10 do
     npc.x = npc.x + 1;
     timeck( 5 );
   endfor;
-----------------------------------------------------------------------
The TIMER function will return the number of clock ticks since
mid night. This can be used to track the passage of real time,
but care must be taken when playing at mid night :)

Example:
   ! Do some stuff for about 10 seconds (182 tics)
   L30 = TIMER; ! Remember the time now..
   while TIMER - L30 < 182 do
     .. keep doing stuff ..
   endwhile;
-----------------------------------------------------------------------
The FOREACH loop construct has been extended so that you can make
a loop through all VISIBLE (on the screen) NPCs or OBJECTS. This 
is very usefull for animation, since you only have to animate the
visible NPCs!

Example:
  foreach VISIBLE npc do
    ...
  endfor;
-----------------------------------------------------------------------
        READTEXT( block# [, line#] );
or      READTEXT( "fname.txt" );

Where:
block#  is the number of the text block (in TEXT.DTA) to read
line#   is the optional line number (if not given, all 16 lines are read)

If "fname.txt" is specified, the given text file is read instead.

NEW FUNCTIONALITY: Starting with version 4.07, the READTEXT function
will look for "DCTXTVHx.PCX" (where VHx is VHI, VH1, etc.). For full
block reads (line# omitted), the text is displayed inside the image
with 10 pixel margins. You can change the PCX image to anything you
want. 

You may also specify line# = -1, which tells READTEXT that an image
has already been displayed (through SET_FRAME + VIEWPCX), and that
the text should be displayed inside that image, instead of DCTXTVHx.PCX).

Example:
   ! Show a book's text inside a book picture...
   setframe( "SPELBOOK.PCX", 35, 15, 15, 15 );
   viewpcx( "SPELBOOK.PCX" );
   readtext( object.text, -1 );

   ! Show a SIGN's text inside the standard PCX background
   readtext( object.text );
-----------------------------------------------------------------------
        SAVEGIF( "FILENAME.GIF" );

Saves the current screen to "filename.gif". See SAVEPCX() for more
details. See also VIEWGIF(), which is identical to VIEWPCX(), except
is shows GIF images.
-----------------------------------------------------------------------
<ret> = MSGBOX( blk#, btn#, b1 [, b2 [, b3]], "message text" );

where:
<ret>   is 0, 1 or 2 depending on which button is pressed
blk#    is the block # from the DCSYSTEM.VHx tiles to display
btn#    is the number of buttons to display (1, 2 or 3)
b1      is the text for button 1
b2      is the text for button 2
b3      is the text for button 3

Example:

   if msgbox( QUESTION, 2, "Yes", "No", "Open it?" ) = 0 then
     .. go ahead and open it..
   endif;

-----------------------------------------------------------------------
        PAINT( SMALL | LARGE | SCREEN | WINDOW );

The new parameters (SMALL and LARGE) switch between the small 
screen mode (window on the left for the world and stats/menu
area on the right) and full screen mode (no stats/menu area).

See also related function "SPLIT"
-----------------------------------------------------------------------
<ret> = SPLIT;

where:
<ret>   is TRUE (non zero) if the game is currently in split mode (with
        the stats/menu/inventory area visible on the right.

Example:

  L0 = SPLIT;                           ! Remember the current mode
  paint( SMALL );                       ! Switch to small mode
  ...                                   ! Do something in small mode
  if not L0 then paint( LARGE ); endif; ! Restore old mode..
-----------------------------------------------------------------------
<ret> = LOS( <from>, <to> [, <tlist>] );

where:
<ret>   is TRUE (non zero) if a path straight line path between
-----------------------------------------------------------------------
<ret> = LOS( <from>, <to> [, <tlist>] );

where:
<ret>   is TRUE (non zero) if a path straight line path between
-----------------------------------------------------------------------
<ret> = LOS( <from>, <to> [, <tlist>] );

where:
<ret>   is TRUE (non zero) if a path straight line path between
        <from> and <to> contains only landscape tiles of the transparency
        given in the (optional) <tlist>.

<from>  is an X/Y location, which can be NPC, PLAYER, OBJECT or two
        numeric expressions. See examples.

<to>    is an X/Y location, which can be NPC, PLAYER, OBJECT or two
        numeric expressions. See examples.

<tlist> is a comma separated list of one or more transparency values
        to be checked.  The default is 0. Names for these values can
        be found in [LAND TRANSPARENCY] in the DCCTOKEN.DAT file,
        where CLEAR = 0 and SOLID = 1.  You can change this and create
        different "levels" of transparency (say 0 to 3) and allow 
        the player to "see" 0 to 2 during the day and 0 to 1 during 
        the night, for example.

Examples:
  The NPC animation routines use LOS to determine if the NPC can see
  the player. If they can, they "walk" towards the player (only the
  hostile NPCs do this).

    if LOS( npc, player ) then
      <move the npc...>
    endif;
 

-----------------------------------------------------------------------
<ret> = LOR( <from>, <to> [, <dlist>] );

where:
<ret>   is TRUE (non zero) if a path straight line path between
        <from> and <to> contains only landscape tiles of the DENSITY
        given in the (optional) <dlist>.

<from>  is an X/Y location, which can be NPC, PLAYER, OBJECT or two
        numeric expressions. See examples.

<to>    is an X/Y location, which can be NPC, PLAYER, OBJECT or two
        numeric expressions. See examples.

<dlist> is a comma separated list of one or more density values to be
        checked.  The default is 0. Names for these values can
        be found in [WORLD DENSITY] in the DCCTOKEN.DAT file, where
        FLAT = 0, ROUGH = 1, etc. Note that the default of 0 is not
        very useful. Players and NPCs can walk on different terrains
        depending on the type of vehicle or type of npc.  For example,
        a Sea Dragon can walk on DEEP and ROUGH WATER.

Examples:
    I didn't use LOR() in any of the examples so far. You might want
    to make it so that an NPC doesn't start moving towards a player
    unless they can SEE the player AND they can REACH the player:
      if LOS( npc, player ) and LOR( npc, player, LAND, ROUGH ) then
        <move the npc...>
      endif;
 
    Note that the above example applies only to land based NPCs. For
    Water based NPCs, it would be:
      if LOS( npc, player ) and LOR( npc, player, DEEP_WATER, ROUGH_WATER ) then
        <move the npc...>
      endif;
 
    Here is an example using LOR to see if a player can REACH a certain
    DOOR from where they are standing:

      if visible( world.doorx(1), world.doory(1) ) and
         LOR( player, world.doorx(1), world.doory(1), FLAT, ROUGH ) then
        <door is visible and player can reach it, so maybe take
         control of the player and "walk" him over to that door..>
        ..
      endif;
 
-----------------------------------------------------------------------
<svar> = SWRITE[LN]( ... );

Identical to a WRITE and WRITELN, except the value is written to the
string variable instead of the text window.

-----------------------------------------------------------------------
PWRITE[LN]( ... );

Identical to a WRITE and WRITELN, except the text is written to the
text window formed within a PCX image file displayed using VIEWPCX()
within the margins specified using SET_FRAME().

Example:
   set_frame( "scroll.pcx", 30, 40, 30, 40, 0 );
   viewpcx ( "scroll.pcx" );
   pwrite( "Name: ", object.name );
   write( "You see a ", object.class, " scroll." );

Note that PWRITE[LN] starts writting at the top of the image and
scrolls down. If you want to clear the image and start writting 
at the top again, you need to re-issue the set_frame() AND the
viewpcx() calls.

-----------------------------------------------------------------------
SET_FRAME( pcx, lft, top, rgt, bot, color );

Where:
  pcx is a file containing a PCX image file.
  lft is the margin from the left.
  top is the margin from the top.
  rgt is the margin on the right.
  bot is the margin on the bottom.
  color is the color to use for the text (default 0 = black).

----------------------------------------------------------------------
VOLUME( v1 [, v2 ] );

Sets the volume level. If only one volume is specified (v1), it is
used for both left and right speakers. If the two are specified, then
they are used for LEFT and RIGHT speakers respectively.

The value of V1 and V2 must be between 0 and 15. Note that 6 is barely
audible while 15 is VERY LOUD!.  The default volume is 12.
---------------------------------------------------------
Syntax     NEW( NPC|OBJECT, x, y, block# );

Purpose    Creates a new npc or object.

Parameters NPC or object to be made
           X - x location
           Y - y location
           Block# - # of tile to be assigned to object/NPC

Remarks    None

Examples

  if group.y > 0 then
    L0 = group.x;
    L1 = group.y - 1;
  elsif group.x > 0 then
    L0 = group.x - 1;
    L1 = group.y;
  else
    L0 = group.x + 1;
    L1 = group.y + 1;
  endif;
  ! Create an NPC next to the player with a tile
  ! selected at random between 30 and 37.
  new(npc,L0,L1, 30 + random(8) );

See CONTROL.SCR for a more detailed example. The
control script uses the DCWORLD defined defaults
for statistics (DEFSTAT array) and tiles (DEFLANDBLK,
DEFWATERBLK, DEFSPOOKBLK and DEFCAVEBLK) to set
the NPC's statistics depending on size (small=0,
medium=1, large=2, pirate boat=3) and the tiles.
This logic starts with label :NEWMONSTER.