Civilization II SAV/SCN file format

[Mercator]

Prologue

This thread is intended to become a reference guide to the Civilization II savegame and scenario file format. It is a vital first step if we ever want to see a universal civ2 scenario editor. I started this thread to make it a more public and centralized effort, as opposed to Allard's Hex Editing document. While being an indispensable initiative, I believe it's become almost unmanageable. There never was one central place to post new discoveries, making it impossible to keep up to date.

But for this new effort to succeed, we need your help. So, please post your discoveries about the file format here.

However, this is mostly meant to be a raw file format reference, not (yet) a complete guide to how every single byte can be used in making your scenarios. When you do have a new discovery, please keep it concise and to the point. But feel free to add comments or ask questions, as long as they're specifically about this reference, and not about hex-editing in general.

Please do NOT ask your hex-editing questions here. If you have a question, post a new thread.

As you will notice, apart from the table of contents the file format is still mostly uncompleted. That's not because we know so little, but simply because I haven't added all of it yet. This thread will probably always remain a work in progress. And for the moment certainly not only for the file format itself. I will also be adding notes on the notation and some of the terms used. Notes will follow right after the table of contents, including notes on the table of contents itself.

Table of Contents

• Notes
• Credits
• File Format
  1. Header (12)
  2. Settings (CiC:558, FW/MGE:572, ToT:1238)
     1. ??? (ToT:640)
     2. Menu (16)
     3. Game (38)
     4. Technologies (200, CiC: 186)
        1. First to Discover (100, CiC:93)
        2. Discovered By (100, CiC:93)
     5. Wonders (56)
     6. ??? (262, ToT:288)
  3. Civilizations (13118, ToT:28478)
     1. Names (7 * 242 = 1694)
     2. Properties (8 * 1428 = 11424, ToT: 8 * 3348 = 26784)
  4. Transporters (ToT10: 4 + 14 * transporters, ToT11: 172 + 14 * transporters)
  5. Maps
     1. Header (14, ToT:16)
     2. Data, repeat for all maps in ToT (13 * surface, ToT: 13 * surface + 2)
        1. Visible Improvements (7 * surface)
        2. Map (6 * surface)
        3. Resource Seed (ToT:2)
     3. ??? (2 * 6th header value * 7th header value)
  6. ??? (1024, ToT:10240)
  7. Units (26 * units, MGE: 32 * units, ToT: 40 * units)
  8. Cities (84 * cities, MGE: 88 * cities, ToT: 92 * cities)
  9. ???
  10. Passwords (MGE/ToT: 224)
  11. ???
  12. Conquest History (338)
  13. Events
      1. Header (FW: 6, ToT: 8)
      2. Events (FW: 298 * events, ToT: 276 * events)
      3. String Heap

Notes

Table of Contents

Let me start off with some comments about the notational use in the table of contents. Due the differences between the various game versions, as well as the presence of variable-size sections I have refrained, and will refrain, from using file offsets. Instead, I indicate the size in bytes of all different parts of the file format. You should be able to calculate the exact position yourself.

So, in parentheses is mentioned the size in bytes of that (sub-)section. Differences between the game versions are marked with their respective abbreviations:

CiC

Civilization II Scenarios: Conflicts in Civilization and all prior versions, including the original "classic" Civilization II v2.42.

FW

Civilization II: Fantastic Worlds

MGE

Civilization II: Multiplayer Gold Edition with the latest patch version 1.3 and all equivalent versions, including Civilization II: Ultimate Classic Collection and the add-on Civilization II: Multiplayer

ToT

Civilization II: Test of Time

ToT10

More specifically, the unpatched version of Test of Time, version 1.0

ToT11

Patched Test of Time v1.1

A size unmarked by any abbreviation applies to all versions, with the possible exception of any marked sizes. E.g. Header (12) means the header is 12 bytes for all versions, Header (14, ToT:16) means the header is 14 bytes for all versions except Test of Time, for which it is 16 bytes. Passwords (MGE/ToT: 224) means this section only exists in the MGE and ToT versions, where it is 224 bytes.

