AGI Specifications: Chapter 10 - Savegame Files

Table of Contents

Savegame Files

Begun by David Symonds
Continued by Lance Ewing

(Last updated: 10 March 2017)

 

10.1 Introduction

AGI saved game files are named as follows:

<gameId>SG.<num>

where <gameId> is the ID of the game, e.g. KQ1, SQ2, etc., and where <num> is a number starting at 1. The format of the saved game file was relatively consistent between versions 2.4XX and 2.9XX apart from one minor addition. The specification below currently focuses on the format used by that version range. The format of AGI v3 saved games has not yet been explored, but it is known that AGI v2.272 differs somewhat in format and almost certainly those versions prior to 2.272 will therefore be different as well.

The saved game file consists of six sections. The first section contains only the description of the saved game. We'll call this the header. The other five sections follow a high level format where the first two bytes give the length of the section and the remainder is the data for that section.

Note that the "Byte" offsets for each section are specified as being from the start of that section and not the start of the file.

Where a numeric value is specified over multiple bytes, it is always little-endian, unless otherwise noted.

10.2 Saved Game Format

Header

Byte	Meaning
0-30	Savegame description. This can be up to 30 printable characters, and is padded out with NUL (\0) bytes to a total of 31 bytes.

General State

Byte	Meaning
0-1	Length of general state section
2-8	Game ID("SQ2", "KQ3", "LLLLL", etc.), NUL padded
9-264	Variables, 1 variable per byte
265-296	Flags, 8 flags per byte, starting with highest bit first
297-300	Clock ticks since game started. 1 clock tick == 50ms
301-302	Horizon
303-304	Key Dir
305-306	Upper left X position for active block
307-308	Upper Left Y position for active block
309-310	Lower Right X position for active block
311-312	Lower Right Y position for active block
313-314	Player control (1) / Program control (0)
315-316	Current picture number
317-318	Blocking flag (1 = true, 0 = false)
319-320	Max drawn. Always set to 15. Maximum number of animated objects that can be drawn at a time.
321-322	Script size. Set by script.size. Max number of script event entries. Default is 50.
323-324	Current number of script event entries.
325-524	Key to controller map (4 bytes each). First 2 bytes keycode, second 2 bytes controller num.
525-1484	24 strings, each 40 bytes long
1485-1486	Text foreground colour
1487-1488	Text background colour
1489-1490	Text Attribute value (a combined foreground/background value)
1491-1492	Accept input = 1, Prevent input = 0
1493-1494	User input row number on the screen (as set by configure.screen command)
1495-1496	Cursor character
1497-1498	Show status line = 1, Don't show status line = 0
1499-1500	Status line row number on the screen (as set by configure.screen command)
1501-1502	Picture top row number on the screen (as set by configure.screen command)
1503-1504	Picture bottom row number on the screen (indirectly set by configure.screen)
(1505-1506)	Stores a pushed position within the script event list. Used by push.script and pop.script.

Notes:

Animated Objects

Byte	Meaning
0-1	Length of animated objects section. Dividing this by 43 gives the number of animated objects.

Following the two bytes above we have a 43-byte entry for each script event item, each of which conform to the following format:

Byte	Meaning
0	Step Time. Number of animation cycles between motion.
1	Counter for number of animation cycles between motion. Counts down from Step Time above.
2	Object number, i.e. index within the list of animated objects (aka. view table entries).
3-4	Current X position
5-6	Current Y position
7	Current view number
8-9	Pointer to current view
10	Current loop number
11	Number of loops in view
12-13	Pointer to current loop
14	Current cel in loop
15	Number of cels in current loop
16-17	Pointer to current cel
18-19	Pointer to previous cel
20-21	Pointer to background save area
22-23	Previous X position
24-25	Previous Y position
26-27	X size (or width) of current cel
28-29	Y size (or height) of current cel
30	Step Size. Distance that object moves.
31	Cycle Time. Number of animation cycles between cel change.
32	Counter for determining when object cycles. Counts down from Cycle Time value above.
33	Direction. 0 = stationary 1 = north 2 = north/east 3 = east 4 = south/east 5 = south 6 = south/west 7 = west 8 = north/west
34	Motion Type. 0 = normal.motion 1 = wander 2 = follow.ego 3 = move.obj
35	Cycle Type. 0 = normal.cycle 1 = end.of.loop 2 = reverse.loop 3 = reverse.cycle
36	Priority.
37-38	Control bits, with bit masks defined as follows: Drawn 0x0001 (is drawn on screen) IgnoreBlocks 0x0002 (ignores blocks) FixedPriority 0x0004 (has a fixed priority) IgnoreHorizon 0x0008 (ignores the horizon) Update 0x0010 (should be updated) Cycle 0x0020 (should cycle the object) Animated 0x0040 (can move) Blocked 0x0080 (is blocked) StayOnWater 0x0100 (must stay entirely on water control colour) IgnoreObjects 0x0200 (won't collide with other objects) Repositioned 0x0400 (is being repositioned in this cycle) StayOnLand 0x0800 (must not be entirely on water control colour) NoAdvance 0x1000 (do not advance object's cel in this loop) FixedLoop 0x2000 (loop is fixed) Stopped 0x4000 (did not move during last animation cycle) The highest bit, i.e. 0x08000, is not used by the interpreter.
39	Motion parameter 1.
40	Motion parameter 2.
41	Motion parameter 3.
42	Motion parameter 4.

