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 (http://en.wikipedia.org/wiki/Hexadecimal) 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 (http://www.modthesims2.com/wiki.php?title=DBPF), 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 (http://sc4devotion.com/forums/index.php?topic=5656.msg179613#msg179613)
- SC4 Exemplar Files (http://sc4devotion.com/forums/index.php?topic=5656.msg179614#msg179614)
- SC4 Other Game Files (http://sc4devotion.com/forums/index.php?topic=5656.msg179615#msg179615)
(https://www.sc4devotion.com/forums/proxy.php?request=http%3A%2F%2Fi232.photobucket.com%2Falbums%2Fee198%2FRippleJet%2FSC4FileRelations.gif&hash=5f34071a51dc975eaa611e3326ea78ae41a1cd74)
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
Container FilesThe file extension isn't significant, the game loads every file in the plugins folders at startup and checks whether it's a
DBPF File (http://www.modthesims2.com/wiki.php?title=DBPF).
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 (http://www.sims2wiki.info/wiki.php?title=DIR) is included, if at least one Game File is compressed.
SC4Model FilesThis is a container file created by
B.A.T.
Normally it contains 20
S3D Files (http://www.modthesims2.com/wiki.php?title=S3D) and a larger number of
FSH Files (http://www.modthesims2.com/wiki.php?title=FSH).
It also contains an
XML File (http://en.wikipedia.org/wiki/XML), 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 (http://en.wikipedia.org/wiki/JFIF) and two
BMP Files (http://en.wikipedia.org/wiki/Bitmap).
These are not used in the game and are not needed, unless you want to upload the model on the official exchange...
SC4Desc FilesThis 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 (http://en.wikipedia.org/wiki/XML) listing all property values.
This XML file is used by Maxis' LotEditor, but isn't needed in the game.
SC4Lot FilesThis 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 (http://www.sims2wiki.info/wiki.php?title=LDAT) (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 (http://sc4devotion.com/forums/index.php?topic=11.0)
DAT FilesA 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.
Exemplar Files (http://www.sims2wiki.info/wiki.php?title=EXMP) (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 ExemplarsThis exemplar lists all items that have been placed on a lot in Maxis' LotEditor.
They are listed in properties called
LotConfigPropertyLotObject (http://www.modthesims2.com/wiki.php?title=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) (http://sc4devotion.com/forums/index.php?topic=211.0).
Building ExemplarsBuilding 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 ExemplarsJust 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 (http://sc4devotion.com/forums/index.php?topic=4789.0)
Foundation ExemplarA 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 ExemplarsAll 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).
Other Game FilesIn 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:
(https://www.sc4devotion.com/forums/proxy.php?request=http%3A%2F%2Fi232.photobucket.com%2Falbums%2Fee198%2FRippleJet%2FSC4BuildingExemplar.gif&hash=5c8c91d4f108ba9f883993268244bb34565a4dee)
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 (http://www.sims2wiki.info/wiki.php?title=S3D) (Type ID = 0x5AD0E817)
Simglide 3D Files are basically the
LOD (http://en.wikipedia.org/wiki/Level_of_detail_(programming)) (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 (http://sc4devotion.com/forums/index.php?topic=4093.0).
FSH Files (http://www.sims2wiki.info/wiki.php?title=FSH) (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 (http://sc4devotion.com/forums/index.php?topic=4843).
PNG Files (http://en.wikipedia.org/wiki/Portable_Network_Graphics) (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 (http://sc4devotion.com/forums/index.php?topic=4959.0)
LTEXT Files (http://www.sims2wiki.info/wiki.php?title=LTEXT1) (Type ID = 0x2026960B)
LTEXT Files are used for most texts in the game.
They support
UNICODE (http://en.wikipedia.org/wiki/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 (http://sc4devotion.com/forums/index.php?topic=548.0)
UI Files (http://www.sims2wiki.info/wiki.php?title=UI) (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 (http://sc4devotion.com/forums/index.php?topic=1012.0).
TRK Files (http://www.sims2wiki.info/wiki.php?title=TRK) (Type ID = 0x0B8D821A)
Track Definition Files are used to link to sound sources, which can be
XA Files (http://www.sims2wiki.info/wiki.php?title=XA) or
WAV Files (http://en.wikipedia.org/wiki/WAV).
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 (http://www.simtropolis.com/forum/messageview.cfm?catid=42&threadid=49433).
DIR Files (http://www.sims2wiki.info/wiki.php?title=DIR) (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.