Getting Started With E02
E02 is built for creating games through the use of its various editing tools. The two basic types are the Data Editors, and the Script Tools. Either type can be used to alter existing games, but proper use of both could yield totally new and unique games. Each editor and tool have their own, more detailed documentation. An easy way to get started would be to focus on a particular aspect of development and browse that portion of the documentation while attempting to modify an existing game. Piece by piece, a major modification, or an entirely new game can be built this way.

Index:

Functionality Overview
File Setup Information
Level Data and Menu/Gameplay Setup Information
ID, Count, Variable, Constant Value, and Value Alias Name Information
Script Value Tags Information
Script Setup Information
Image Setup Information
Sound and Music Setup Information
Remote Update and Game Listing Information
Packed/Protected Games
Complete Documents Listing

Functionality Overview

The following list is an overview of some of the available functionality. For a complete list of all documentation files, see the end of this page.

Data Editors:
• Level Editor
  For editing levels
• Tile Editor
  For editing tile art, solidity, and animation, and palette colors and animation
• Level Ripper
  For creating levels and tilesets from PCX/TGA images
• Object Editor
  For moving or deleting objects placed in a level, or changing their properties
• Sprite Editor
  For editing sprite boundaries and properties, and viewing and testing animations
Script Tools:
• Game Listing File
  For making the game available to E02
• Game Def
  For setting up certain properties of a game and loading "global" data
• Zone Def
  For setting up certain properties of "zones" and "acts" and loading their data
• Object Def
  For defining "Game Objects" for use in-play
• Font Def
  For creating fonts for use in E02
• Character Def
  For setting up player properties, art, and sound effects
• Music Def
  For loading music
• Sound Effect Def
  For loading sound effects
• Status Script
  For creating logos, title screens, status displays, level intros/outtros, menus, intermissions, etc
• Functions
  For level init, animations, menu selection events, level events, object/player control, etc

File Setup Information

Certain files are absolutely necesary for a stand-alone game, and must be in certain places. Be sure to pay special attention to where the "Game Listing", "Game Def", and "Zone Def" files belong, and how to use them.

Aside from Game-global data, games built using E02 are made up of "Zones", which themselves are broken up into "Acts". "Zones" are a collection of data that make up any one level, menu screen, intro/ending sequence, etc, depending on how they are used. "Acts" are sub-sets of data within a "Zone" that are generally used to group similar levels together. Both are defined in the Zone Def files that appear in each "Zone" folder.

"Zone" folders are named by their Zone ID number (which must contain at least two digits), such as "zone00" for when the game's "Zone" setting is set to 0. Any number value may be used for Zone IDs, and they do not need to be sequential. Registers 3 and 4 represent the current "Zone" and "Act" respectively, however, they only have an effect when they are tested by scripted game events, or when Register 7, "InLevel" is set to 0, which causes E02 to reload "Zone" and "Act" data. The simplest way to fully switch levels is to use the _SetLevel command, which takes care of all three.

Files used with E02 must not use long filenames. Instead, their names must consist only of 8 characters, and 3 characters for the suffix (12345678.123, 8charfil.def). Not all supported platforms allow long filenames.

Files and file references must have consistent casing. Some supported platforms are case-sensitive. Referencing a file named "filename.ext" when the file on disk is "filename.ext" will work. Referencing a file named "FileName.ext" when the file on disk is "filename.ext" will not work. All files and folders expected by E02 itself are assumed to be all lower-case (such as "game.def", "zone00/zone.def", "keymap.def", etc). Files referenced by scripts may use any casing as long as the actual file and all references to it match exactly. E02 cannot enforce this restriction on platforms that are case-insensitive, so a practice such as limiting all files and folders strictly to lower-case names would be an easy way to avoid mistakes that will only cause errors for other users.

For all script file types, please also view previously-created scripts as well as the documentation to get a deeper understanding of how they work.

Level Data and Menu/Gameplay Setup Information

