////=============================================================================== //// 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 - .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 .APE, if it exists. //// //// (3) The command LOADAPE 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!