
////===============================================================================
//// LESSON1.TXT
//// In which we find out how to make dialogue and gameflow scripts.
////===============================================================================
////
////  This file is a sample gameflow script source file for use in Anachronox scripting.
////  For making little APE games, you usually start by defining a window and
////  its contents.  To do so, you define the size, font to use, and so on.
////  Almost all subfields present below are optional, and will correctly default
////  to nice values if not specified.  However, in most cases we're going to want
////  to be pretty specific for most of the windows--you want to know what area you
////  have to work with 90% of the time.
////  
////  To access these script entries in the game, one of the following must occur:
////
////  (1)  This file is named "GLOBAL.TXT" - this designates it as the global
////       gameflow source file, which means the dialogues and switch entries
////       defined here will always be loaded in the engine.  In our case, this
////       is obviously not true, as we are in LESSON1.TXT!
////       
////  (2)  This file - <apefilename>.TXT - has the same name (without file extension)
////       as the map you load.  Whenever we change levels in the game, all entries
////       that were loaded from the previous level are unloaded, and Anachronox will
////       attempt to load in new entries from <apefilename>.APE, if it exists.
////       
////  (3)  The command LOADAPE <apefilename> is executed in the Console, which is
////       _supposed_ to be hidden from the user.  If you do this, then you must
////       then do INVOKE 1000:1 or whatever bank:entry number your main window
////       or switch starts with.  I don't literally mean 1000:1 here, of course!
////       
////  (4)  Put it in the GAMEFLOW directory, and add it to APE Arcade once you've
////       gotten one cartridge in the game.  After that, it is open for anyone
////       playing that installed copy of the game.
////
////  In all cases, this plain-text source file (.TXT) is NEVER directly read by the
////  engine.  It must first be compiled by the APE utility, which generates a binary
////  output file with a .APE extension.  APEs are read into the engine directly,
////  based on the two above listed criteria.
////
////  Example:  I want to make a map-specific script file for the map "HOUSE".
////  This, of course, means that there must be a HOUSE.BSP map file in the
////  ANOXDATA/MAPS directory.  I create a new text file, called HOUSE.TXT, in
////  the ANOXDATA/GAMEFLOW directory.  After composing my scripts, I go to the
////  command prompt (dos shell), change directory to ANOXDATA/GAMEFLOW, and
////  run the command "APE HOUSE".  This will go through your script file
////  (HOUSE.TXT) and, if there are any errors, point them out to you.  If
////  there are NO errors, dparse will tell you it was successful and create a
////  HOUSE.APE file in the same directory.  This is the compiled gameflow
////  script file that Anachronox will load into memory when you enter map House.
////
////===============================================================================


//--------------------------------------------------------------------------------
// Entries: Windows and Switches
//--------------------------------------------------------------------------------
//
//  Gameflow scripts consist of two distinct types of discrete entries:
//
//  WINDOWS are dialogue boxes that pop up, usually with text, a title,
//  a graphical border, a background graphic, and occasionally a list of
//  choices.  They typically stay open until dismissed (either clicked
//  away or a choice is made).  They can have conditional content based
//  on variables set outside the window definition.  This is not a program,
//  but something that defines what is displayed.
//
//  SWITCHES are "nodes" which control the logical flow of script execution.
//  They are executed in an instant, unlike Windows which stay open while
//  they are waiting for user input, etc.  Switches can be used not only for
//  doing intelligent window selection but also for any sort of event control
//  between just about any plugin/module of Anachronox (including Battle
//  events, shops, stats, camera scripts, actors scripts, you name it).
//  Windows can have a startfunction (which sets up variables before the
//  window is drawn, a thinkfunction (which runs actively and can change,
//  through variables, what the window draws), and a finishfunction (which
//  cleans up anything that needs cleaning up, and may pass on global
//  variables to be saved in the save file later). 
//
//  Rules, formats, and examples for using both types of gameflow entries
//  can be found below.  You can have as many windows and switches in a
//  file as you want.


//--------------------------------------------------------------------------------
// Specifying BANK:ENTRY numbers
//--------------------------------------------------------------------------------
//
// Each entry - whether it be a Window or Switch - must have a unique identifier
// associated with it for flow control.  This identifier is given in the form of
// two numbers seperated by a colon, such as "30:4".  This example means
// "bank 30, entry 4", which is very much like saying "chapter 30, verse 4".
// The range for BANK is from (1 to 200,000); the range for ENTRY is (1 to 9,899).
// Anachronox, for the most part, uses banks 1 to 200.
// 
//
// The compiler actually generates a single ID number for each entry based on
// on the following formula:   ID = (BANK * 10000) + ENTRY   The #:# format is
// merely for user-organizational purposes.  Entry "0:0" is reserved to mean
// "no action", or "end of flow" (so you can say "goto 0:0", but you can never
// define your own "#window 0:0").  
//
// NOTE:  It has become the unofficial convention to use one bank number per
// map (or per sub-map area), and not to divide banks across maps.  Also, it
// is standard practice to always use a four digit entry number, where the
// first two digits identify the actor and the last two are used for uniqueness.
// For instance, "14:0302" might be "map #14" (whichever one that may be),
// "npc #3", "second dialogue".  Examples in this file follow these standards.

// (For personal APE game use, one should use a bank number of 50000 and up.
// For temporary use, you can use the bank number of 2, but you cannot be assured
// of it not getting trampled on.  This is often used for testing purposes.
// Anyway, back to our discussion.)

// Let's learn our first GameFlow command.  It's called "body"  Body defines
// what text we want printed in the window.  We'll learn more about it later,
// but here's a simple window definition:

#window 1:1
body "Hello world."

// So, if you compiled this file, loaded it into Anachronox, and invoked that
// window, you'd see "Hello world." printed in a default Anachronox GameFlow
// window.

// What?  You want to do that?  Well, then, go to the MS-DOS prompt and go
// to the directory where Anachronox is installed.

// Go to ANOXDATA\GAMEFLOW.  Here is where the scripts are.  In this same
// directory is a program called "APE".

// So, to compile a script's text file, you type: APE FILENAME
// You don't have to add the .TXT, because it knows it has to be a
// text file.  And, of course, FILENAME is whatever name you want to
// use.  This file's name is called "LESSON1".

// After you compile a file, assuming there are no errors in it, APE
// will create a file called FILENAME.  Compiling this file you are reading
// will result in "LESSON1.APE".

// To run the file, launch Anachronox.  Wait for the logo to appear.
// Press "~" to bring down the console.  [WILL BE MORE DIFFICULT LATER.]
// Type:
//               map test
//
// (To see a window, a map must be loaded, and this is the smallest map.)

// Now type:
//               loadape lesson1
//
// The LOADFLO command will load in any compiled FLO file.  You can load any
// number of FLO files in at the same time.

// Now type:
//               invoke 1:1
//
// This will start the window.
// Press "~" again to get rid of the console.
//
// There is your window!  It uses the default font, the default background,
// and the default window frame.
//
// How do we change those?
//
// Read on in LESSON2.TXT!

