Difference between revisions of "DBPF"

From SC4D Encyclopaedia
Jump to navigation Jump to search
sc4e>Whatevermind
(General cleanup)
sc4e>Whatevermind
(Incorporated the /format page, general cleanup.)
Line 1: Line 1:
{{transcluded|1=[http://www.sims2wiki.info/wiki.php?title=DatabasePackedFile Sims2Wiki page]}}
+
'''Database Packed File (DBPF)''' is a proprietary archive format used in many Maxis developed games, including The Sims 2, [[SimCity 4]] and Spore. DBPF files are similar to Zip files, as they hold other files inside them which are usually compressed. All plugins for SimCity 4 (excluding the [[Plugin:SC4 Extra Cheats.dll|SC4 Extra Cheats.dll]]) are DBPF files, the file name's extension is irrelevant.  DBPF files are sometimes referred to as ''packages'' following the convention used in The Sims 2, where the files sometimes have the .package file extension.
 
 
'''Database Packed File (DBPF)''' is a proprietary archive format used in many Maxis developed games, including The Sims 2, [[SimCity 4]] and Spore. DBPF files are similar to Zip files, as they hold other files inside them which are usually compressed. All plugins for SimCity 4 (excluding the [[Plugin:SC4 Extra Cheats.dll|SC4 Extra Cheats.dll]]) are DBPF files, the file name's extension is irrelevant.
 
  
 
DBPF files can be identified by opening the file in notepad, or preferably a hex editor, as the first 4 characters/bytes will be the letters DBPF. If a file in the plugins folder does not start with these 4 letters the game will not load them, however the [[Reader]] will. This means that if you want to disable a plugin you can open the DBPF file in a hex editor and change the first byte to something other than 44 (in Hexadecimal) (D) and the game will not load the plugin, but you will still be able to edit it in the reader (saving the disabled plugin with the reader will not re enable it, to re enable you must change the first byte back to 44 (hexadecimal)).
 
DBPF files can be identified by opening the file in notepad, or preferably a hex editor, as the first 4 characters/bytes will be the letters DBPF. If a file in the plugins folder does not start with these 4 letters the game will not load them, however the [[Reader]] will. This means that if you want to disable a plugin you can open the DBPF file in a hex editor and change the first byte to something other than 44 (in Hexadecimal) (D) and the game will not load the plugin, but you will still be able to edit it in the reader (saving the disabled plugin with the reader will not re enable it, to re enable you must change the first byte back to 44 (hexadecimal)).
Line 10: Line 8:
  
 
==Format==
 
==Format==
[[DBPF/format]]
 
  
==Compression==
+
===Overview===
[[DBPF/compression]] and [[DBPF Compression]]
+
This is the general structure of Database Packed File packages:
 +
 
 +
Header (96 bytes)
 +
File 1
 +
File 2
 +
...
 +
File n
 +
Index Entry 1 (20 bytes)
 +
Index Entry 2
 +
...
 +
Index Entry n
 +
 
 +
Header first, individual files following with no file names and a small file header area at the beginning of each, followed by an index of all the files in the archive. Note that files may appear after the index table in files that are updated.
 +
 
 +
===Header===
 +
{| width="100%" border="1"
 +
! width="20%" | Name
 +
! width="5%" | Version
 +
! width="10%" | Type/Size
 +
! width="65%" | Info
 +
 
 +
|-
 +
| Magic
 +
|
 +
| char[4]
 +
| DBPF
 +
 
 +
|-
 +
| Major Version
 +
|
 +
| u32
 +
| rowspan="2" |
 +
* 1.0 seen in Sim City 4, The Sims 2
 +
* 1.1 seen in The Sims 2
 +
* 2.0 seen in SPORE
 +
 
 +
|-
 +
| Minor Version
 +
|
 +
| u32
 +
 
 +
|-
 +
| unknown
 +
| 2.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| unknown
 +
| 2.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| unknown
 +
| 2.0
 +
| u32
 +
| Should always be zero in DBPF 2.0.
 +
 
 +
|-
 +
| Date Created
 +
| 1.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| Date Modified
 +
| 1.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| Index major version
 +
| < 2.0
 +
| u32
 +
| Always 7 in The Sims 2, Sim City 4. If this is used in 2.0, then it is 0 for SPORE.
 +
 
 +
|-
 +
| Index entry count
 +
|
 +
| u32
 +
| Number of entries in the Index table.
 +
 
 +
|-
 +
| Offset of first Index entry
 +
| < 2.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| Index size
 +
|
 +
| u32
 +
| Size of the Index table in bytes.
 +
 
 +
|-
 +
| Hole entry count
 +
| < 2.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| Hole offset
 +
| < 2.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| Hole size
 +
| < 2.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| Index minor version
 +
| < 2.0?
 +
| u32
 +
| Version 1.1+ in The Sims 2 only. In DBPF 2.0, it has a value of 3, unknown if used.
 +
 
 +
|-
 +
| Index offset
 +
| 2.0
 +
| u32
 +
| Offset to Index table in DBPF 2.0.
 +
 
 +
|-
 +
| unknown
 +
| 2.0
 +
| u32
 +
|
 +
 
 +
|-
 +
| reserved
 +
|
 +
| char[24]
 +
|
 +
 
 +
|}
 +
 
 +
 
 +
===Index Table===
 +
There are two known formats of indexes in the game. The format version is found in the file header.
 +
 
 +
A third format has been discovered, and is used in The Sims 2, but the structure is currently unknown. The Index Minor Version is an actual zero, so this would be called "Index Table 7.-1" by the logic used here. This format has been seen in files that ship with that game, and is believed to have been seen in files generated by that game, but has not yet been seen in user-created files (for obvious reasons). These files were discovered by the simple expedient of having a file-scanning tool choke on them during a scan of the entire game.
 +
 
 +
In [[Reader]], the '''Index Table''' is read as the file directory ([[DIR]]), and these names are generally interchangeable.
 +
 
 +
====DBPF 1.x, Index Table 7.0====
 +
(20 bytes, some DBPF 1.1 entries use this format) A typical entry in this table looks like:
 +
 
 +
'''DWORD'''
 +
  Type ID (see [[:Category:File Formats/SC4]])
 +
'''DWORD'''
 +
  Group ID
 +
'''DWORD'''
 +
  Instance ID
 +
'''DWORD'''
 +
  Location of the file in the archive
 +
'''DWORD'''
 +
  Size of the file
 +
 
 +
====DBPF 1.x, Index Table 7.1====
 +
(24 bytes) A typical entry in this table looks like:
 +
 
 +
'''DWORD'''
 +
  Type ID (see [[:Category:File Formats/SC4]])
 +
'''DWORD'''
 +
  Group ID
 +
'''DWORD'''
 +
  Instance ID
 +
'''DWORD'''
 +
  Second Instance ID
 +
'''DWORD'''
 +
  Location of the file in the archive
 +
'''DWORD'''
 +
  Size of the file
 +
 
 +
===Hole Table===
 +
A Hole Table contains the location and size of all holes in a DBPF file. Holes are created when the game deletes something from a DBPF. The holes themselves are simply junk data of the appropriate length to fill the hole.
 +
 
 +
====DBPF 1.x====
 +
(8 bytes) A typical entry in this table looks like:
 +
 
 +
'''DWORD'''
 +
  Hole Location
 +
'''DWORD'''
 +
  Hole size
 +
 
 +
==Files Within DBPF Files==
 +
The files included in a DBPF file make up the bulk of the DBPF package.  Each file is either uncompressed or compressed.  To check if a file is compressed you first need to read the [[DIR]] file, if it exists.  If no DIR entry exists, then no files within the package are compressed.
 +
 
 +
===Compression===
 +
When reading a DBPF file, the first thing you should do is check to see if any chunks inside are compressed.  This is done via the [[DIR]] (E86B1EEF) resource. For example code and a description of the mechanics, see [[DBPF Compression]] and [[DBPF/compression]].
 +
 
 +
===Header===
 +
The file header only exists if the file is compressed, and looks like this:
 +
 
 +
'''DWORD'''
 +
  Compressed Size of file
 +
'''WORD'''
 +
  Compression ID (0x10FB) QFS Compression. (See [[DBPF Compression]] for compression information)
 +
'''3 bytes'''
 +
  Uncompressed size of the file
 +
 
 +
===Body===
 +
Raw data of the files.  See [[List of File Formats]] for a list of the file types that may exist within a DBPF file.
 +
 
 +
==Pseudocode==
 +
To read files inside a DBPF file, you need to perform the following steps, in order:
 +
 
 +
* Read the DBPF header.
 +
* Read the Index Tables.
 +
* Check for a DIR record.
 +
* Check for the file you want to extract.
 +
* Is this file compressed? If so, decompress it.
 +
* Read the file data and process accordingly.
 +
 
 +
For an example PHP class for reading DBPF files, see [[DBPF/Source Code]]
 +
 
 +
==Visual Format Guide==
 +
These visual guides to the DBPF file format were created by DarkMatter:
 +
 
 +
{|
 +
| [[Image:DBPF_File_Format_v1.1.png|thumb|left|200x152px|alt=DBPF v1.x Visual Guide|DBPF v1.x]]
 +
| [[Image:DBPF_File_Format_v2.0.png|thumb|left|200x152px|alt=DBPF v2.0 Visual Guide|DBPF v2.0]]
 +
|}
  
 +
Some information was taken from old DatGen source code, such as the Created/Modified timestamps and possible Flags DWORD. That information may not be accurate, per DarkMatter's own description. Reason given is that it was some time ago that he "last chatted with Maxoids about the DBPF format."
  
  
 
[[Category:File Formats/SC4]]
 
[[Category:File Formats/SC4]]
 
[[Category:MTS2]]
 
[[Category:MTS2]]

Revision as of 15:38, 25 March 2012

Database Packed File (DBPF) is a proprietary archive format used in many Maxis developed games, including The Sims 2, SimCity 4 and Spore. DBPF files are similar to Zip files, as they hold other files inside them which are usually compressed. All plugins for SimCity 4 (excluding the SC4 Extra Cheats.dll) are DBPF files, the file name's extension is irrelevant. DBPF files are sometimes referred to as packages following the convention used in The Sims 2, where the files sometimes have the .package file extension.

DBPF files can be identified by opening the file in notepad, or preferably a hex editor, as the first 4 characters/bytes will be the letters DBPF. If a file in the plugins folder does not start with these 4 letters the game will not load them, however the Reader will. This means that if you want to disable a plugin you can open the DBPF file in a hex editor and change the first byte to something other than 44 (in Hexadecimal) (D) and the game will not load the plugin, but you will still be able to edit it in the reader (saving the disabled plugin with the reader will not re enable it, to re enable you must change the first byte back to 44 (hexadecimal)).

Entries may be compressed with RefPack compression depending on their entry data.

For an examination of the Spore DBPF format, see Spore DBPF.

Format

Overview

This is the general structure of Database Packed File packages:

Header (96 bytes)
File 1
File 2
...
File n
Index Entry 1 (20 bytes)
Index Entry 2
...
Index Entry n 

Header first, individual files following with no file names and a small file header area at the beginning of each, followed by an index of all the files in the archive. Note that files may appear after the index table in files that are updated.

Header

Name Version Type/Size Info
Magic char[4] DBPF
Major Version u32
  • 1.0 seen in Sim City 4, The Sims 2
  • 1.1 seen in The Sims 2
  • 2.0 seen in SPORE
Minor Version u32
unknown 2.0 u32
unknown 2.0 u32
unknown 2.0 u32 Should always be zero in DBPF 2.0.
Date Created 1.0 u32
Date Modified 1.0 u32
Index major version < 2.0 u32 Always 7 in The Sims 2, Sim City 4. If this is used in 2.0, then it is 0 for SPORE.
Index entry count u32 Number of entries in the Index table.
Offset of first Index entry < 2.0 u32
Index size u32 Size of the Index table in bytes.
Hole entry count < 2.0 u32
Hole offset < 2.0 u32
Hole size < 2.0 u32
Index minor version < 2.0? u32 Version 1.1+ in The Sims 2 only. In DBPF 2.0, it has a value of 3, unknown if used.
Index offset 2.0 u32 Offset to Index table in DBPF 2.0.
unknown 2.0 u32
reserved char[24]


Index Table

There are two known formats of indexes in the game. The format version is found in the file header.

A third format has been discovered, and is used in The Sims 2, but the structure is currently unknown. The Index Minor Version is an actual zero, so this would be called "Index Table 7.-1" by the logic used here. This format has been seen in files that ship with that game, and is believed to have been seen in files generated by that game, but has not yet been seen in user-created files (for obvious reasons). These files were discovered by the simple expedient of having a file-scanning tool choke on them during a scan of the entire game.

In Reader, the Index Table is read as the file directory (DIR), and these names are generally interchangeable.

DBPF 1.x, Index Table 7.0

(20 bytes, some DBPF 1.1 entries use this format) A typical entry in this table looks like:

DWORD
 Type ID (see Category:File Formats/SC4)
DWORD
 Group ID
DWORD
 Instance ID
DWORD
 Location of the file in the archive 
DWORD
 Size of the file 

DBPF 1.x, Index Table 7.1

(24 bytes) A typical entry in this table looks like:

DWORD
 Type ID (see Category:File Formats/SC4)
DWORD
 Group ID
DWORD
 Instance ID
DWORD
 Second Instance ID
DWORD
 Location of the file in the archive 
DWORD
 Size of the file

Hole Table

A Hole Table contains the location and size of all holes in a DBPF file. Holes are created when the game deletes something from a DBPF. The holes themselves are simply junk data of the appropriate length to fill the hole.

DBPF 1.x

(8 bytes) A typical entry in this table looks like:

DWORD
 Hole Location
DWORD
 Hole size

Files Within DBPF Files

The files included in a DBPF file make up the bulk of the DBPF package. Each file is either uncompressed or compressed. To check if a file is compressed you first need to read the DIR file, if it exists. If no DIR entry exists, then no files within the package are compressed.

Compression

When reading a DBPF file, the first thing you should do is check to see if any chunks inside are compressed. This is done via the DIR (E86B1EEF) resource. For example code and a description of the mechanics, see DBPF Compression and DBPF/compression.

Header

The file header only exists if the file is compressed, and looks like this:

DWORD
 Compressed Size of file
WORD
 Compression ID (0x10FB) QFS Compression. (See DBPF Compression for compression information)
3 bytes
 Uncompressed size of the file

Body

Raw data of the files. See List of File Formats for a list of the file types that may exist within a DBPF file.

Pseudocode

To read files inside a DBPF file, you need to perform the following steps, in order:

  • Read the DBPF header.
  • Read the Index Tables.
  • Check for a DIR record.
  • Check for the file you want to extract.
  • Is this file compressed? If so, decompress it.
  • Read the file data and process accordingly.

For an example PHP class for reading DBPF files, see DBPF/Source Code

Visual Format Guide

These visual guides to the DBPF file format were created by DarkMatter:

DBPF v1.x Visual Guide
DBPF v1.x
DBPF v2.0 Visual Guide
DBPF v2.0

Some information was taken from old DatGen source code, such as the Created/Modified timestamps and possible Flags DWORD. That information may not be accurate, per DarkMatter's own description. Reason given is that it was some time ago that he "last chatted with Maxoids about the DBPF format."