Satisfactory Save Game - File Structure

Documentation of the Satisfactory save game file structure.

Content

Introduction
General file structure
- Save header
- Chunks
Decompressed binary data
- TOCBlob
- DataBlob
Objects
Properties
Structs
- Property Structs
- Binary Structs
Type and Object Reference
Blueprints
- BlueprintCfg File
- Blueprint File
  - Blueprint Header
  - Blueprint Binary Data
    - Blueprint TOCData
    - Blueprint BlobData

Introduction

Satisfactory is a game from Coffee Stain Studios based on the Unreal Engine. Many data structures in the save game are based on the Unreal serialization system. Satisfactory uses a few data structures specific to the game. Most of them can be found in the C++ headers, distributed within the CommunityResources folder in the game's installation directory.

This documentation tries to use the original Unreal/Satisfactory type names as closely as possible. The structure of all types and objects used in this document is referenced at the end, see Type and Object Reference.

All binary data is encoded little-endian in the save.

Document Version: Satisfactory 1.0

General file structure

The save file starts with a save header, followed by chunks of zlib compressed data. Each chunk starts with a chunk header followed by the binary chunk data.

+--------------+
| Save Header  |
+--------------+
| Chunk Header |
+--------------+
| Chunk Data   |
+--------------+
| Chunk Header |
+--------------+
| Chunk Data   |
+--------------+
| ...          |
+--------------+

Save header

The save header has the following structure:

+----------+-----------------------+
| int32    | SaveHeaderVersion     |
| int32    | SaveVersion           |
| int32    | BuildVersion          |
| FString  | MapName               |
| FString  | MapOptions            |
| FString  | SessionName           |
| int32    | PlayDurationSeconds   |
| int64    | SaveDateTime          |
| int8     | SessionVisibility     |
| int32    | EditorObjectVersion   |
| FString  | ModMetadata           |
| bool     | IsModdedSave          |
| FString  | SaveIdentifier        |
| bool     | IsPartitionedWorld    |
| FMD5Hash | SaveDataHash          |
| bool     | IsCreativeModeEnabled |
+----------+-----------------------+

This is the save header as of Update 8 and 1.0. In the past, the header was shorter, but additional values were added with updates. Each time this struct is extended, the SaveHeaderVersion value increases, the current value is 13. Internally, an enum Type is used for this number, see FGSaveManagerInterface.h distributed with the game files. The variable names are taken from the struct FSaveHeader in FGSaveManagerInterface.h.

SaveDateTime is the serialization of an FDateTime object. Ticks since 0001-01-01 00:00, where 1 tick is 100 nanoseconds. Satisfactory seems to use the UTC time zone.

Source Reference: FGSaveManagerInterface.h - struct FSaveHeader

Chunks

The save data is stored in a binary structure (see below). This binary structure is divided into chunks, which are then individually compressed with zlib. The division into chunks is done purely on size and has nothing to do with the serialized content within this binary structure. In the save data, each chunk is prefixed by a header, followed by the compressed binary data.

The chunk header has the following structure:

+---------------+---------------------------+----------------------------------------------+
| int32         | PACKAGE_FILE_TAG          | always `0x9E2A83C1`                          |
| int32         | archive header            | 0x00000000: v1 header, 0x22222222: v2 header |
| int64         | max chunk size            | always `131072`                              |
| if v2 header: |                           |                                              |
|     uint8     | CompressorNum             | compression algorithm, 3: zlib               |
| int64         | compressed size summary   | compressed buffer size                       |
| int64         | uncompressed size summary | uncompressed buffer size                     |
| int64         | compressed size           | compressed buffer size                       |
| int64         | uncompressed size         | uncompressed buffer size                     |
+---------------+---------------------------+----------------------------------------------+

PACKAGE_FILE_TAG is a constant magic number. archive header was introduced with the Unreal 5 upgrade and marks if CompressorNum exists. max chunk size is the maximum size used for (uncompressed) chunks. This is a hardcoded constant from Unreal. CompressorNum is the index of the used compression algorithm, which currently seems to be always zlib (value = 3). compressed size refers to the size of the compressed chunk data within the save file. uncompressed size is the size of the chunk data after decompression with zlib. All chunks, except the last one, use max chunk size as uncompressed size. The sizes are stored twice with identical values (see below). After decompression, all uncompressed chunk buffers are merged into a single large binary object, defined in the next section.

Unreal internal details:
Unreal can serialize an archive to a compressed structure. Unreal uses the struct FCompressedChunkInfo to store chunk header information. It is a pair of two int64 sizes. A compressed archive starts with an FCompressedChunkInfo containing the PACKAGE_FILE_TAG and COMPRESSION_CHUNK_SIZE. Next is an FCompressedChunkInfo with the summary compressed and uncompressed size of all data in this archive. That is followed by a series of FCompressedChunkInfo with the current chunks' size and the actual compressed chunk data. There are as many chunks until the summary size is reached. But instead of using a single archive for the binary blob, Satisfactory uses the FArchiveLoadCompressedProxy to store the big binary structure. Here, the data is not stored in a single archive but multiple archives containing just a single chunk. Probably, this structure has the advantage of decompressing the large buffer internally step by step and not all at once. Nevertheless, this explains why the buffer size is stored twice in the chunk header.

