SC4 Container Files, Game Files and File Relations

[RippleJet]

This tutorial covers the basics of what is included in those files you can see in your folders, e.g. SC4Lot, SC4Desc, SC4Model and DAT files.
Those files are usually called Container Files. Each container file can (and usually does) contain several Game Files.
The relationship (links, but no other properties) between the most common Game Files (those needed for custom buildings) is explained below.

No programming experience is required to follow this tutorial. However, some understanding of hexadecimal numbers is recommended.
For those who wish more in-depth information on file formats I've provided links for further reading.

Each Container File is a DBPF File, containing an index, specifying the TGI address for each Game File therein.
TGI is an acronym for Type ID, Group ID and Instance ID.
Type, Group and Instance ID's are all 32-bit integers (DWORD), that can take numbers between 0 and 4,294,967,295.
They are always written in hexadecimal though, between 0x00000000 and 0xFFFFFFFF.





The image below shows the relationship between the most important Game Files within the Container Files.

The game files are linked to each other with their TGI addresses. The red arrows show how the links are defined,
with the linking property being where the arrow starts and the target TGI address of the link being where the arrow terminates.

There's one exception to this though;
the building/prop family is not an address, it's just a property value, given in the building or prop exemplar.

For more information about these files and links, see below:

• SC4 Container Files
• SC4 Exemplar Files
• SC4 Other Game Files

Note that each Game File must have a unique TGI address. Otherwise conflicts will occur.
Each red link in the image above is a dependency. If the target of the link is missing, we have a missing dependency.

• If an S3D File (yellow) is missing, we get the infamous brown box
• If a Prop Exemplar (blue) is missing, we just get an missing prop
• If a Building Exemplar (green) is missing, we get a missing plugin error message at startup
• If an FSH File (texture) is missing, we get a missing texture

[RippleJet]

Container Files

The file extension isn't significant, the game loads every file in the plugins folders at startup and checks whether it's a DBPF File.
However, we are used to dealing with only four "standard file extensions", SC4Model, SC4Desc, SC4Lot and DAT.

For a description of the Game Files that are included in a Container File, please see further down in this tutorial.
Common for all container files is that a DIR File is included, if at least one Game File is compressed.


SC4Model Files
This is a container file created by B.A.T.
Normally it contains 20 S3D Files and a larger number of FSH Files.

It also contains an XML File, listing the name and size of the model.
This XML file is used by Maxis' PluginManager to identify the model, but isn't needed for the game.

Furthermore, it contains two JFIF Files and two BMP Files.
These are not used in the game and are not needed, unless you want to upload the model on the official exchange...


SC4Desc Files
This container file is created by Maxis' Plugin Manager (or wouangaine's PIM-X, included in the "X Tool").
It's a "descriptor file", containing at least one game file, an Exemplar File, the most common of which are:

• Building Exemplar
• Prop Exemplar
• Foundation Exemplar

If an LTEXT file has been used for naming the building, this is also included in the SC4Desc file.

It also contains an XML File listing all property values.
This XML file is used by Maxis' LotEditor, but isn't needed in the game.


SC4Lot Files
This container file is created in Maxis' LotEditor (or wounagaine's LOT-X, included in the "X Tool").
It contains (at least) an Exemplar File for the lot, called the LotConfiguration Exemplar.

A SC4Lot file made by Maxis' LotEditor contains an LD File (Lot Data).
It includes some general info and the filenames for the prop dependencies. However, other dependencies are not included.
This is not used in the game and isn't needed, unless you want to upload the lot on the official exchange...

A SC4Lot file also contains one PNG for previewing the lot.
This is not used in the game and isn't needed, unless you want to upload the lot on the official exchange...

SC4Lot files for ploppable buildings contain several additional game files:

• The Building Exemplar (copied and modified from the SC4Desc file)
• One PNG File for the item icon
• Possible LTEXT files for naming the building and for the item description

Note also that some creators include the Building Exemplar for growable lots in the SC4Lot file.
The reason for this is to reduce the number of files needed for each lot.
For more information about this, read BarbyW's Tidy Files - An intermediate modding tutorial


