LGL format

From ENIGMA
Jump to navigation Jump to search

LGL is the LateralGM Library format, intended as a highly compressed alternative to Game Maker's LIB format.

Compression over LIB was achieved 3 ways:

  • Trimming unused bytes (short strings are usually 1-byte prefixed) and unused inclusions (only include the arguments you use, not 8).
  • Masking multiple booleans into 1 byte (also applies to values that don't use all 8 bits).
  • Combining the Images into a single PNG strip. See #Image for more information.

As a result, LGLs are generally 10% of the size of their LIB equivalent. The LIBs included with Game Maker are 860 KB. The LGLs included with LateralGM, which contain the same number of Actions, are 82 KB.

The first downside is that readers have to cope with being able to read 2- and 3-byte integers, bit masks, and an image strip. This slightly increases reading time. It normally takes LGM about 250ms (1/4 second) to read and process all of its standard LGLs. The second downside is limitations - a library can only have at most 127 actions, some strings can must be shorter than 256 characters (names, action list/hint text, argument info) - although these limitations are reasonable, since libraries that exceed these limitations would behave undesirably in GM anyways (imagine scrolling through hundreds of actions, or trying to read a hint text that's wider than the screen).


For notes on how to read this format, and other information, please see Format info. However, the following differences exist in this format:

  • Each line begins with the number of bytes that the information of that line requires, unless the line contains an insertion or a bit description.
  • A >> denotes that a byte is broken up into bits, and the following lines describe those bits, each preceded by a > and a bit count (denoted by a "b" - e.g. "1b" indicates 1 bit)

Lookup Tables

Action Kinds
ID Name
0 Normal
1 Begin Group
2 End Group
3 Else
4 Exit
5 Repeat
6 Variable
7 Code
8 -Placeholder
9 -Separator
10 -Label
Execution Types
ID Name Description
0 Nothing Execution Information remains empty (0)
1 Function Execution Information contains Function Name
2 Code Execution Information contains Code

The Order column in the table below indicates the order that the entries would be expected to appear in a user-friendly dropdown.

Argument Types
Order Name ID
1 Expression 0
2 String 1
3 Both 2
4 Boolean 3
5 Menu 4
6 Color 13
7 Font String 15
8 Sprite 5
9 Sound 6
10 Background 7
11 Path 8
12 Script 9
13 Object 10
14 Room 11
15 Font 12
16 Timeline 14

Documentation

3 (string) "LGL"
2 LGM version needed for the following info (160)
3 Lib ID (if ID < 1000, this file is protected as official)
1 Length of Tab Caption { Tab Caption }
1 Length of Author { Author }
4 Lib Version
8 (double) Last Changed date
4 Length of Info { Info }
4 Length of Initialization Code { Initialization Code }
1 >>
> 1b Advanced
> 7b Number of Actions
{
 2 LGM version needed for the following info (160)
 2 Action Id
 1 Length of Name { Name }
 1 Length of Description { Description }
 1 Length of List Text { List Text }
 1 Length of Hint Text { Hint Text }
 1 >>
 > 1b Hidden
 > 1b Advanced
 > 1b Registered only
 > 1b Question
 > 1b Apply to
 > 1b Relative
 > 2b Execution Type[1] (0-2)
 4 Length of Execution Information[1] { Execution Information }
 1 >>
 > 4b Kind[2] (0-10)
 > 4b Interface Kind (0=Normal, 1=None, 2=Arrows, 5=Code, 6=Text)
 1 Argument Count
 {
  1 Length of Argument Caption { Argument Caption }
  1 Argument Type[3] (0-15)
  1 Length of Default Argument Value { Default Argument Value }
  1 Length of Menu { Menu }
 }
}
Raw PNG Strip of Action Images
  1. 1.0 1.1 Execution Information is an adapted value that depends on Execution Type (above).
  2. See Action Kinds above
  3. See Argument Types above

Image

The Score tilesheet used by 05_score.lgl

In LGL, all of the Action Images for a library are combined together into a single strip/sheet PNG. By doing this, filesize is greatly reduced, because PNG compression compresses a single large image better than a bunch of little images (not to mention, there is only 1 header this way). Transparency is not only supported, but expected.

The image sheet must be composed of 24x24 tiles. Tiles may be arranged horizontally, vertically, or both. Tiles are to be read left-to-right and then top-to-bottom. For an example, see the image included in this section.

The PNG data storing the image sheet is appended raw to the end of the LGL file. There is no length prefix (aside from the PNG-internal size indicators in the PNG header data). Immediately after the last Action and its Arguments, you will encounter the PNG signature (0x89 0x50 0x4E 0x47) and the rest of the PNG data. The LGL format does not specify any additional data after the PNG, and it is generally expected that you should encounter the End of the File (EOF) after the PNG data.