Level, Tile, and Object files that must be made available to any particular level must be loaded by the appropriate Script Commands in that level's "Act Init" Function. If none of those commands are called, the level will start with an empty level, blank tiles, and no objects. When files are loaded with those commands, they become the current Level, Tile, and Object files, which will be used for any saving/loading initiated within the editors. These files must be specified by these commands even if they do not exist (blank ones will be created if they do not exist), because this is the only way to supply filenames to the editor. Otherwise, data cannot be saved.

The "Act Init" Function must also call any "Object" that is to be used in the current level, whether it is a gameplay level, a menu "level", a title screen/intermission "level", or any other type of screen. Built-in objects are very necesary, such as the tile plane object for displaying planes, the player move and draw objects for making a player character available, and the Script Objects, for displaying Status Scripts. Please see the "Zone Def", Function, and Built-in Object documentation for more information. The "SpawnObject" Command will be of particular interest.

ID, Count, Variable, Constant Value, and Value Alias Name Information

Remember that ID numbers for everything start with the number 0, not the number 1. The very first ID number for anything must be 0, and the very last must be the total number of entries minus 1. The total number of entries in any list will be the ID number of the final entry plus 1, because the 0 entry also counts. (Example: 0, 1, 2, 3 - there are 4 total values listed). This includes entries within scripts, as well as ID numbers for "acts". ("Act 1" has the ID number 0)

"Variables" are areas of memory that are set aside to store number values that can be changed. Variables are used to store temporary values, counters, changeable settings, etc. They are laid out as lists, and each one is referenced by its "ID number" from within that list. When a Script Command requires a "Variable ID" as a Parameter, the number entered for the Parameter is taken as the ID number of a Variable, and the value stored in that Variable is used for the operation. There are three basic types of Variables: Game Variables/Registers, Player Variables, Object Variables

"Constant Values" are essentially the opposite of Variables; they are "Constant", they never change. "Constant Values" are used when a known value must be used in a mathematical expression, to initialize a Variable, or to pass as known Parameters to any other Command. When a Script Command requires a "Constant Value" as a Parameter, the value entered as the parameter is taken literally; that value is used for the operation.