It is obvious from looking at the above that this format matches the view table format described in the "View resources" section of the AGI specs. This isn't surprising since all the above really is is a dump of the view table entries for each of the animated objects from the memory of the interpreter.

Inventory Objects

Almost an exact copy of the OBJECT file, but always unencrypted, and with the 3 byte header replaced by the 2 byte length of the section, and with room numbers reflecting the current location of each object (rather than starting location).

Byte	Meaning
0-1	Length of inventory objects section. Dividing this by 3 gives the number of objects.

Following the two bytes above we have a three byte entry for each inventory item all of which conform to the following format:

Byte	Meaning
0-1	Offset of inventory item name i
2	Current room number for inventory item i, or 255 for carried or 0 for limbo.

where i is the entry number starting at 0. All offsets are taken from the start of entry for inventory item 0 (not the start of the section).

Then comes the textual names themselves. This is simply a list of NULL terminated strings. The offsets mentioned in the above section point to the first character in the string and the last character is the one before the 0x00.

Note that the saving of the object names in the saved game file (and the offsets to those names) is completely redundant since the names cannot change during game play. But they're present regardless.

Script Events

Stores a transcript of relevant logic script commands leading to the current state in the current room.

Byte	Meaning
0-1	Length of script events section. Dividing this by 2 gives the number of script events.

Following the two bytes above we have a two byte entry for each script event item, each of which conform to the following format:

Byte	Meaning
0	Script event type. A value from 0 to 8 defined as follows: load.logics 0 load.view 1 load.pic 2 load.sound 3 draw.pic 4 add.to.pic 5 discard.pic 6 discard.view 7 overlay.pic 8
1	The resource number that relates to the above event type. For add.to.pic this is 0.

The add.to.pic event type is a special case. It is stored over 8 bytes, i.e. over 4 script entries. This appears to be a hack of sorts that the original AGI interpreter used for storing this event type. The other eight types have a clear action and resource number that the action applies to. The add.to.pic command doesn't follow this form. Instead it is stored as follows:

Byte	Meaning
0	0x05 (i.e. add.to.pic)
1	0x00 (effectively unused)
2	View number
3	Loop number
4	Cel number
5	X position
6	Y position
7	Top 4 bits are control line colour, bottom 4 bits are priority band colour.

Scan Start Offsets

Every logic currently loaded will have an entry in this table. A logic script can use the set.scan.start command to set an offset at which the interpreter will scan from. If a logic has done that then it is this section that saves that value. It is quite common that a saved game has a 0 offset for all entries since it is only if a logic has used set.scan.start that you would see a non-zero value.

Byte	Meaning
0-1	Length of scan start offsets section. Subtract 8 then divide by 4 gives the number of entries.
2-5	Start of list. Always four zeros, i.e. 00 00 00 00
...	A variable number of 4-byte scan start offset entries, format as described in table below
?-?	End of list. Always FF FF 00 00

Each of the 4-byte scan start offset entries conforms to the following format:

Byte	Meaning
0-1	Logic number that the scan start offset is for.
2-3	Current scan start offset value of the logic.

Notes:

1. Only logics that are currently loaded are in the scan offset list, i.e. they're removed from the list when the room changes.
2. The order logics appear in this list is the order that they were loaded.
3. The new.room command unloads all logics except for logic 0, so logic 0 never leaves this list and is always the first item, i.e. at offsets 6-9.
4. There is a defined maximum of 30 entries in the scan start offset list, but given that only loaded logics can set a scan start offset value, we're unlikely to see anywhere near that many.

Table of Contents

< Previous: Chapter 9 - Sound ResourcesNext: Chapter 11 - Other Game Data >