DAT Files
A DAT file is usually a Container File that is made by merging several Game Files.
E.g. a Prop Pack would contain S3D Files and FSH Files from several Prop SC4Model files, and also the corresonding Prop Exemplars.
A Texture Pack would normally be just a collection of Base and Overlay FSH Files, to be used in the LotEditor.

[RippleJet]

Exemplar Files (Type ID = 0x6534284A)

There are several types of Game Files, and the among the most important ones are certainly the Exemplar Files.
An Exemplar File contains a list of properties and their values.

There are several types of Exemplar Files. Only those in bold typeface are covered in this tutorial:

• 0x01 Tuning
• 0x02 Building
• 0x03 RCI
• 0x04 Developer
• 0x05 Simulator
• 0x06 Road
• 0x07 Bridge
• 0x08 Misc Network
• 0x09 Network Intersection (unused, 0x21 used instead)
• 0x0A Rail
• 0x0B Highway (Puzzle Piece)
• 0x0C Powerline
• 0x0D Terrain
• 0x0E Ordinances
• 0x0F Flora
• 0x10 Lot Configuration
• 0x11 Foundation
• 0x12 Advice (unused)
• 0x13 Lighting
• 0x14 Cursor (unused)
• 0x15 Lot Retaining Wall
• 0x16 Vehicle
• 0x17 Pedestrian
• 0x18 Aircraft
• 0x19 Watercraft
• 0x1E Prop
• 0x1F Construction
• 0x20 Automata Tuning
• 0x21 Network Intersection (Type 21)
• 0x22 Disaster
• 0x23 Data View
• 0x24 Crime
• 0x25 Audio
• 0x26 MySim Template
• 0x27 Terrain Brush
• 0x28 Misc Catalog
• 0x2A Trend Bar
• 0x2B Graph

LotConfiguration Exemplars
This exemplar lists all items that have been placed on a lot in Maxis' LotEditor.
They are listed in properties called LotConfigPropertyLotObject.

The first value (rep) listed for each LotConfigPropertyLotObject specifies what type of an object it is
(only the most common ones are listed here):

• 0x00000000 = Building
• 0x00000001 = Prop
• 0x00000002 = Texture

Each LotConfiguration Exemplar must have one building, and a maximum of 1,279 other items (props, textures, etc.).
The last value listed for each such LotConfigPropertyLotObject is an Instance ID (or Family ID).
This links to the Instance ID of the Building Exemplar or Prop Exemplar mentioned below.

If it links to a Building/Prop Family, the building or prop is randomly chosen among those belonging to that family.
For more information about building and prop families, see Jeroni's Creating your own Prop Families (Extended Version).


Building Exemplars
Building exemplars contain a property called Resource Key Type (RKT).
There are several variations of these. For buildings only RKT0 and  RKT1 are used.

They both contain a TGI address pointing to a S3D File.

• If the Resource Key Type is 0, the S3D file pointed to will be used for all rotations and zooms
• If the Resource Key Type is 1, the S3D file pointed to will be the one for Zoom1, South View

For more information about the S3D files, see the further below.
Typically, if the bat has been rendered only once, the Instance ID in the RKT will always be 0x00030000.


There is a significant difference between building exemplars for growable and ploppable buildings.
When the game decides to grow a lot, it looks for available lots and decides which lot to grow based on e.g. lot size and growth stage.

However, when you decide to plop a building from the menus, you are selecting a building, not a lot.
Ploppable building exemplars contain properties that are unique for the lot and cannot appear on more than one lot.
E.g. the Item Icon and Item Description (seen in the menu) are given in the Building Exemplar, and is unique for each ploppable building/lot.

For this reason there is also a link back from a ploppable Building Exemplar to the LotConfiguration Exemplar.
This link is given in the property Lot Resource Key and lists the Instance ID for the LotConfiguration Exemplar.

When making a ploppable building exemplar (descriptor) in PluginManager, the lot is still undefined.
Thus, the Lot Resource Key cannot be a valid one, and only contains the address 0x0, 0x0, 0x0.
It's when making the lot in LotEditor, that the Lot Resource Key is specified and inserted.
At this stage the whole building exemplar is copied into the SC4Lot container file.
After this the original descriptor file (SC4Desc file) is obsolete and should be deleted.