File Format

Data Types

Onto the file format notes. So far, there are three data types: The null-terminated string is a variable length type for text. It always ends with a byte value of zero, meaning a string of 9 bytes only has place for at most 8 characters. The signed short integer is a numeric data type taking up 2 bytes. It can take values from -32768 to +32767. The unsigned byte should be self-explanatory. It takes values from 0 to 255.

Description

If the specific order of a section with multiple values is not specified, you can assume the order as used in the RULES.TXT. This applies, for instance, to the technology and wonder sections.

Hexadecimals

I mark hexadecimals with the prefix "0x". In this guide I write them in big-endian notation. In other words, in the same way you'd see them in your Windows calculator. However, in the binary file format, the numeric data types use a reverse, little-endian, notation with the least significant value first. The bytes appear in reverse order. E.g. for a short integer value, your hexadecimal calculator might say 27, which I would write in this guide as 0027 (since a short takes 2 bytes), but in the savegame file it would be written as 2700.

Credits

In alphabetical order:

• AGRICOLA
• Captain Nemo
• Paul "Kull" Cullivan
• Carl "Gothmog" Fritz
• Allard Höfelt
• Andrew "Panda" Livings
• Mercator
• Javier "yaroslav" Mu&ntilde Kirschberg
• Dusty Reichwein
• Angelo Scotto
• SlowThinker
• Harlan Thompson
• Xin Yu

[Mercator]

File Format

