EGM format: Difference between revisions

From ENIGMA
Jump to navigation Jump to search
 
(No difference)

Latest revision as of 20:04, 6 February 2013

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