Prop Exemplars
Just like building exemplars, all prop exemplars contain the property Resource Key Type (RKT).
For props RKT0, RKT1 and RKT4 can be used.

They all contain a TGI address pointing to a S3D File.

• If the Resource Key Type is 0, the S3D file pointed to will be used for all rotations and zooms
• If the Resource Key Type is 1, the S3D file pointed to will be the one for Zoom1, South View
• If the Resource Key Type is 4, there can be several S3D files pointed to, each of them being for Zoom1, South View

For more information about making seasonal and timed props using a RKT4, please read smoncrie's tutorial Making Seasonal/Timed Props


Foundation Exemplar
A Foundation Exemplar is similar to a Building Exemplar, but with very few properties.
Just like any building, also a building foundation can be a batted object, rendered into a SCModel file.
Just like a building model, such a foundation consists of 20 S3D Files and a number of FSH Files.
The S3D File is in that case linked from the Foundation Exemplar with the property Resource Key Type 1,
which contains the full TGI address of the S3D File (see above for more information).


Cohort Exemplars
All Exemplar Files include a property called Parent Cohort.
It contains three numbers, giving the full TGI address of another Exemplar File, called a Cohort Exemplar.

This Cohort Exemplar basically serves as a template for several other Exemplars.
All properties defined in a Cohort are inherited by every Exemplar referring to it as a Parent Cohort.

Note that also Cohort Exemplars include the property Parent Cohort.
Thus, Cohort Exemplars can be nested in several layers.
If an Exemplar doesn't have a Parent Cohort (being the top-most exemplar),
the property Parent Cohort contains three zeros (pointing nowhere).

Cohorts are used for almost all in-game buildings and lots, but usually not for custom buildings.
Maxis used Cohorts to define the general properties for a set of buildings,
and the building exemplars only hold the values that are different for each building.
Everything else, such as pollution values etc., is read from the Parent Cohort.
When making custom buildings, Plugin Manager generates a full set of properties in the Building Exemplar.
Thus, a Cohort Exemplar isn't necessary (unless a modder makes one especially for this purpose).

[RippleJet]

Other Game Files

In addition to the Exemplar Files, there are several other types of Game Files.
The most important ones, used in custom building exemplars, are covered in the image below:





Note that Building Exemplar, Foundation Exemplar and Cohort Exemplar are covered in the Exemplar Files section above!

Similarly as was noted above with Exemplar Files, each red arrow is a link and dependency.
If any of the links above would be missing, we'd have implications in the game:

• A missing UI file would lead to nothing happening when querying (clicking) a building in the game
• A missing TRK, XA or WAV file would lead to missing sounds (not that noticeable)
• A missing LTEXT file would lead to a "NOT IN TEXT DATABASE" error appearing, instead of the text
• A missing icon PNG file would cause the icon to disappear from the menu, and a vertical shift to occur among several items in the menu

Those files that appear on a pink background above, are those you would probably find in a Container File called "Essentials".





S3D Files (Type ID = 0x5AD0E817)
Simglide 3D Files are basically the LOD (Level Of Detail) triangles as exported from B.A.T.
It includes the coordinates of the vertices and links to the textures (materials) that are mapped onto it.
The material links point to the Instance ID's of FSH Files (see below).
S3D files can also be animated.

A unique Group ID is generated each time a new S3D model is rendered in B.A.T.
The Instance ID, 0xNNNNNZR0, has a specific numbering to distinguish between different zooms and rotations:

• NNNNN is a number that's incremented each time the same model is rendered, starting with 00030
• Z is the zoom bit, 0=Zoom1, 1=Zoom2, 2=Zoom3, 3=Zoom4, 4=Zoom5
• R is the rotation bit, 0=South, 1=East, 2=North, 3=West

Some further understanding in how S3D files work can be achieved by reading Chrisim's
Tutorial: MODding rendered SC4Models.