All "Constant Values" are treated as Base 10 (Decimal) by default, however, Base 16 (Hexadecimal) and Base 2 (Binary) values may be entered by prefixing the number value with '$' or '%', respectively (For example, "31" (Decimal), "$1F" (Hex), and "%00011111" (Binary) all represent the same value). On occasions when the content of a string is being manipulated or tested, the ASCII character code of any given ASCII character may be expressed by placing a single quote in front of the character itself (such as using 's to represent the ASCII character 's' rather than the decimal form of its ASCII character code, which is 83)

-Advanced- "Constant Value" versions of mathematical Commands may be used to perform math operations on a Variable ID (the Variable's reference number, not the contents of that variable) by using the special Variable reference "Tags" (as described below), entering the ID of that Variable as the "Constant Value". This is also useful for storing Variable IDs in "Registers", for use when a Command that requests a Variable ID allows that ID to be obtained from a "Register". Furthermore, the extra "Tag" "O" may be used in conjunction with the "G", "Z", and "A" "Tags" to reference an Object Type ID (as in "OZ4", to reference "Zone"-specific Object Type 4).

"Aliases", textual names that can be assigned number values, can be used in place of any Variable ID, Command ID, or Constant Value to aid in readability and memorization. Aliases are defined using Alias Files, which are loaded by an Alias Def. For a game script set to use Aliases, an Alias Def must be present in the same folder as the "game.def" Game Def file, and must have the name "alias.def". All Command IDs, built-in variables, and many parameter and settings values have default Aliases that are defined by the Alias Files in the folder "default/alias", which are also used throughout this documentation. When an Alias Name is entered in place of a value, it must be preceded with an underscore to cause E02 to treat it as an Alias (for example, the default Alias Name for Script Command 154 is "Reg=Chr+Const", so, instead of entering the value 154, the text "_Reg=Chr+Const" can be used to represent the same Command).

Script Value Tags Information

There also several "tags" that may be used on certain script lines to change the meaning of a Number Value. They are used to make keeping track of certain IDs easier. When they are to be used, they must come immediately before the value they are meant to alter, without spaces, such as "A2", "r0", "U13", etc.

Some special cases use other types of "tags" that aren't listed here, but are documented where appropriate.

"Tags" are also used in the same way when substituting Aliases for ID values, such as in "r_Curr_Player", "C_Player_VPX_Speed", and "A_Player_X_Vel". As a general rule, Alias definitions do not include the tags themselves, as this could lead to tag type conflicts in some situations.


• "G", "Z", "A" (Game/Zone/Act data IDs)
  These tags, standing for "Game", "Zone", and "Act" may be used in certain places in the script to signify that a data ID number represents data that was loaded by a "Game Def" as "global" data, or by a "Zone Def" as either "Zone" data or "Act" data. These tags are useful because when they are available for use, you won't need to keep track of the real data ID of the data as it is understood by the game. These tags allow you to use the ID of the data as it is shown in the script that loads it. If these tags are not available, and the Real data ID of any data must be used, it is simple enough to calculate the ID. "Game Data" IDs are the ID that they are given from the script that loads them. Starting at 0 for the first ID, it is the order in which they appear in that script. For "Zone Data", its script ID is found in the same way as a "Game Data", but its Real ID is found by adding the total number of "Game Data" of the same type to its "Script ID". "Act Data" is found in a similar way, but its Real ID is its "Script ID" plus the total number of "Game Data" of the same type, plus the total number of "Zone Data" of the same type. It may sound complicated at first, but it is actually very simple once you've come to understand it. These tags may only be used where a script's documentation says they are available.
  
  
• "R", "r" (Data stored in "Registers"/"Game Variables")
  These tags are used when the value inside a "Register" should be taken as a Parameter to a Command. These can be used so that when a Command requires a number value, it can use a value that was stored in memory by another Command instead of using a fixed value that was written in the script. This is very useful, although it is only available where the Command descriptions in the documentation say that they may be used. Lower-case r represents a main game "Register", whereas capital R represents a user-created "Register". More information is available in the "Game Variable" documentation.
  
  
• "U" ("Register"/"Game Variable" IDs)
  This tag is used when the ID number of a "Register" (not the value stored inside it) is necesary. This tag is only used with certain Commands, such as mathematical and conditional Commands. Main game "Registers" are used by simply using their ID, while user-created "Registers" use the tag "U", as in "User". More information is available in the "Game Variable" documentation.
  
  
• "C", "c", "A", "a" (Player Variable IDs)
  These tags are used when the ID number of a Built-in or User-defined Player Constants or Player Active Variable is required as a parameter to a Command. Although the tag "A" is also used to signify "Act" data, it does not conflict with its use for Player Variables, as the difference is context-based. More information is available in the "Player Variable" documentation.
  
  
• "E" (Object Variable IDs)
  This tag is used to refer to the ID number of one of an Object's user-defined "Extra Variables", while Built-In Object Variable IDs should be listed without a prefix "tag". More information is available in the "Object Variable" documentation.
  
  

Script Setup Information

Each script file, although it uses its own extension, is a plain text file. It is best to work with these files in a fixed-width font viewer, such as Windows' "Notepad". If the file becomes too large, there are other free viewers, such as "Crimson Editor", which is much more powerful and much less resource-intensive. A wide variety of viewers for non-Windows systems are also available from various sources.

The basic format of the script files is very simple. Each line consists of a "Header String" and a "Data String". The header string is NOT interpreted in any way by the program; it is ignored, and is simply used as reference. It can contain any text that describes what is required on that particular line, or even no text at all, but it is generally best to use the text given in the documentation for each script type. The end of the Header String, and the beginning of the Data String is referenced by a colon (:). The colon must not ever be used at any time for any reason other than signifying the start of a Data String. The end of a Data String is signified by an enter keypress. No data is interpreted beyond that point, as the program then disregards everything else until it finds another colon. As an example, an entry in a script file may look like this:

Header String: Data String
Num Of Sound Effects: 32

In the example, the string "Num Of Sound Effects" is ignored entirely, and is used only to tell the person reading the script that the data supplied is used by the program to determine the number of sound effects to be loaded. The Data String will either be regarded as a Text String or a Number Value, which is determined during the processing of the script. Each script type documentation states exactly what data is expected in each part of each script. It is very important to follow the format exactly, because if the format is broken, the program will not be able to recover, and will either act inappropriately, or crash.

The semicolon (;) is used throughout many of the scripts to signify a comment. The script parser will stop interpreting a line if a semicolon is met.

While all other aspects of a script use only the colon (:) as a line identifier, Functions use a few others to identify certain parts of the function itself, which are detailed in their own documentation

Image Setup Information

Image files used to store image data for use in E02 can be any size as long as height and width are both even, but must be 256-color PCX "Version 5", or 256-color RLE-compressed or uncompressed TGA. If the images aren't saved in one of these formats, they will be interpreted wrong, and the data taken will either appear as garbage or cause a crash.

E02 graphics are 256-color palettized, and so, the display colors of graphics loaded from image files depend on the palette settings within E02 at the time they are displayed. The full in-game palette is broken into two parts-

"Level Palette"


This area is controlled by settings in a Tile File, and set up using the Level Ripper and/or the Tile Editor. There are three possible size settings-



	64		One palette section (0-63) is controlled by Tile File data. "Water" overlay is allowed (palette indexes 128-255 are reserved as mirrors of 0-127, modified by the "water color"). Indexes 64-127 are left for the "Global Palette".
	128		Two palette sections (0-63, 128-191) are controlled by Tile File data. "Water" overlay is not allowed. Indexes 64-127 and 192-255 are left for the "Global Palette".
	192		Three palette sections (0-63, 128-191, 129-255) are controlled by Tile File data. "Water" overlay is not allowed. Indexes 64-127 are left for the "Global Palette".


There may be one or more of these palettes stored in a single Tile File, which may be set as the active palette by the _Pal_Switch Script Command. Each of these palettes may also contain data to animate/cycle colors both within and between each index, which may be set up using the Palette Animation area of the Palette Editor.

When a Tile File is loaded, that file's "Palette 0" becomes E02's active Level Palette.


"Global Palette"


This area's size is determined by the current "Level Palette" setting, as described above. The colors are loaded from either "globpal.pcx" or "globpal.tga" in the current game's "Art" folder. If the "Art" folder doesn't exist, or neither of these files exist, the file is loaded from E02's "Default/Art" folder. If both a PCX and a TGA file exist, the PCX file will be used. The colors are read from the same indexes of the image file's palette at which they will be used in E02 (64-127, 128-191, 192-255).

Indexes 64-127 will remain the same throughout gameplay, unless modified manually. Indexes 128-255 will be overwritten if a Level Palete of size 64 or 192 is activated.

If any portion of the the active palette's "Global Palette" section is ever modified, it can be restored by the _Pal_RestoreGlobal Script Command.

The existing "Global Palette" can be replaced at any time by use of the _Pal_LoadNewGlobal Script Command.


Both tiles and sprites may use either area of the palette, and either area may be manipulated by the _Pal_SetRange command. If, after that command has been used to modify the palette, the original colors need to be restored, the _Pal_Switch and _Pal_RestoreGlobal commands may be used.

Palette entry 0 is reserved for "transparancy", meaning that any area of any graphic that is drawn with that index will not actually be drawn to the screen, and anything that was drawn to the screen before will show through. This entry is also the "Backdrop Color". This is the color that the screen will be filled with if a Backdrop Object was spawned.

Sound and Music Setup Information

E02 uses uncompressed WAV format for sound effects. It will recognize sounds of any frequency, 8- or 16-bit, and stereo or mono, but they will be converted to 8-bit mono durong load. WAV files of similar type may also be loaded as music, as well as XM files with up to 16 channels. XM support is based on the XM standard - special extensions to the format added by various tracker programs are not supported.

Remote Update and Game Listing Information

E02 features two methods for other authors to provide their content to end-users through the E02 interface. Those methods are Repositories support, and Automatic Updates Checking. Please view the provided links for examples of each of the mentioned files.

The Automatic Updates system allows games to reference a remote location that contains update information. When the remote version number is greater than the local version number, the game is flagged as having an available update (noted by a "*" in the game selection interface), and E02 can obtain information about the update (assuming it is provided by the author), and download the updated version directly from within the same interface.

The GDF file for the game contains two entries that provide the remote location at which to check for updates. The files that E02 expects to find at the given location are as follows:


• "Ver"- This file contains the updated version number for the game, stored as plaintext. This number must appear at the very beginning of the file, and cannot contain any symbols. Anything that comes after the number will be ignored, and if the first character in the file is non-numeric, it will be interpreted as "0". The preferred format is a 6-digit date- "YYMMDD", such as "August 20th, 2010" becoming "100820"
  
  
• "Info.txt"- This is a two-part file from which E02 will read information about the game and its updates. The first line of this file must consist of the full path and filename (excluding the hostname [as in "http://wwww.host.com"]) of the files list. Each of the following lines are displayed in the "info" interface, and may be no longer than 40 characters, as that will fill the width of the interface, and there is no automatic word wrapping. When obtaining update information, E02 will search for the first occurrence of a line consisting only of exactly 40 hyphens ("-"), indicating the start of the updates section
  
  
• Files list- This is the file that is referenced by the first line of "Info.txt", and contains a list of each file that must be downloaded for this game. The first line in this file must contain the name of the Game Folder that this game should reside in. If the folder does not yet exist locally, it will be created. All other file operations will be performed relative to this folder (IE: This folder becomes the "root" during this operation, and any file that resides outside of this game's folder will require backtracking [for example, the path used to store the ".gdf" file would be "../gdf"]). The information that follows is a list of two entries per file. The first entry for each file is its full path on the remote server (excluding the hostname), and the second entry is the relative path into which it should be placed locally. If an entry is preceded by a greater than sign (">"), it is regarded as a folder creation entry, and a folder of that name will be created if it does not already exist.
  

The Repositories support allows for special files placed into the "repo" folder to give E02 access to other games and messages lists. This feature will only be available if the "repo" folder contains at least one file other than "default.txt". These files may have any name, as long as their extension is ".txt". They are plaintext, and consist of only three lines:


• Display name of the repository (no more than 40 characters)
  
• Hostname of the repository (such as "http://www.hostname.com")
  
• Server path of the repository (such as "E02/Games/")
  

The files that E02 expects to find at that location are as follows:


• "List.txt"- This file contains the primary list for the repository, which may contain references to sublists. Each list entry is made up of two lines:
  
  
  • Display name of the list entry
  • Full server path of the file/folder referenced by the entry, excluding the hostname
  
  If the display name is preceded by a "<" character or succeded by a ">" character, then it is regarded as a reference to another list. Otherwise, it is regarded as a reference to a game's info text. The "full server path" is the full remote path to the desired list or info file, excluding the hostname
  
  
• "Msg/Msg"- This is, as it reads, a file named "Msg" in a folder named "Msg". This file contains a list of references to selectable update messages for this repository, with each entry consisting of two lines in the following format:
  
  
  • Update number / Filename- This entry begins with a six-digit date in the "YYMMDD" format, such as "August 20th, 2010" becoming "100820", followed by any other identifying text, and is used as the filename to load for this entry's update message. This allows for ordering updates, and separate updates on the same date, such as a game update being named "100820Game" and a situational update being named "100820Status". No path should be provided, as the ID number should be the first thing on each line. These files are expected to be in the same "Msg" folder
  • Display name of the update- This is usually the date in "YY.MM.DD" format, followed by any descriptive subject-style text, such that the entire line is no longer than 40 characters

If the display name is preceded by a "<" character or succeded by a ">" character, then it is regarded as a reference to another list. Otherwise, it is regarded as a reference to a game's "Info.txt" (the same as described above for automatic updates). The "full server path" is the full remote path to the desired list or info file, excluding the hostname

Packed/Protected Games

Game filesets may be "packed" into a single^* file named "game.e02", either by using the "-pack" command-line parameter, or by using the "Pack Game" option in the "Utilities" menu from withtin the main program interface. When present, this file takes precedence over any existing game files. For changes to separate game files to be recognized by E02, the "game.e02" file must first be removed from that game's root folder.

There are several advantages to using the packed format:


• The "game.e02" file is encrypted, so that the files contained cannot be read outside of E02, or modified in any meaningful way. This protects proprietary content and prevents cheating
  
• When a packed game is being run, editor access is disabled. This disallows simple access to game assets and prevents cheating
  
• Due to eliminating sector padding, and stripping and partial pre-processing of scripts, the "game.e02" filesize is somewhat smaller than the total size of the original fileset
  
• Due to stripping and partial pre-processing of scripts, packed games enjoy a very slightly shorter load time
  

^*The following files (in the game's root folder) are ignored by the packing process:


• All "key???.def" files- These files must remain external to the packfile so that users can modify their key configuration
  
• All ".txt" files- This causes "info.txt" not to take up space in "game.e02", as well as any other informational text the author may wish to provide
  
• The "dump" folder- This folder is only meaningful to the author during development, and so is ignored during packing so that it doesn't need to be removed from the game folder
  
• The "docs" folder- If the author creates a "docs" folder in which to place documentation files for the game, they will be excluded from the "game.e02" pack
  
• The "alias" folder and "alias.def"- Aliases are stripped and converted to their hard number values when the game is Packed, and so any Alias Files that were used become unnecessary
  
• The "game.e02" file- If a pack file already exists within the game folder, it will be ignored during the packing process and overwritten by the new game pack
  

When using the packed format, it is possible to protect only some files and not others. When E02 is made to call on a file that does not exist in "game.e02", it will check to see if that file exists externally, and if so, open it. Files that do exist within "game.e02" will override any external files with which they share a common path and filename (thus preventing modification by replacing the game files externally), so, files that should remain external must be removed from the fileset before it is packed so that they are not placed into the "game.e02" file. This can be useful, for example, for savegames, game settings, games with their own editors, games for which users should otherwise still be provided a limited ability to modify in some way, or for any other purpose.

Complete Documents Listing
(in alphabetical order)

• Alias Def.html
• Alias File.html
• Animation.html
• Built-in Objects.html
• Character Def.html
• Command Line.html
• Font Def.html
• Font File.html
• Functions.html
• /Funcs
  • Animation.html
  • Files.html
  • Function Control.html
  • General.html
  • HotSpot.html
  • /If
    • Collision.html
    • Flags.html
    • General.html
    • Variables.html
  • Level Control.html
  • Keywords.html
  • /Math
    • AbsValue.html
    • Add.html
    • AND.html
    • Array.html
    • Divide.html
    • Equal.html
    • Flags.html
    • Modulus.html
    • Multiply.html
    • Negate.html
    • OR.html
    • Power.html
    • Shift.html
    • Subtract.html
    • Vector.html
    • XOR.html
  • Objects.html
  • Palette.html
  • Players.html
  • Random.html
  • Sound.html
  • Status Objects.html
  • Switch.html
  • Table.html
  • While.html
• Game Def.html
• Game Listing File.html
• Game Objects.html
• Game Variables.html
• Getting Started.html
• KeyMap.html
• KeyTable.html
• Levels.html
• Level Editor.html
• Level Looping.html
• Level Ripper.html
• Music Def.html
• Object Collisions.html
• Object Debug Drawing.html
• Object Debug Placement.html
• Object Def.html
• Object Drawers.html
• Object Editor.html
• Object Movers.html
• Object Projectile Collisions.html
• Object Variables.html
• Player Management.html
• Player Variables.html
• ReadMe.html
• Sound Effect Def.html
• Sprite Editor.html
• Sprites.html
• Status Script.html
• Table Def.html
• Table File.html
• Tile Editor.html
• Tile Selector.html
• What's New.html
• XM.html
• Zone Def.html