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
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. Valid values are File Mode Values 0 through 4, where "[elements]" is "player files". Note that mode 4 will reset all players' inventories, spawn locations, and other properties, but not Scoreboard statistics.
- 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. Valid values are File Mode Values 0 through 4, where "[elements]" is "map_<#>.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. Valid values are File Mode Values 0 through 4, where "[elements]" is "Objectives". In mode 4, the Objectives list will simply be empty in the output map's scoreboard.dat.
- playerScoresMode: Describes how to handle PlayerScores. Valid values are File Mode Values 0 through 4, where "[elements]" is "player score entries". 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. Valid values are File Mode Values 0 through 4, where "[elements]" is "Teams". 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).
File Mode Values
Several "Mode" tags in the fileData of the Update Format accept the following values, with the following meanings:
- 0 - Copy only [elements] from the source map (no changes).
- 1 - Copy only [elements] from the update map (full replacement).
- 2 - Copy all [elements] from the source map, as well as any [elements] in the update map which aren't in the source map (no changes to [elements] which are in source map).
- 3 - Copy all [elements] from the update map, as well as any [elements] in the source map which aren't in the update map.
- 4 - Do not copy any [elements].
Dimension Update Format
- A worldData, netherData, or endData tag. Any missing Mode tags within this (but not within any ExceptionLists) will default to 0.
- chunkMode: Describes how to handle chunks. 0 = Copy only chunks from source map. 1 = Copy only chunks from update map. 2 = Copy chunks from the source map, as well as any chunks in the update map which aren't in the source map. 3 = Copy chunks from the update map, as well as any chunks in the source map which aren't in the update map. 4 = Do not copy any chunks. Note that any missing chunks will be regenerated by the game when encountered. Also note that if a chunk is not present in the output map, settings such as blockMode or regionExceptionLists will not apply to them - such chunks will still not exist.
- chunkData: Contains tags describing how special chunk properties are to be handled.
- biomesMode: Describes how to handle biome data for chunks in the output map. Valid values are Dimension Mode Values 0 through 5, where "[data]" is "biome data" and "[default]" is biomesDefault.
- biomesDefault: May be used if biomesMode is 1, 2, or 5. Valid values are Biome IDs, or -1. Note that the game will automatically re-generate any biome data which is -1. Default value is -1.
- populatedMode: Describes how to handle TerrainPopulated for chunks in the output map. Valid values are Dimension Mode Values 0 through 5, where "[data]" is "TerrainPopulated" and "[default]" is populatedDefault.
- populatedDefault: May be used if populatedMode is 1, 2, or 5. Valid values are 0 (terrain will be populated the next time the chunk is encountered), or 1. Default value is 1.
- inhabitedTimeMode: Describes how to handle InhabitedTime for chunks in the output map. Valid values are Dimension Mode Values 0 through 5, where "[data]" is "InhabitedTime" and "[default]" is inhabitedTimeDefault.
- inhabitedTimeDefault: May be used if inhabitedTimeMode is 1, 2, or 5. Default value is 0. Set this to 3600000 to max out regional difficulty in these chunks, or -9,223,372,036,854,775,808 to have regional difficulty effectively permanently locked at 0.
- lastUpdateMode: Describes how to handle LastUpdate for chunks in the output map. Valid values are Dimension Mode Values 0 through 5, where "[data]" is "LastUpdate" and "[default]" is lastUpdateDefault.
- lastUpdateDefault: May be used if lastUpdateMode is 1, 2, or 5. Default value is 0.
- blockMode: Describes how to handle block data for chunks in the output map. Note that this mode will control blocks' IDs, Add, Data (4 bits of metadata), BlockLight, SkyLight, and TileTicks, but not TileEntities. Valid values are Dimension Mode Values 0 through 5, where "[data]" is "block data" and "[default]" is both blockDefault and blockMetaDefault.
- blockDefault: Defines the default block ID to use (never used if blockMode is 0, 3, or 4). Default value is 0 (Air).
- blockMetaDefault: Defines the default block metadata to use (never used if blockMode is 0, 3, or 4). Valid values are 0 through 15. Default value is 0.
- tileEntityMode: Describes how to handle Tile Entities for chunks in the output map. Valid values are Dimension Mode Values 0 through 5, where "[data]" is "Tile Entities" and "[default]" is "an empty list" (if [default] is used, the Tile Entity data will effectively be deleted in the output map).
- entityMode: Describes how to handle Entities for chunks in the output map. Valid values are Dimension Mode Values 0 through 5, where "[data]" is "Entities" and "[default]" is "an empty list".
- chunkExceptionLists: A list of chunkExceptionLists, which allow the updater.dat to define Exceptions for entire chunks. All Mode and Default tags are optional, and will be ignored if omitted. Mode -1, for all Mode tags, indicates "no override" (this is equivalent to omitting them).
- An individual chunkExceptionList.
- description: Not actually used by the Updater. An entirely optional string which describes this ExceptionList in a human-readable way for people looking at the raw NBT.
- chunkMode: Overrides chunkMode for chunks in this list.
- chunkData: Contains tags describing how special chunk properties are to be overridden. May be omitted entirely.
- biomesMode: Overrides biomesMode for chunks in this list.
- biomesDefault: Overrides biomesDefault for chunks in this list.
- populatedMode: Overrides populatedMode for chunks in this list.
- populatedDefault: Overrides populatedDefault for chunks in this list.
- inhabitedTimeMode: Overrides inhabitedTimeMode for chunks in this list.
- inhabitedTimeDefault: Overrides inhabitedTimeDefault for chunks in this list.
- lastUpdateMode: Overrides lastUpdateMode for chunks in this list.
- lastUpdateDefault: Overrides lastUpdateDefault for chunks in this list.
- blockMode: Overrides blockMode for chunks in this list.
- blockDefault: Overrides blockDefault for chunks in this list.
- blockMetaDefault: Overrides blockMetaDefault for chunks in this list.
- tileEntityMode: Overrides tileEntityMode for chunks in this list.
- entityMode: Overrides entityMode for chunks in this list.
- tileEntityTypes: If present and not empty, tileEntityMode will only be overridden for Tile Entities in chunks which match IDs in this list. Non-matching Tile Entities will use a lower-priority tileEntityMode (in this case, the global one). If this list is omitted or empty, all Tile Entities will be matched. Has no effect if tileEntityMode is -1 or omitted.
- A Tile Entity ID (such as "Chest" or "Music") to match for.
- entityTypes: If present and not empty, entityMode will only be overridden for Entities in chunks which match IDs in this list. Non-matching Entities will use a lower-priority entityMode (in this case, the global one). If this list is omitted or empty, all Entities will be matched. Has no effect if entityMode is -1 or omitted.
- An Entity ID (such as "Villager" or "FallingSand") to match for.
- chunks: The list of chunks for which the above Modes and Defaults are to be overridden.
- An individual chunk.
- name: Not actually used by the Updater. An entirely optional string which describes this chunk in a human-readable way for people looking at the raw NBT.
- chunk: A list of Int tags describing this chunk's location (as chunk coordinates, not block coordinates).
- The x position of this chunk.
- The z position of this chunk.
- A range of chunks.
- name: Not actually used by the Updater. An entirely optional string which describes this chunk range in a human-readable way for people looking at the raw NBT.
- chunkMin: A list of Int tags describing this range's first corner (as chunk coordinates, not block coordinates). Same format as chunk, above.
- chunkMax: A list of Int tags describing this range's second corner (as chunk coordinates, not block coordinates). Same format as chunk, above. Note that neither coordinate of chunkMax needs to actually be greater than those of chunkMin; they can also be equal or less than.
- Naturally, you're not limited to one individual chunk and one chunk range. This list can contain as many chunks and ranges as are desired; it will be read in first-to-last order, so later chunks/ranges can override earlier ones if they overlap.
- An individual chunk.
- An individual chunkExceptionList.
- regionExceptionLists: A list of regionExceptionLists, which allow the updater.dat to define Exceptions for cuboid regions. All Mode and Default tags are optional, and will be ignored if omitted. Mode -1, for all Mode tags, indicates "no override" (this is equivalent to omitting them).
- An individual regionExceptionList.
- description: Not actually used by the Updater. An entirely optional string which describes this ExceptionList in a human-readable way for people looking at the raw NBT.
- biomesMode:
- biomesDefault:
- blockMode:
- blockDefault:
- blockMetaDefault:
- tileEntityMode:
- entityMode:
- tileEntityTypes:
- entityTypes:
- regions:
-
- name: Not actually used by the Updater. An entirely optional string which describes this region in a human-readable way for people looking at the raw NBT.
- posMin:
- posMax:
-
- An individual regionExceptionList.
- tileEntityExceptionLists: A list of tileEntityExceptionLists, which allow the updater.dat to define Exceptions for Tile Entities by location or Type. All Mode and Default tags are optional, and will be ignored if omitted. Mode -1, for all Mode tags, indicates "no override" (this is equivalent to omitting them).
- An individual tileEntityExceptionList.
- description: Not actually used by the Updater. An entirely optional string which describes this ExceptionList in a human-readable way for people looking at the raw NBT.
- tileEntityMode:
- blockMode:
- blockDefault:
- blockMetaDefault:
- tileEntities:
-
- name: Not actually used by the Updater. An entirely optional string which describes this Tile Entity in a human-readable way for people looking at the raw NBT.
- location:
-
- tileEntityTypes:
- An individual tileEntityExceptionList.
- entityExceptionLists: A list of entityExceptionLists, which allow the updater.dat to define Exceptions for Entities by UUID or Type.
- An individual entityExceptionList.
- description: Not actually used by the Updater. An entirely optional string which describes this ExceptionList in a human-readable way for people looking at the raw NBT.
- entityMode:
- entities:
-
- name: Not actually used by the Updater. An entirely optional string which describes this Entity in a human-readable way for people looking at the raw NBT.
- UUIDMost:
- UUIDLeast:
-
- entityTypes:
- An individual entityExceptionList.
Dimension Mode Values
Several "Mode" tags in the Dimension Update Format accept the following values, with the following meanings:
- 0 - Use the [data] of whichever source or update map chunk originated this chunk (no changes). The effects of this depend on the value of the main chunkMode value.
- 1 - If the chunk exists in the source map, copy its [data]; otherwise set it to [default].
- 2 - If the chunk exists in the update map, copy its [data]; otherwise set it to [default].
- 3 - If the chunk exists in the source map, copy its [data]; otherwise copy the update map chunk's [data].
- 4 - If the chunk exists in the update map, copy its [data]; otherwise copy the source map chunk's [data].
- 5 - Always set value to [default].