FSH Files (Type ID = 0x7AB50E44)
FSH Files are texture files.
They can be used either as base/overlay textures on a lot or as textures that are mapped on S3D models.

The textures that are mapped onto S3D models are rendered in B.A.T.
The Instance ID, 0xNNNNNZRQ, has a numbering similar to the one for S3D files (see above):

• NNNNN is a number that's incremented each time the same model is rendered, starting with 00030.
  For night time views, overlay textures are used with adding 8 to this, ie. starting with 00038
• Z is the zoom bit, 0=Zoom1, 1=Zoom2, 2=Zoom3, 3=Zoom4, 4=Zoom5
• R is the rotation bit, 0=South, 1=East, 2=North, 3=West
• Q is an incremental number (if several textures are mapped onto one S3D model).
  If there are more than 16 textures, 0x40 is added to the next ones (in order not to interfere with the R bit)

Base and Overlay textures that can be used on lots are fixed in size and come in four different sizes (zooms).
They can also be made wealth dependent and they can be random (picked randomly from a list).
The Instance ID's for these texture must follow a specific numbering.
For more information, please read Geoffhaw's Explanation of the Texture IID.





PNG Files (Type ID = 0x856DDBAC)
PNG Files are used for most graphic elements in the game.
Among them are the item icons (those that appear in the menus in the game).

An item icon has to be exactly 44 pixels tall and 176 pixels wide.
It is divided into four separate images, each being 44×44 pixels.

Those four images, from left to right, represent the icons used when:

• The object is unavailable
• The object is available (normal state)
• The icon is depressed
• The icon is highlighted (selected)

Simplified item icons are automatically created for ploppable buildings in Maxis' LotEditor.
For more information about custom icons, please read Travis' simplified custom icon tutorial





LTEXT Files (Type ID = 0x2026960B)
LTEXT Files are used for most texts in the game.
They support UNICODE and can thus be used for text in any language.

LTEXT Files can be linked to in two main ways:

• User Visible Name Key (from a Building Exemplar, Prop Exemplar or Foundation Exemplar)
• Item Description Key (from a ploppable Building Exemplar)

Both these Keys include the full TGI address of the LTEXT File.

Any text field or button in a query UI File can point to an LTEXT File with captionres.
The LTEXT File pointed to by this "caption resource" contains the text to be inserted in the query.
Additionally, a button in a query UI file can point to a LTEXT File with tipres.
The LTEXT File pointed to by this "tip resource" contains the text to be shown when hovering above a button in the query.
Both the captionres and the tipres include only the Group ID and Instance ID of the address.

All in-game LTEXT Files reside in the container file called SimCityLocale.DAT.
For more information, please read LTEXT Files - Definition and Tutorial





UI Files (Type ID = 0x00000000, Group ID = 0x96A006B0)
Maxis' own User Interface format is used for all queries in the game.

They are linked to from the Building Exemplar with the property Query Exemplar GUID,
which only contains the Instance ID of the UI File.

For more information, please read Daeley's How to Create/Edit Query Interfaces.





TRK Files (Type ID = 0x0B8D821A)
Track Definition Files are used to link to sound sources, which can be XA Files or WAV Files.
The properties of TRK files are still mostly unknown, but custom TRK files can be created by copying an existing one.

There are several properties linking to TRK Files from a Building Exemplar, e.g.:

• SFX: Query Sound
• SFX: Query Sound Abandoned
• SFX: Query Sound Decayed
• SFX: Default Plop Sound
• SFX: Activate Sound
• SFX: Ambience Good Sound
• SFX: Ambience Decayed Sound
• SFX: Alarm SoundID

All these properties include the Instance ID of the TRK File they are pointing to.

Also a button in a query in a UI file can point to a TRK file with btnclicksnd.
In this case both the Group ID and Instance ID are included in the address.

All in-game TRK and XA Files reside in the container file called Sound.DAT.
The only available tutorial is an old one by Pegasus called Custom query sound - tutorial.





DIR Files (Type ID = 0xE86B1EEF)
A Directory File is just an index pointing at all those included Game Files that are compressed.
The purpose of the DIR file is to speed up the loading of the Game Files at startup.