Notice: This page describes a file format to be used by a program I plan to write. As of this writing, the program does not actually exist in any form; I will update this article with links to the program once it exists. If you somehow stumbled onto this page, feel free to ask questions or make suggestions on the Talk page - although I won't necessarily follow through on a suggestion unless I find it useful and fitting enough to implement. --WolfieMario 22:31, 5 August 2013 (UTC)
The updater.dat file is located in the root folder of any Minecraft level which supports the Minecraft Map Updater (in the same folder as the level.dat). It tells the Updater how to patch together maps and allows for version/safety checks. It is stored as a GZip'd NBT file, to be edited with conventional NBT editors such as NBTExplorer or NBTedit.
NBT Structure
- The root tag.
- mapName: The name of the Minecraft map this updater is for. Displayed to the user by the Updater once the update world has been selected.
- author: The author(s)/creator(s) of the map. Displayed to the user by the Updater once the update world has been selected.
- messages: Custom messages for the Updater to display to the user. If a string is blank, no message/dialog will be displayed.
- info: Displayed as info about the update map, once it has been selected.
- patch: Displayed as a dialog box (with the options "Continue" and "Cancel") when the Patch button is clicked.
- refresh: Displayed as a dialog box (with the options "Continue" and "Cancel") when the Refresh button is clicked.
- outdated: Displayed to the user if they attempt to update a version of the map not supported by this updater.dat. This can only happen if versionStrict is true. Note that this message is displayed in addition to the default error message which tells the user what minimum version(s) they can update from - it can be used to provide additional information, such as specific instructions for how to update their old version correctly.
- version: The version of the map this updater.dat is for. This is also displayed to the user by the Updater for the update world, and if possible, the source world. Unlike most tags, this one is required.
- updaterVersion: This version string represents the version of the Updater itself - or rather, the earliest version to support the current updater.dat format. Currently, the only valid value for this string is "1.0.0"; if you set it to a later version, users will be warned that their Updater is outdated (even when it's not - so don't do that!).
- versionStrict: 1 or 0 (true/false) - Defaults to false. If true, a different algorithm will be used to queue updates in Patch mode. Unlike the normal algorithm, this one can cause the update process to abort if no valid combination of versionUpdates can bring the source map's version to match version. Note that the updater.dat itself is considered invalid if no update's toVersion matches version.
- allowRefresh: 1 or 0 (true/false) - Defaults to true. Allows a user to use the Refresh button, which patches the map with the update in alwaysUpdate, if and only if the map's current version matches the new updater.dat's version.
- warnings: 1 or 0 (true/false) - Defaults to true. If set to false, any warnings caused by violated loose restrictions will not be displayed to the user. It is highly recommended that this setting be kept "true", to reduce the risk of accidents.
- versionUpdates: A list of compound tags representing the versioned updates.
- An individual versioned update.
- fromVersion: The newest map version this update will attempt update a map from.
- toVersion: The version this update will update the map to. Must be greater than fromVersion and must not be greater than version.
- versionStrict: 1 or 0 (true/false) - Defaults to false. If true, this update is version-strict: fromVersion must match the "current version" in the queue.
- update: Contains the data of the update itself.
- See Update Format
- An individual versioned update.
- alwaysUpdate: Contains data for the special, "unversioned" update. This data, unlike the update data in the versionUpdates list, will always be used, whether the user is Patching a map or Refreshing it.
- See Update Format
- baseOffSource: The true/false tags in this compound determine how the updater is to copy files into the output directory. When a tag is true, it indicates that the source map's copy of these files will be copied; otherwise the update map's copy of these files will be copied instead. Note that these settings have no effect on the end result of the Patch or Refresh processes; properly configuring them will merely make the process more efficient.
- worldData: 1 or 0 (true/false) - Defaults to false. Set this to true if your update will not change the majority of blocks/entities/tileEntities in the Overworld.
- netherData: 1 or 0 (true/false) - Defaults to false. Set this to true if your update will not change the majority of blocks/entities/tileEntities in the Nether.
- endData: 1 or 0 (true/false) - Defaults to false. Set this to true if your update will not change the majority of blocks/entities/tileEntities in the End.
Update Format
- An update or alwaysUpdate tag.
- fileData: Contains tags which tell the Updater how to handle non-region world files (such as level.dat, scoreboard.dat, player files, etc.). Any missing byte tags will default to 0 (for all such tags, this value represents "no changes", copying data from the source map without making any modifications and completely ignoring data in the update map).
- levelMode: Describes how to handle level.dat. 0 = Use source map's level.dat (no changes). 1 = Copy all properties from the update map's level.dat, except GameRules, Player, LastPlayed, Time, DayTime, and weather properties, which come from the source map. 2 = Copy all properties from the update map's level.dat, except Player, which comes from the source map. 3 = Use the update map's level.dat (full replacement).
- playerMode: Describes how to handle player files found in the "players" folder. 0 = Copy only players from the source map (no changes). 1 = Copy only players from the update map (full replacement). 2 = Copy all players from the source map, as well as any players in the update map who aren't in the source map (no changes to players who are in source map). 3 = Copy all players from the update map, as well as any players in the source map who aren't in the update map. 4 = Do not copy any player files (output map will have no player data).
- villageMode: Describes how to handle villages.dat. 0 = Use source map's villages.dat (no changes). 1 = Use update map's villages.dat (full replacement). 2 = Copy all villages and Tick from the source map, as well as any villages from the update map which have a Center matching no existing village (warning: a village's center can move as doors are added). 3 = Copy all villages and Tick from update map, as well as any villages from the source map which have a Center matching no existing village. 4 = Do not copy any village data (output map will not have a villages.dat; the game will regenerate village data as they are encountered).
- mapData: Contains tags describing how map data is to be handled.
- idcountsMode: Describes how to handle idcounts.dat. 0 = Use source map's idcounts.dat (no changes). 1 = Use update map's idcounts.dat (full replacement). 2 = Do not copy any idcounts.dat (output map will not have an idcounts.dat; the game will assume no map items exist and can overwrite existing map item data).
- mapMode: Describes how to handle map_<#>.dat files found in the "data" folder. Modes 0 through 4 have the same meanings as playerMode, except applying to map_<#>.dat files instead of player.dat files. Note that in mode 4, the output map will have no map item data; existing map items will be blank and automatically re-initialized to map around the spawn.
- scoreboardData: Contains tags describing how data in scoreboard.dat is to be handled.
- objectivesMode: Describes how to handle Objectives. Modes 0 through 3 have the same meanings as playerMode, except applying to individual objectives instead of player.dat files. In mode 4, the Objectives list will simply be empty in the output map's scoreboard.dat.
- playerScoresMode: Describes how to handle PlayerScores. Modes 0 through 3 have the same meanings as playerMode, except applying to individual player score entries instead of player.dat files. Note that each entry is a specific player's score in a particular objective, not all of a player's scores. In mode 4, the PlayerScores list will simply be empty in the output map's scoreboard.dat.
- teamsMode: Describes how to handle Teams. Modes 0 through 3 have the same meanings as playerMode, except applying to individual teams instead of player.dat files. In mode 4, the Teams list will simply be empty in the output map's scoreboard.dat.
- displaySlotsMode: Describes how to handle DisplaySlots. 0 = Copy DisplaySlots settings from the source map (no changes). 1 = Copy DisplaySlots settings from the update map (full replacement). 2 = Copy DisplaySlots from source map, and overwrite blank ones with ones from update map. 3 = Copy DisplaySlots from update map, and overwrite blank ones with ones from source map. 4 = Don't copy any DisplaySlots (all DisplaySlots will be cleared in the output map).
- worldData: Contains tags which tell the Updater how to handle region files for the Overworld (including chunk data, blocks, entities, and tile entities)
- netherData: Contains tags which tell the Updater how to handle region files for the Nether (including chunks, blocks, entities, and tile entities)
- endData: Contains tags which tell the Updater how to handle region files for the End (including chunks, blocks, entities, and tile entities)
- fileData: Contains tags which tell the Updater how to handle non-region world files (such as level.dat, scoreboard.dat, player files, etc.). Any missing byte tags will default to 0 (for all such tags, this value represents "no changes", copying data from the source map without making any modifications and completely ignoring data in the update map).
Dimension Update Format
-
- blockMode:
- tileEntityMode:
- entityMode:
- chunkData:
- chunkMode:
- biomesMode:
- populatedMode:
- inhabitedTimeMode:
- lastUpdateMode:
- chunkExceptionLists:
-
- description:
- chunkMode:
- biomesMode:
- populatedMode:
- inhabitedTimeMode:
- lastUpdateMode:
- blockMode:
- tileEntityMode:
- entityMode:
- chunks:
-
- name:
- chunk:
- chunkMin:
- chunkMax:
-
-
- regionExceptionLists:
-
- description:
- biomesMode:
- blockMode:
- tileEntityMode:
- entityMode:
- regions:
-
- name:
- posMin:
- posMax:
-
-
- tileEntityExceptionLists:
-
- description:
- tileEntityMode:
- blockMode:
- tileEntities:
-
- name:
- location:
-
- types:
-
- entityExceptionLists:
-
- description:
- entityMode:
- entities:
-
- name:
- UUIDMost:
- UUIDLeast:
-
- types:
-