1 Binary Format of GameMaker Save Files (gmd, gm6, gmk)
2 Copyright (c) 2008 IsmAvatar <cmagicj@nni.com>
5 Redistribution and use of this document, with or without modification,
6 is permitted provided that redistributions retain the above copyright
7 notice, this condition, and the following disclaimer.
10 THIS DOCUMENT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
11 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
12 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
13 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
14 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
15 OUT OF OR IN CONNECTION WITH THIS DOCUMENT OR THE USE OR OTHER DEALINGS IN
18 You may need a hex editor to examine GM files and/or make modifications.
19 You can use the one I used, XVI32. It can be found at
20 http://www.chmaas.handshake.de/delphi/freeware/xvi32/xvi32.htm
24 I have thoroughly reviewed the Licence Agreement of GameMaker, and have a
25 general knowledge of copyrights and such. These activities are legal, as
26 long as I do not tamper with the compiler and as long as I maintain
27 credit to Mark Overmars for the original GameMaker, which I will make
28 sure to revere and worship greatly in this product. A note from Mark
29 Overmars himself regarding this activity:
31 "Sorry for not replying earlier. I was first was on holidays and then
32 trying to catch up. I don;t think this is an important issue. Actually
33 .gm6 files are not really protected. And even though I prefer people not
34 to hack them, I cannot see a reason to be worried about this.
40 From time to time, you'll see some bytes documented as "GM Version needed
41 for the following info". For resources, first GM version tells when the
42 resource type was added, while the second GM version tells when the last
43 update of the resource type was.
45 We will only focus on versions 530, 600, and 702 although these other
46 versions may be mentioned elsewhere.
48 * 702 for GM7.0 (notice, GMK is obfuscated. Please see the GMKrypt Documentation)
49 * 701 for GM7.0 as well.
50 * 620 for GM7.0 in some places. This may be because Mark was planning on calling it 6.2
51 * 600 for GM6.1 and GM6.0 (cross-compatible)
52 * 530 for GM5.3 and GM5.3a (bug-fix version. cross-compatible)
53 * 520 for 510 for GM5.1
54 * 500 for GM5.2 and GM5.0 (forward compatible)
57 and so on. Other numbers may pop up as well, as in-between versions. For
58 example, 542 means that 530 cannot read it, but 600 can. Software usually
59 does this for format changes during development. Also see Angle Brackets
62 Note About Sounds, Images, Data Files, and Game Information
63 All images, with the exception of Data File images and the Game Icon, are stored as zlib compressed bitmaps.
64 All sounds are stored in their original format when possible, and then zlib compressed.
65 Game Information is stored in Rich Text Format (RTF).
66 You should also see Angle Brackets below.
68 Note About Longint / Numbers
70 GM uses primarily 32-bit (4-byte) little-endian signed integers, which I
71 choose to call "longints", for most of its data. Even basic things like
72 True/False and Radio Buttons etc. each tend to be stored in their own
73 4-byte/32-bit set, rather than merging 8 of them to make a single byte or
74 merging 32 of them to make that same 4-byte.
76 I will display any dates as Gregorian ISO standard (yyyy-mm-dd).
78 Dates are stored in 64-bit (8-byte) signed doubles representing the
79 number of days that have passed since 1899-12-30. Fractional parts are
80 used to represent fractions of days (hours, minutes, seconds, etc).
82 Colors are stored in a longint, usually only using the first 3 bytes as R
83 G B respectively, although sometimes they'll make use of the 4th byte, so
84 handle carefully. Usually the 4th byte is 0.
86 Unless otherwise denoted by a preceding (<byte size>-bytes) note, all
87 data is stored in 32-bit integers or 32-bit preceded 8-bit character
88 sequences (as denoted by insertions, explained below).
90 Note About Insertion and Curly Brackets { }
92 Insertion will take 2 normal forms, and a third special form (see Angle
93 Brackets). Both normal forms will almost always have a longint before the
94 insertion to indicate how much information is contained in the insertion.
95 If this number is 0, no additional data will be inserted. The data is
96 then surrounded by curly brackets { }.
98 The first kind of insertion is String Insertion. This is when the data is
99 a series of 8-bit (1-byte) characters. My documentation will show these
100 by having all the information (the length longint, the curly brackets,
101 and the data) on one line.
103 Example of string insertion:
104 Length of Name { Name }
105 which would turn out as something like 07 Sprites ...
108 The second kind of insertion is Structured Insertion (although you
109 needn't remember the name - it's stolen from C's struct). For this, the
110 documentation format will be the length longint, and then the first curly
111 bracket { on a new line, followed by the data on its own lines separate
112 from the curly brackets, and then concluded with an end curly bracket on
113 a new line. See the examples below.
115 Two common forms will arise. One is the true/false Structured Insertion.
116 This determines simply whether or not the insertion will appear.
118 Example of a true/false
124 The other is the Repitition Structured Insertion. This means that the
125 first longint will indicate *how many times* the data within will be
126 inserted. The data itself is not actually repeated - only the structure
129 Example of repetition
134 In this case, supposing there's 8 views, each with increments of ID
135 The result would be: 08 00 01 02 03 04 05 06 07 (replacing each of those numbers with the longint equivelent)
137 Note about Conditional Insertions and Angle Brackets < >
139 Conditional Insertions are when a certain condition (e.g. the value of a
140 prior longint) must be met in order for the data to be inserted. This is
141 set apart from normal insertions because that longint may not be
142 adjacent, or because the longint value may not be an obvious indicator of
143 the repetitions (e.g. 0 may indicate that data is indeed inserted, while
144 1 may indicate that it is not). Angle Brackets are placed around this
145 conditional expression.
147 A very common example of Conditional Insertions is the Version Number, as
148 this weighs heavily on what data appears in which version. Each section
149 has its own version number - there's 1 for Game Information, 1 for each
150 resource, and a separate one for the format of each resource. Thus you
151 should keep an eye on which version number is being used for that section
152 - and also keep an eye on the scope of that version number.
154 Example of Version Numbers:
155 GM version needed for the following info (542/600)
156 <530 only> Load only on Use (0)
157 <600 only> Preload (1)
159 If different versions get grouped together like that, I will try to group
160 the older versions first and the newer versions later.
162 Of course, Conditional Insertions aren't solely dependant on a version
163 number. Here's an example of Special Case insertion (one which does not
164 denote how often the data is repeated)
167 <if not -1> Size of Image data { Image Data }
169 This frequently occurs in Sounds and Images. At this time we do not
170 understand why this odd conditional is there - why use 10 instead of 1,
173 Note about Default Values in Parenthesis
175 I've also started including default values and value ranges to my format
176 documentations, for your convenience. When the default value is not
177 obvious by the format, I will put an asterisk (*) next to it.
179 Here are a few examples of the formats used;
180 (<Lower>-<Upper>,<Default>) e.g. (0-100,10)
181 (Min <Value>,<Default>) e.g. (Min 0, 100)
183 ([Range,]<Val1>=Name1,<Val2>=Name2[,<Val3>=Name3[,...]]) e.g. (0-2,0*=Yes,1=No,2=Cancel)
185 ----------------------------
186 Now to explain the bytes.
188 Reserved, tells GM that it's a GM file (1234321)
189 GM Version needed for Game Settings (530/600/701)
190 <530 only> Reserved (0)
191 Game ID. (0-100,000,000, Random*)
192 (16 bytes) These seem to go hand-in-hand with the Game ID, for when they
193 change. Its purpose is unclear. You may just plug in 0's with no apparent
195 GM version needed for the following info (530/542/600/702)
196 Start in full-screen mode (0)
197 <600+> Interpolate colors between pixels (0)
198 Don't draw a border in windowed mode (0)
199 Display the cursor (1)
200 <530 only> Scale percentage in windowed mode (1-999, 100*)
201 <530 only> Scale percentage in fullscreen mode (0=max) (0-999, 100*)
202 <530 only> Only scale when there is hardware support (1)
203 <542+> Scaling (-1 to 999, -1* = Keep Aspect Ratio, 0 = Full Scale, 1-999 = Fixed Scale)
204 <542+> Allow the player to resize the game window (0)
205 <542+> Let the game window always stay on top (0)
206 <542+> Color outside the room region (0 or 0x00000000)
207 Set the resolution of the screen (0)
208 <530 only> Color Depth (0* = 16-bit, 1 = 32-bit)
209 <530 only> Use exclusive graphics mode (0)
210 <530 only> Resolution (0-6, 0=640x480, 1*=800x600, ..., 5=320x240, 6=No Change)
211 <530 only> Frequency (0-4, 4)
212 <530 only> Wait for a vertical blank before drawing (0)
213 <530 only> Display the caption in full-screen mode (1)
214 <542+> Color Depth (0* = No Change, 1 = 16-bit, 2 = 32-bit)
215 <542+> Resolution (0-6, 0* = No change, ...)
216 <542+> Frequency (0-5, 0* = No change, 1 = 60, ...)
217 Don't show the buttons in the window caption (0)
218 <542+> Use synchronization to avoid tearing (0)
219 Let <F4> switch between screen modes (1)
220 Let <F1> show the game information (1)
221 Let <Esc> end the game (1)
222 Let <F5> save the game and <F6> load a game (1)
223 <702+> Let <F9> take a screenshot of the game (1)
224 <702+> Treat the close button as <Esc> key (1)
225 Game Process Priority (0* = Normal, 1 = High, 2 = Highest)
226 <530 only> Reserved (1)
227 <530 only> Reserved (1)
228 Freeze the game when the form looses focus (0)
229 Loading Progress Bar (LPB) (0 = No LPB, 1* = Default LPB, 2 = Own LPB)
232 <if not -1> Size of Back Image data { Back Image Data }
234 <if not -1> Size of Front Image data { Front Image Data }
236 Show your own image while loading (0)
239 <if not -1> Size of Front Image data { Front Image Data }
241 Make image partially transparent (0)
242 Make translucent with alpha value (0-255, 255)
243 Scale progress bar image (1)
244 Size of Icon data (2238) { Icon Image Data }
245 Display error messages (1)
246 Write error messages to file game_errors.log (0)
247 Abort on all error messages (0)
248 Treat uninitialized variables as value 0 (evil!) (0)
249 Length of Author (0) { Author }
250 <600 and below> Version (100)
251 <702 only> Length of Version (3) { Version ("100") }
252 (double) Last Changed date and time (generated)
253 Length of Information (0) { Information }
254 How many Constants there are (0)
256 Length of Name { Name }
257 Length of Value { Value }
261 <702 only> Release (0)
263 <702 only> Length of Company (0) { Company }
264 <702 only> Length of Product (0) { Product }
265 <702 only> Length of Copyright (0) { Copyright }
266 <702 only> Length of Description (0) { Description }
267 <542 and 600> How many Include files there are (0)
269 Length of Filename { Filename }
271 <542 and 600> Folder to save Include files to (0* = main, 1 = temp)
272 <542 and 600> Overwrite existing Include files (0)
273 <542 and 600> Remove Include files at game end (0)
275 GM version needed for the following info (400)
276 How many sound ID's there are (0)
278 Whether sound of this ID exists or not
280 Length of Name { Name }
281 The GM version needed for the following info (440/600)
282 <440 only> Kind (-1*=None, 0="Wave", 1="Midi", 2="Mp3", 10="Unknown")
283 <600 only> Kind (0=Normal, 1=Background, 2=3D, 3=Multimedia)
284 Length of Filetype { Filetype (like ".wav") }
285 <600 only> Length of Filename { Filename (no directory) }
286 <600 only> Music exists
288 Size of Music Data { Music Data }
290 <440 only and Kind is not -1> Size of Music Data { Music Data }
291 <440 only> Allow for sound effects (0)
292 <440 only> Buffers (1)
293 <440 only> Load only on use (0)
294 <600 only> Effects (Chorus=1, Echo=2, Flanger=4, Gargle=8, Reverb=16)
295 Notice, Effects is actually merged into 1 longint
296 To get the value, simply add active Effect numbers together
297 <600 only> (double - 8 bytes) Volume (1)
298 <600 only> (double - 8 bytes) Pan (0*=center)
299 <600 only> Preload (1)
303 GM version needed for the following info (400)
304 How many sprite ID's there are (0)
306 Whether sprite of this ID exists or not
308 Length of Name { Name }
309 The GM version needed for the following info (400/542)
312 Left Bounding Box (can be negative)
313 Right Bounding Box (can be negative)
314 Bottom Bounding Box (can be negative)
315 Top Bounding Box (can be negative)
317 <542 only> Smooth Edges (0)
318 <542 only> Preload Texture (1)
319 Bounding Box (0*=Automatic, 1=Full image, 2=Manual)
320 Precise collision checking (1)
321 <400 only> Use video memory (1)
322 <400 only> Load only on use (0)
325 How many subimages there are
328 <if not -1> Size of Image data { Image Data }
333 GM version needed for the following info (400)
334 How many background ID's there are (0)
336 Whether background of this ID exists or not
338 Length of Name { Name }
339 The GM version needed for the following info (400/543)
343 <400 only> Use video memory (1)
344 <400 only> Load only on use (1)
345 <543 only> Smooth Edges (0)
346 <543 only> Preload Texture (0)
347 <543 only> Use as tile set (0)
348 <543 only> tile width (16)
349 <543 only> tile height (16)
350 <543 only> horizontal offset (0)
351 <543 only> vertical offset (0)
352 <543 only> horizontal sep (0)
353 <543 only> vertical sep (0)
357 <if not -1> Size of Image data { Image Data }
362 GM version needed for the following info (420)
363 How many path ID's there are (0)
365 Whether path of this ID exists or not
367 Length of Name { Name }
368 The GM version needed for the following info (530)
369 Connection Kind (0* = Straight lines, 1 = Smooth curve)
372 Room Index to show as Background (-1* = none)
375 How many Points there are (0)
384 GM version needed for the following info (400)
385 How many script ID's there are (0)
387 Whether script of this ID exists or not
389 Length of Name { Name }
390 The GM version needed for the following info (400)
391 Length of Script { Script }
395 GM version needed for the following info (440/540)
396 <440 only> How many data file ID's there are
398 Whether data file of this ID exists or not
400 Length of Name { Name }
401 The GM version needed for the following info (440)
402 Length of File Name (0) { File Name }
405 Size of File Data { File Data }
407 Export (0=Don't, 1=Temp Folder, 2*=Working Folder, 3=As Font)
408 Overwrite the File (0)
410 Remove at Game End (1)
413 <540 only> How many font ID's there are
415 Whether font of this ID exists or not
417 Length of Name { Name }
418 The GM version needed for the following info (540)
419 Length of Font Name { Font Name }
423 Character Range Begin (32)
424 Character Range End (127)
428 GM version needed for the following info (500)
429 How many timeline ID's there are (0)
431 Whether timeline of this ID exists or not
433 Length of Name { Name }
434 The GM version needed for the following info (500)
435 How many Moments there are (0)
438 Here is where Action information is inserted. This information is exactly
439 the same as it appears in objects. As such, to understand how these bytes
440 work, rather than documenting it twice, I shall refer you to see Actions
441 below, between the **stars**
446 GM version needed for the following info (400)
447 How many object ID's there are (0)
449 Whether object of this ID exists or not
451 Length of Name { Name }
452 The GM version needed for the following info (430)
453 Sprite Index (-1* = none)
458 Parent object index (-100* = none)
459 Mask sprite index (-1* = none)
461 Now we have an interesting thing. We have eleven (11) -1's thrown in for
462 each of the event types. They appear after each event's data (or simply
463 appear where they are if the event type has no data), but the events may
464 have -1's in them too, so you can't just count down 11 -1's and hope to
465 be at the end of the object. No event begins with -1, so if you have a -1
466 where an event should be, you know that the event has no data. If there
467 is data, it is documented here. If there are multiple kinds (event kind =
468 'numb' in the GM manual) of the same event, each kind will be added in
469 without a -1 appended on the end until the last. The first kind to appear
470 will actually be the highest kind number, and then it will count down.
471 Other than that, Events appear in standard order. The stars ** you will
472 see below relate to Time Lines. See Time Lines for more info.
474 Event Numb (see GM Manual)
475 **GM version needed for the following info (400)
476 How many actions this event has
478 The GM version needed for the following info (440)
481 Action Kind (Normal, Begin Group, Else, etc. See Lib Builder)
482 Action may be Relative
484 Action Applies to something
485 Action Type (0=Nothing, 1=Function, 2=Code)
486 Length of Function Name { Function Name }
487 Length of Code { Code }
489 How many arguments there are (always 8)
491 Argument Kind (See Lib Builder)
493 Applies to Object Index (-1 for Self, -2 for Other)
495 How many arguments there are (always 8)
497 Argument Length { Argument Value }
502 (Don't forget the -1 after each Primary event)
506 GM version needed for the following info (420)
507 How many room ID's there are (0)
509 Whether room of this ID exists or not
511 Length of Name { Name }
512 The GM version needed for the following info (520/541)
513 Length of Room Caption (0) { Room Caption }
518 Turn the grid into an isometric grid (0)
521 Background Color (12632256 or 0xC0C0C000)
522 Draw background color (1)
523 Length of Creation Code { Creation Code }
524 How many Backgrounds there are (always 8)
526 Visible when room starts (0)
528 Background Image index (-1* = none)
537 Enable the use of Views (0)
538 How many Vies there are (always 8)
540 Visible when room starts (0)
547 <541 only> View X (min 0, 0)
548 <541 only> View Y (min 0, 0)
549 <541 only> View W (min 1, 640)
550 <541 only> View H (min 1, 480)
551 <541 only> Port X (min 0, 0)
552 <541 only> Port Y (min 0, 0)
553 <541 only> Port W (min 1, )
554 <541 only> Port H (min 1)
559 Object following (-1* = none)
561 How many Instances are in the room (0)
566 ID (starts with 100001)
567 Length of Creation Code { Creation Code }
570 How many Tiles are in the room (0)
579 Layer/Depth (1000000)
580 ID (starts with 10000001dec)
583 Remember the Room Editor Info (REI if 0. May be 0 if all settings are defaults)
584 Room Editor Width (646, 0 if REI)
585 Room Editor Height (488, 0 if REI)
586 Toggle the showing of the grid (1, 0 if REI)
587 Show Objects (1, 0 if REI)
588 Show Tiles (1, 0 if REI)
589 Show Backgrounds (1, 0 if REI)
590 Show Foregrounds (1, 0 if REI)
591 Show Views (0, 0 if REI)
592 Delete underlying objects (1, 0 if REI)
593 Delete underlying tiles (1, 0 if REI)
594 <520 only> Tile Width (16)
595 <520 only> Tile Height (16)
596 <520 only> Tile Hsep (1)
597 <520 only> Tile Vsep (1)
598 <520 only> Tile Horizontal Offset (0)
599 <520 only> Tile Vertical Offset (0)
600 Tab (0-4, 0, 0 if REI)
601 0* = objects, 1 settings, 2 tiles, 3 backgrounds, 4 views
602 X Position of the horizontal scrollbar of the Room Editor (0, 0 if REI)
603 Y Position of the vertical scrollbar of the Room Editor (0, 0 if REI)
606 ID of last instance placed (100000)
607 ID of last tile placed (1000000)
609 <701 only> GM version needed for Includes (620)
610 <701 only> How many Includes there are (0)
612 GM version needed for the following info (620)
613 Length of Filename (0) { Filename }
614 Length of Filepath (0) { Filepath }
615 Whether an Original File is chosen or not
616 Original File Size (0)
617 Store in editable gmk file (0)
619 Length of File Data (0) { File Data }
621 Export (0=Don't, 1=Temp Dir, 2=Working Dir*, 3=Following Folder)
622 Length of Folder To Export To (0) { Folder To Export To }
623 Overwrite the file if it exists (0)
624 Free memory after export (1)
625 Remove at game end (1)
628 <701 only> GM version needed for Packages (700)
629 <701 only> How many Packages there are (0)
631 Length of Package Name { Package Name }
634 GM version needed for the following info (430/600/620)
635 Background Color of Game Information (-16777192 or 0x180000FF)
636 Mimic the main game window/main form (0)
637 <600+> Length of Form Caption (16) { Form Caption ("Game Information") }
638 <600+> Position Left (-1)
639 <600+> Position Top (-1)
640 <600+> Position Width (600)
641 <600+> Position Height (400)
642 <600+> Show the window border and caption (1)
643 <600+> Allow the player to resize the window (1)
644 <600+> Stay always on top (0)
645 <600+> Stop the game while showing help (1)
646 Length of Game Information RTF (147) { Game Information in Rich Text Format }
648 GM version needed for the following info (500)
649 How many library dependancies there are (these are stored in the order of
650 the lib's filenames, in alphabetical order. Likewise, they are executed
653 Length of Library Creation Code { Library Creation Code }
656 GM version needed for the following info (500/540/700)
657 How many executable rooms there are (this stores the room indexes in
658 execution order, so you know which room to summon next via
659 room_goto_next() etc.)
661 Room index (in execution order, which is usally the same as the Tree Order)
665 (Following that is the Resource Tree, which concludes the file)
667 Creating the Resource Tree:
669 <700 only> There are 12 Root Tree Resources - 9 primary, 3 secondary
670 <500 and 540> There are 11 Root Tree Resources - 9 primary, 2 secondary
673 Status, Grouping, Index, Length, { Name }, Contents
674 You repeat that for all things on the resource tree, as they appear,
675 going down, all branches expanded.
680 3) Secondary Resource
682 Grouping (in the order they appear in the file):
688 9) <500> Data Files / <540> Fonts
693 B) <500> Game Options* / <540> Global Game Settings*
694 D) <700> Extension Packages*
695 *Considered Secondary Resources that don't belong in a primary resource group.
699 All Secondary Resources are given an Index, or a reference number, which
700 reflects the index of the resource far above, where you set their
701 properties and options. Primary Resources, Groups, and Game Information
702 and Game Options / Global Game Settings all use 0 for their Index.
703 Occasionally you may find that they will actually use a number other than
704 zero. It is unclear why they would do this, but just keep it in mind.
706 If the index does not reflect their resource number above, you may either
707 get invisible resources, or <undefined> resources. Also, make sure that
708 no two secondary resources under a single Grouping have the same Index.
709 This may result in Duplicate Complex, in which both are dependant on each
710 other and anything you do to one is done to the other.
712 Name Length { Name }:
713 All have a Name Length. After that, it will count out that many bytes for the name itself.
717 All Primary Resources and Groups have Contents count, which is how many
718 groups/secondary resources it has within itself, non-recursive. Secondary
719 Resources always have a content count of 0, since they may never contain
722 Non-recursive means that if a folder has several resources, only that
723 folder is counted. Once it reaches the folder, it will tell how many
724 resources it contains.
726 Let's say you have 5 sprites, but all 5 of them are inside a Group, and
727 that group falls under Sprites. The Sprites Primary Resource has 1
728 content, which is the Group. The Group has 5 contents - the 5 sprites.
731 In an empty file, it would look something like this:
732 1 2 0 7 Sprites 0 1 3 0 6 Sounds 0 etc.
733 In the pacman example that comes with most distributions of GM, it would look like this:
734 1 2 0 7 Sprites 6 2 2 0 7 pacmans 5 3 2 0 8 pac_left 0 3 2 1 9 pac_right 0 3 2 2 6 pac_up 0 3 2 3 8 pac_down 0 3 2 4 9 pac_stand 0 2 2 0 8 monsters 2 etc.
735 This will cause the tree to look like this:
745 Since Primary Resources are included in the save file, you can change
746 their names (and their lengths, as long as you update the longint before
747 their name to reflect the new length) and it will actually display in the
748 resource tree to the left.
751 Additional data may be stored at the end of the file and GM will ignore/discard it.