Decompressed binary data

With Update 6 and again Update 8, the format changed quite a bit; only the new format will be described here. The new format stores data for each level separately, where a level refers to a part of the game map.

The binary data layout follows the following format:

+-------------------------------------------+------------------------------------------------------+
| int64                                     | total size of binary data (not including this value) |
| FWorldPartitionValidationData             | SaveGameValidationData                               |
| TMap<FString, FPerStreamingLevelSaveData> | mPerLevelDataMap                                     |
| FPersistentAndRuntimeSaveData             | mPersistentAndRuntimeData                            |
| FUnresolvedWorldSaveData                  | mUnresolvedWorldSaveData                             |
+-------------------------------------------+------------------------------------------------------+

Structs are defined in FGSaveSession.h. FString in mPerLevelDataMap is the levelName.

FPerStreamingLevelSaveData and FPersistentAndRuntimeSaveData contain binary buffers named TOCBlob64 and DataBlob64, described in detail below. Within these, all objects of a level are stored. The result is a list of all objects TArray<UObject*> objects. However, information about each object is separated. TOCBlob64 stores metainformation about each object, such as the class name. DataBlob64 contains the internal data of each object, i.e., a list of properties.

Each object has a class name in the form /Game/FactoryGame/Buildable/Building/Foundation/Build_Foundation_8x4_01.Build_Foundation_8x4_01_C and an additional instance name. This allows for the interpretation of a save file in a hierarchical way, similar to a file system.

The size of each object varies. Therefore, the data must be parsed sequentially. Different objects are just written one by one after each other. The number of objects in the TOCBlob and DataBlob are the same (first object in TOCBlob corresponds to first object in DataBlob, ...).

TOCBlob

+-----------------------------------------------------+---------------------------+
| int32                                               | numObjects                |
| for i = 1 to numObjects:                            |                           |
|     bool                                            | isActor                   |
|     if isActor:                                     |                           |
|         FActorSaveHeader                            | objectHeader              |
|     else:                                           |                           |
|         FObjectSaveHeader                           | objectHeader              |
| if remaining data:                                  |                           |
|     if within FPerStreamingLevelSaveData:           |                           |
|         TArray<FObjectReferenceDisc>                | DestroyedActors           |
|     if within FPersistentAndRuntimeSaveData:        |                           |
|         TMap<FString, TArray<FObjectReferenceDisc>> | LevelToDestroyedActorsMap |
+-----------------------------------------------------+---------------------------+

DestroyedActors is not always present. It needs to be determined if the TOCBlob buffer has already been completely read after parsing the object headers.

Internally, the object headers are stored as FGenericObjectSaveHeader. The serialization code can be found in FWPSaveDataMigrationContext.h in the game headers.

DataBlob

+--------------------------+-------------------------------------+
| int32                    | numObjects                          |
| for i = 1 to numObjects: |                                     |
|     int32                | SaveVersion                         |
|     bool                 | ShouldMigrateObjectRefsToPersistent |
|     TArray<uint8>        | Data                                | binary object data
+--------------------------+-------------------------------------+

The size of the Data array can be used to skip over the current object. This allows only partially reading data of some objects or skipping of unknown objects.

Internally, this data is stored in the FObjectSaveData struct. The serialization code can be found in FWPSaveDataMigrationContext.h in the game headers.

Objects

Each object corresponds to an instance of a class representing any type of object. The state of each instance is serialized using the Unreal serialization system. All objects use a common UObject class as base, but each class can add additional binary save data. However, most classes use the Unreal reflection system to store their properties. Each UObject contains a List of Properties that stores all properties that utilize that reflection system. There are only a few classes that add custom binary data.

Parsing the List of Properties is probably the most complex part of save parsing. Therefore, the details are in a separate section below. The size of the class-specific binary data is the remaining buffer, of which the total size is given by the containing TArray.

The second most commonly used class is AActor. If isActor is true in the TOCBlob, the object is always an AActor instance or a class derived from AActor.

Unreal internal details:
The UObject class has a virtual method Serialize, that can be overwritten by child classes to serialize data. Each class that overwrites the Serialize method usually calls the parent Serialize method, so child classes usually only add additional data.

Note: The actual classes in the game source files may have additional classes in their inheritance tree. Here, only classes adding data to the serialization are mentioned.

UObject

+--------------------+------------+
| List of Properties | Properties |
| bool               | HasGuid    | (only observed false values so far)
| if HasGuid:        |            |
|     FGuid          | Guid       |
+--------------------+------------+

Reference to HasGuid source.