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 (binary) or VCF (text) format) from the
scripts. The default instrument bank for WORX was MT32 (roland's
instrument bank). Starting with 4.09 the default is General MIDI.
The instrument bank is only used for playing MIDI files.

DCGAMES includes an MT32 instrument bank and a General MIDI 
instrument bank, as well as utilities to convert IBK to VCF,
edit individual instruments, etc.

If the file DCMUSIC.IBK or DCMUSIC.VCF is present when the game
starts running, then it is loaded automatically.
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. The PALETTE command applies to PCX and GIF only.

Example:
   VIEWPCX( FRAME, "myfile.pcx" );
   VIEWGIF( "myimage.gif", PALETTE );
   VIEWFLI( FRAME, "mymovie.fli" );
-----------------------------------------------------------------------
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 ] ); ! Set the MASTER volume level (for everything)  !
MVOLUME( v1 [, v2] ); ! MUSIC volume only (MIDI, CMF only, not S3M or MOD) !
VVOLUME( v1 [, v2] ); ! VOICE volume only (WAVE or VOC) !

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.

***NOTE*** Starting in 4.09, the volume is specified as a percent, (a
number between 0 and 100). The startup Master volume is 50%, with the
MUSIC and VOICE volumes set to 80% each. The highest volume is attained
by setting the Master volume to 100 and then raising the Music and
Voice volumes to 100 also. In general, you should only use the Master
volume. Note that MOD and S3M volumes are not affected by MVOLUME,
only by VOLUME().
