Introduction to A.P.E.


Prerequisites:

  1. A knowledge of programming is extremely helpful, but being a sentient being is required.

A.P.E. (Anachronox Programming Environment) is the scripting language layer that controls most of the standard interactivity within the world. If you can click something in the world that triggers a dialog, interface, or event, then chances are APE has played a major part in it. Now before you hop straight into APE, there are a few things you should know about it.

     APE was originally written as a simple dialog parser. However as more interactivity was needed it was added to, and slowly it evolved into a relatively powerful scripting language. This evolution is important to understand when looking at the structure of the language. The first major thing you might notice is that there are two types of functions in APE, a window and a switch, and instead of function names there are sequences. These sequences are comprised of a bank and entry number. A typical window header might look like this:

#window 123:1024

In this case #window is the type, 123 is the bank , and 1024 is the entry . Typically a single bank number is used for an entire map or project. The APE lessons will get into all of this in much greater detail, so don't worry if this doesn't make sense at the moment.

     The next major thing you might notice is that most of APE's power is external from APE itself. Since APE was originally only for dialog, additional features have been written into functions called externs. You can simply call these externs from APE to do an unlimited amount of things, from setting the XYZ of an entity, to adding to inventory, to fading out the screen. There are dozens and dozens of APE externs available, and with the DLL structure of Anachronox, it is even possible to add your own.

To access these script entries in the game, one of the following must occur:

  1. The 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.
  2. The file is named <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 dparse utility, which generates a binary
    output file with a .APE extension. APEs are read into the engine directly, based on the 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 "..\..\dparse 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.

Thanks to Richard Tew we now have an APE decompiler. This is a great tool used to study any of the APE code created for Anachronox. Remember that all code contained in compiled .ape files is copyrighted, thus you cannot use any code you may decompile. Use this tool ONLY to better learn how to program in APE.
Usage of this tool requires the installation of the interpreted object-oriented programming language Python.

These documents are primarily unchanged from their original release.
Creaper 03-22-07 website statistics