From tapilot@home.se Tue Jan  1 09:40:56 2002
Date: Tue, 01 Jan 2002 03:14:29 +0100
From: Thomas kesson <tapilot@home.se>
To: sarien-devel@lists.sourceforge.net
Subject: [sarien-devel] PalmOS: Database format, rev 0.2


PalmOS AGI Game Database Specification
Revision 0.2, 2001-12-31

Note: PalmOS is Big Endian which is why all data that is adapted during
conversion should be stored that way.

Each game is contained in one record database with the following format.
PDB header:
Name: Defined at conversion, max 31 characters, has the .pdb extension when
not on a Palm.
CreatorID: 'FAGI'
Type: 'agi4'

All database attribute bits should be cleared with the following exceptions:
The backup bit can be set depending on user preference. The backup bit
causes the database to be backed up during the next Hotsync.
OKToInstallNewer can be set in order to allow installation over a currently
open database. In this case it's safer to set this bit.
LaunchableData allows a db to be launched by sending it to it's
application. Don't ask me where it's sent from but it might be useful to
set depending on how we solve the game selection problem.

The dates can be set to zero except creationDate and modificationDate which
must be > 0 for the database to install.


Record 0, Header record
UINT16  format;  /* Type of the database. Currently 0 */
UINT16  revision; /* Revision number of the database format, currently 0 */
char            id[8]; /* Game ID in order to easily clean up (savegames) 
when deleting a game. */
UINT16  version; /* Interpreter version used by the game */
UINT16  emulation; /* Interpreter version to emulate */
UINT32  options; /* For Amiga/AGDS, etc */
struct sndInfo {
          #define sndTypeAGI 1
          #define sndTypeSMF0 2
          #define sndTypeSMF1 3
          UINT8 sndType;
          UINT8 sndChannels; /* Valid range: 0..4 */
}

Note: The header can be extended later as long as format and revision are
not moved.


Record 1, logdir
This is the equivalent of the logdir file.

Contains a finite number of two byte entries, no more than 256. Each entry
is a UInt16 giving the record index of the resource. If the two bytes
contains 0xFFFF, then the resource does not exist.


Record 2, picdir
This is the equivalent of the picdir file.

Same format as above.


Record 3, viewdir
This is the equivalent of the viewdir file.

Same format as above.


Record 4, snddir
This is the equivalent of the snddir file.

Same format as above.


Record 5, Objects
This is the equivalent of the object file. It is stored as an array of
starting room numbers followed by a packed block of strings containing the
object names.

The format of the object list is:
Byte     Meaning
-------  --------------------------------------------------------------------
0-1      Number of objects in the record, n (Hi then Lo)
2        Starting room number for first object
...
n+1      Starting room number for last object
n+2     All the object names after each other in a packed block of
NULL-terminated strings.

This allows the creation of pointers to the packed block of strings using:
MemHandle SysFormPointerArrayToStrings (Char *c, Int16 stringCount)
The pointers are then copied together with the room numbers into an array
of struct agi_object. This means that the room numbers are stored twice in
memory (once in storage RAM and once in dynamic RAM) but the strings are
only stored once.


Record 6, Words
This is the words.tok file in its original form.

With the "Sierra style" word find algorithm this data can stay completely
in storage RAM.

Resources
The following records contain one resource each. They are stored without
the AGI resource header since PalmOS knows the size of the record. All
resources (presently excluding SOUND) stay in storage RAM. Only small
portions are copied into dynamic memory, namely those pieces of information
that go into the various structs.

The total number of records in the database is the total number of
resources + 7.


Record 7 .. number_of_log_res+7
Each record contains one LOGIC resource in uncompressed and decrypted form.


Record last_log_record+1 .. number_of_pic_res+last_log_record+1
Each record contains one PICTURE resource in uncompressed form, i.e. in AGI
v2 format. There is no header.


Record last_pic_record+1 .. number_of_view_res+last_pic_record+1
Each record contains one VIEW resource in uncompressed form.


Record last_view_record+1 .. number_of_snd_res+last_view_record+1
Each record contains one SOUND resource in uncompressed form.

These should probably be in Midi format eventually but we have a long way
before sound is really an issue. I suggest we keep them in AGI format for now.


References:
[1] Palm File Format Specification (2001-05-01),
http://www.palmos.com/dev/tech/docs/


_______________________________________________
sarien-devel mailing list
sarien-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/sarien-devel
