EGM_format

This page documents the specifications of the actual current
implementation of the EGM format. For the general concepts and proposal,
see EGM.

EGM is the sovereign file format of all game data storage format. Except
Game Maker can't load it, and almost certainly never will will
soon have its own format, .gmx and .gmz, using the same concept.

Overview

EGM is an archived format. Specifically, it is based on ZIP, modeled
loosely after JAR. With this design decision come several key advantages
over the original formats GM6, GMK, and GM81. Highlights of these are as
follows:

1. The entire file does not need rewritten each save. This means
   that large files can be modified quickly and easily; new resources
   can be added anywhere in the file according to the zip format,
   support for which is very broad.
2. Corruption is an unlikelihood. While it is possible for
   corruption of files to occur, it is unlikely, and the majority of
   existing resources will be unaffected. Users can recover unharmed
   resources manually if necessary.
3. Manual manipulation is simple. Anyone who can open a zip archive
   can access the resources directly and modify them in a custom
   editor.
4. High extensibility. Since the archive does not list resources in
   any set order, any recognized resources can be loaded, and the rest
   can be ignored until support is added (even through a plugin).
   Moreover, these unrecognized additions and attributes can be easily
   preserved through a save.
5. The file can be left as a folder until transport becomes
   necessary. Two major capabilities follow from this facet:
   • Files can be placed under version control, such as SVN or GIT.
   • Load and save times for executables can be decimated by keeping
     the files handy externally.

Format specifics

Resources are stored in the EGM format in a series of folders. The
folders represent the resource tree; there is one folder for each
resource type in the root of the archive. Each directory optionally
contains a Table of Contents to
indicate the order that the resources should visually appear, as
lexicographic order is oftentimes undesired.

From there, each resource is given exactly one EYAML
Descriptor File. For example, a sprite
by the name of spr_player would be given /Sprites/spr_player.ey as its
descriptor. Since eYAML is plaintext, this file does not contain the
resource data; only properties and information about it. To include that
data, the file can outsource to a separate binary or info file in the
same directory simply by naming it in the Data member. For instance,
spr_player.ey may list Data: spr_player.apng as its binary file.

Hence, all Data Files are mentioned in at least one Descriptor File, and
all Descriptor Files are listed in the Table of Contents. Any file for
which that is not the case is considered
orphaned.

Descriptor Files

Descriptor files are defined for the EGM format as an
EYAML data file containing any scalar attributes and
info bits about a particular resource. While most of the information
found in these is unique to each Resource
Type, one attribute that remains common
between all of them is `ID`, which names the 0-based integer by which
the system refers to this resource.

Table of Contents

The Table of Contents file was created as a means of allowing users to
re-order resources in the tree. The Table is a plain-text file, named
toc.txt, which appears in each directory in the EGM and simply lists
all resources in the current directory in the order the user prefers
them to appear. Resources are named by their Descriptor
File and are separated simply by a
newline.

Orphaned Files

Resource Types

This section aims to create a specification for each resource. Since the
storage mechanisms of EGM are very modular, not only are these likely to
change over time, but multiple, selectable specifications could be
created for each resource.

Sprites

Sounds

Backgrounds

Paths

Scripts

Objects

Storing object data is slightly more messy than storing the other
resources mentioned so far, namely because they contain potentially very
large stores of code, as well as Action blocks
which often depend on runtime settings. Since blocks of code can contain
literally anything, storing it in most text-based formats is either ugly
(in the case of YAML) or impossible (in the case of INI). Hence, the
Objects section utilizes ENIGMA's own Extensible Enumeration
Format.

The object format defines events as the first super key type.

Events{3}
  Event (0,0): Actions{1}
    Action (101,-1): Fields[2]
      010101010
      3.1415
  Event (0,3): Actions{3}
    Action (107,-1): "Relative" Applies(obj_wall) Fields[2]
      quantity1
      quantity2
    Action (612,-1): "Not" Fields[3]
      quantity1
      quantity2
      0
    Action (104,-1): "Relative" Fields[1]
      quantity1
  Event (0,8): Actions{1}
    Action (603,-1): Code[3 lines]
// Line 1
// Line 2
// Line 3

Rooms

Category:Formats