Header (12)
	Data Type (#Bytes)	Description	Value	Version
	String (9)	File type identifier	"CIVILIZE"
	Byte (1)	Unknown	0x1A
	Short (2)	File type version	0x0027 (39)	Classic, Conflicts in Civilization
			0x0028 (40)	Fantastic Worlds
			0x002C (44)	Multiplayer v1.3
			0x0031 (49)	Test of Time v1.0
			0x0032 (50)	Test of Time v1.1
Settings (CiC:558, FW/MGE:572, ToT:1238)
??? (ToT:640)
	Data Type (#Bytes)	Description	Value	Version
	Unknown (640)			Test of Time
Menu (16)
	Data Type (#Bytes)	Description	Value	Version
	Unknown (16)	Menu settings
Game (38)
	Data Type (#Bytes)	Description	Value	Version
	Short (2)	Turn number
	Short (2)	Year (negative for B.C.)
	Unknown (34)	More game settings
Technologies (200, CiC: 186)
First to Discover (100, CiC:93)
	Data Type (#Bytes)	Description	Value	Version
	Byte (100, CiC:93)	For all advances, the value of the civilization that first disovered it.	None: 0, White: 1, Green: 2, Blue: 3, Yellow: 4, Cyan: 5, Orange: 6, Purple: 7
Discovered By (100, CiC:93)
	Data Type (#Bytes)	Description	Value	Version
	Byte (100, CiC:93)	For all advances, the sum of the values of all civilizations that discovered it.	Red: 1, White: 2, Green: 4, Blue: 8, Yellow: 16, Cyan: 32, Orange: 64, Purple: 128
Wonders (56)
	Data Type (#Bytes)	Description	Value	Version
	Short (56)	Wonder location	Not yet built: 0xFFFF (-1), Destroyed: 0xFFFE (-2), City ID otherwise (0 for first city, 1 for second etc.)

[Mercator]

To be continued... (2)

[Mercator]

To be continued... (3)

[Mercator]

To be continued... (4)

[Mercator]

I don't yet want to move this thread to the hints, tips & guides subforum, so I'll top it here for the moment.

Edit: Notes have been expanded, Wonders section added to file format.

[Catfish]

@Mercator:

Those 640 "unknown" bytes in ToT's "Settings" section are actually the units' transport site relationships, read from the Advanced Unit fields in rules.txt and written to the .sav file when it's first created. Thereafter, modification is only possible via hex editing or the Transport action in events – editing the rules file will have no effect. The block consists of 80 (max number of units) x 8 (4 shorts) bytes, starting at byte 12 (dec).

For each unit:

Bytes 1-2: Basically a cross-referencing of the unit Build Transport Site mask and the Map Transport Relationships. Values for each of the 6 possible relationships (obviously, none, some or all are possible):

(0,1) 0x0012
(0,2) 0x0104
(0,3) 0x1008
(1,2) 0x0240
(1,3) 0x2080
(2,3) 0x4800

The 16 bits are divided into four (4 bits for each map – each bit representing a connection to another map), eg, (1,2) 0x0240 = (Map 1) 0100 (Map 0) 0000 (Map 3) 0000 (Map 2) 0010.

Bytes 3-4: Build Transport Site mask. Values: 0x0000 – 0xFFFF
Bytes 5-6: Use Transport Site mask. Values: 0x0000 – 0xFFFF
Bytes 7-8: Native Transport Site Ability mask. Values: 0x0000 – 0xFFFF

Edit: Sorry, I've realised my notation is incorrect. I'd transplanted the values from some old notes of mine. Fixed now.

[Mercator]

Great! The other "unknowns" are actually mostly known already, but I just haven't put the values in yet... But I didn't know this. I'll add it later.

[AGRICOLA]

The following is an explanation of the function of byte 15 in MGE and byte 12 in FW in Allard Höfelt’s UNITS INFORMATION section. I don’t actually have FW, but byte 12 is the only one in his article that has no explanation beyond a comment that “?? does change”. I have no information on TOT, but there likely is a byte in the low teens that serves the same purpose as byte 15 in MGE. As both MGE and FW are based closely on the structure of the original CIV unit information strings, it would be surprising if TOT was radically different.


In any case, these bytes are used only by Settlers and Engineers engaged in building terrain improvements or in transforming terrain.


If a single unit carries out the work, the process is simple. During each turn of building/transforming, the unit earns points and the accumulated points are stored in byte 12 or 15. When the point total reaches or exceeds the number required to complete a particular task, the task is finished, the icon for the square is changed, the point total is reset to 0 and the unit becomes available for the next task. If the unit is activated before it completes a task, it retains its accumulated points so that they will count towards its next task. This is the basis of creating the “pre-charged” engineers/settlers that players can use to their advantage.

If two or more units on a square are assigned to the same task, the process is somewhat more complicated but does provide an explanation for the empirical observation that assigning more than 3 units to a task does not speed up completion.



An engineer in CIV II generates 2 points per turn. A settler generates 1 point. These numbers remain constant when the “Base time for engineers to transform terrain (x2)” is changed in the Rules file. With the “Base time…….” set to 20 (vanilla CIV II), twenty points are needed to transform Grassland to Hills.

Consequently, if the Grassland to Hills transformation command is entered on turn 1, a single Engineer will complete the transformation on turn 10. Its byte 15 is changed to 2 on turn 1, is incremented by 2 on each of the following 9 turns, and reaches 20 on turn 10.

If 2 engineers (E1 and E2) are assigned to the task, their byte 15’s change as follows:

UNIT -- E1 E2
TURN 1 04 00
TURN 2 08 00
TURN 3 12 00
TURN 4 16 00
TURN 5 00 00 Task completed

Points accumulated by both units are credited to E1. No points are wasted.


If 3 engineers carry out the transformation, the points are credited as follows:

UNIT -- E1 E2 E3
TURN 1 04 00 02
TURN 2 08 00 04
TURN 3 14 00 04
TURN 4 00 00 00 Task completed

Points earned by E1 and E2 are credited to E1, but only 4 of the points earned by E3 (turns 3 and 4) are credited to E1 and contribute to the completion of the project. The 4 points earned by E3 during turns 1 and 2 are wasted. Although 3 Engineers complete the transformation one turn sooner than 2, the Law of Diminishing Returns has set in.

Note that the above data also shows why it will take 3 turns to complete small tasks that require 10 points for completion, regardless of whether 2 or 3 Engineers are used,



To better illustrate the futility of using more than 3 Engineers on one task, the sample task has been changed to transforming Mountains to Hills. This requires 60 points to complete.

Consequently, 1 Engineer requires 30 turns for the transformation and 2 Engineers require 15.

When 3 Engineers are used, their byte 15’s change as follows:

UNIT --- E1 E2 E3
TURN 01 04 00 02
TURN 02 08 00 04
TURN 03 14 00 04
TURN 04 20 00 04
TURN 05 26 00 04
TURN 06 32 00 04
TURN 07 38 00 04
TURN 08 44 00 04
TURN 09 50 00 04
TURN 10 56 00 04
TURN 11 00 00 00 Task completed

The use of 3 rather than 2 Engineers shortens the process to 11 turns. The waste of 4 points is of no real significance in a task requiring 60 points.


If we increase the number of Engineers to 4, their byte 15’s change as follows:

UNIT --- E1 E2 E3 E4
TURN 01 04 00 00 04
TURN 02 10 02 00 04
TURN 03 16 04 00 04
TURN 04 22 06 00 04
TURN 05 28 08 00 04
TURN 06 34 10 00 04
TURN 07 40 12 00 04
TURN 08 46 14 00 04
TURN 09 52 16 00 04
TURN 10 58 18 00 04
TURN 11 00 00 00 00 Task completed

The addition of the fourth Engineer has not speeded completion. 22 points have been wasted, 18 from E2 and 4 from E4. This increased waste negates the points contributed by the fourth Engineer.


Finally, if 10 Engineers are used for the transformation, the following happens:

UNIT --- E1 E2 E3 E4 E5 E6 E7 E8 E9 E10
TURN 01 04 00 00 00 08 02 02 02 02 00
TURN 02 06 02 02 02 10 04 04 04 00 06
TURN 03 14 04 04 04 12 06 06 06 00 04
TURN 04 20 06 06 06 14 08 08 08 00 04
TURN 05 26 08 08 08 16 10 10 10 00 04
TURN 06 32 10 10 10 18 12 12 12 00 04
TURN 07 38 12 12 12 20 14 14 14 00 04
TURN 08 44 14 14 14 22 16 16 16 00 04
TURN 09 50 16 16 16 24 18 18 18 00 04
TURN 10 56 18 18 18 26 20 20 20 00 04
TURN 11 00 00 00 00 00 00 00 00 00 00 Task completed

The increased waste has negated the contributions of 7 Engineers so that the task still takes 11 turns to complete. As all this data is empirical, I cannot prove that 11 turns is definitely the minimum number needed for this transformation. Perhaps one of the mathematical wizards who frequent this forum might be interested in unravelling the algorithm.

Of course there are workarounds to avoid the waste, but this is not the place to discuss methods for doing this.

[AGRICOLA]

When I posted about the hex-editing of the first turn money bug in scenarios, I deliberately left out the following sentence:

“I believe that the correct size for the blocks in TECHNOLOGIES & MONEY is 1428 bytes rather than 1427.”

Although this information was included in an e-mail to Allard Höfelt, I did not considered it to be of interest to any other potential readers of my post.

However the correct value is important if you intend to work with the sizes of various data blocks rather than offsets.

[Mercator]

It's byte 14 in FW. The building progress is written in the same byte as the trade commodity and the amount of turns spent in the air... Do you know which bytes are added in MGE, or where in the structure (compared to FW) they're added?

I already knew about the 1428.

I exchanged some of my further discoveries with yaroslav, so I already have quite a few additions to the last "official" release of Allard's doc. I can e-mail it to you if you want. I don't really want to make it public yet, because it's rather messy and contains some "sensitive" information.

(Sorry for not updating this thread any further, I'm rather busy at the moment.)