Minecraft Wiki
Advertisement

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.

Note that most of the tags listed below are entirely optional and have default values. In fact, the only mandatory tag is the top-level version tag. All other tags which confer features unnecessary to your map's updater may safely be omitted. If any errors occur when reading the updater.dat (for example, having a tag of the wrong type), the Patch and Refresh buttons are disabled, and the user is told that the updater.dat is invalid. At this point, a button can be pressed to get the stacktrace of the exception which caused the reading failure.

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 or the tag is omitted entirely, 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.
      •  versionSpecific: A list of version-specific messages. Only one version's messages can be used; the latest applicable version will be selected. If none are applicable, patch and outdated above will be used instead.
        • An individual set of version-specific messages.
          •  version: The highest source map version to be presented these messages. If "unknown", will only be presented if source map lacks an updater.dat.
          •  versionStrict: 1 or 0 (true/false) - Defaults to false. If true, version cannot be greater than the source map's version; it must instead match it. An unknown version will still match "unknown".
          •  patch: Same meaning as patch, above.
          •  outdated: Same meaning as outdated, above.
    •  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. Cannot be "unknown". 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 if no update's toVersion matches version, the Patch button itself will be disabled altogether.
    •  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. If set to "unknown", this will only attempt to update source maps which simply lack an updater.dat.
        •  toVersion: The version this update will update the map to. Must be greater than fromVersion and must not be greater than version. Cannot be "unknown".
        •  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.
    •  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.

Update Format

  • An update or alwaysUpdate tag.
    •  summary: Not actually used by the Updater. An entirely optional string which describes this update's changes in a human-readable way for people looking at the raw NBT.
    •  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 or Stats.
      •  statsMode: Describes how to handle player stat files found in the "stats" folder. Valid values are File Mode Values 0 through 4, where "[elements]" is "player stat files".
      •  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).
      •  structureData: Contains tags describing how structure data (used for structure-based mob spawns) is to be handled.
        •  fortressMode: Describes how to handle Fortress structure data. Valid values are File Mode Values 0 through 4, where "[elements]" is "Fortresses".
        •  mineshaftMode: Describes how to handle Mineshaft structure data. Valid values are File Mode Values 0 through 4, where "[elements]" is "Mineshafts".
        •  strongholdMode: Describes how to handle Stronghold structure data. Valid values are File Mode Values 0 through 4, where "[elements]" is "Strongholds".
        •  templeMode: Describes how to handle Temple structure data (includes Desert Temples, Jungle Temples, and Witch Huts). Valid values are File Mode Values 0 through 4, where "[elements]" is "Temples".
        •  villageMode: Describes how to handle Village structure data. Valid values are File Mode Values 0 through 4, where "[elements]" is "Villages".
      •  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.
        •  teamPlayersMode: Describes how to handle the list of Players on each Team in the output map. Valid values are File Mode Values 0 through 4, where "[elements]" is "Players on this Team". If a Team does not exist in a source/update map, its list of Players will be assumed empty (for example, if this is in mode 2 and the Team does not exist in the source map, but exists in the update map, all Players will be copied from the update map's Team). In mode 4, all Teams will simply be emptied of players.
        •  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)

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 7, where "[data]" is "biome data" and "[default]" is biomesDefault.
      •  biomesDefault: Will not be used if biomesMode is 0, 3, or 4. 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 7, where "[data]" is "TerrainPopulated" and "[default]" is populatedDefault.
      •  populatedDefault: Will not be used if populatedMode is 0, 3, or 4. 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 include Dimension Mode Values 0 through 7, where "[data]" is "InhabitedTime" and "[default]" is inhabitedTimeDefault. Values 8 and 9 are the same as 5 and 6 (the "masking" modes), except replacements will be made even for cases where InhabitedTime is less than inhabitedTimeDefault. Values 10 and 11 are also the same as 5 and 6, except replacements will be made even for cases where InhabitedTime is greater than inhabitedTimeDefault.
      •  inhabitedTimeDefault: Will not be used if inhabitedTimeMode is 0, 3, or 4. Default value is 0. Any value is valid, but notable values are 3600000 (effectively maxes out a chunk's regional difficulty), or -9,223,372,036,854,775,808 (regional difficulty is effectively permanently locked to 0).
      •  lastUpdateMode: Describes how to handle LastUpdate for chunks in the output map. Valid values include Dimension Mode Values 0 through 7, where "[data]" is "LastUpdate" and "[default]" is lastUpdateDefault. Values 8 and 9 are the same as 5 and 6 (the "masking" modes), except replacements will be made even for cases where LastUpdate is less than lastUpdateDefault. Values 10 and 11 are also the same as 5 and 6, except replacements will be made even for cases where LastUpdate is greater than lastUpdateDefault.
      •  lastUpdateDefault: Will not be used if lastUpdateMode is 0, 3, or 4. Default value is 0. Any value is valid.
    •  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 7, where "[data]" is "block data" and "[default]" is both blockDefault and blockMetaDefault. Modes 5 and 6 (the "masking" modes) will check for a match of both blockDefault and blockMetaDefault, or only blockDefault if blockMetaDefault is -1.
    •  blockDefault: Defines the default/mask block ID to use (never used if blockMode is 0, 3, or 4). Default value is 0 (Air).
    •  blockMetaDefault: Defines the default/mask block metadata to use (never used if blockMode is 0, 3, or 4). Valid values are -1 through 15. Default value is 0. Note that -1 is a special value used only by blockModes 5 and 6 (see blockMode); in any other mode it will be interpreted as 0.
    •  tileEntityMode: Describes how to handle Tile Entities for chunks in the output map. Valid values are Dimension Mode Values 0 through 7, where "[data]" is "Tile Entities" and "[default]" is "nothing". If [default] is used by Modes 1, 2, or 7, the output chunk's TileEntities list will be empty. In Modes 5 or 6, a Tile Entity will be copied as long as no Tile Entity already exists at the same location (this makes 5 and 6 behave just like File Modes 2 and 3).
    •  tileEntitySafetyMode: A setting to reduce the risk of Tile Entities being modified independent of their blocks (which, if done incorrectly, can cause client or even server crashes. It's safe to remove a Tile Entity in all situations, but it is not safe to add a Tile Entity to an incompatible block (e.g. Chest Tile Entity on a Furnace block)). 0 disables SafetyMode; this tag will have no effect. 1 will force a Tile Entity's block to be copied with it, overriding blockMode for Tile Entities which are copied. 2 will make Tile Entities only be copied if their block is also copied; in this mode tileEntityMode will be ignored. Note that no mode will prevent a Tile Entity from being removed without changing its block, as this does not create a risk of crashes. The default mode is 0.
    •  entityMode: Describes how to handle Entities for chunks in the output map. Valid values are Dimension Mode Values 0 through 7, where "[data]" is "Entities" and "[default]" is "nothing". If [default] is used by Modes 1, 2, or 7, the output chunk's Entities list will be empty. In Modes 5 or 6, an Entity will be copied as long as no Entity already exists with the same UUID (this makes 5 and 6 behave just like File Modes 2 and 3). It should be noted that Modes 5 and 6 can cause the Minecraft Map Updater to experience a performance drop for larger numbers of entities in the source and update maps.
    •  tileEntityTypeExceptionLists: A list of tileEntityTypeExceptionLists, which allow the updater.dat to define Exceptions for Tile Entities by 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 tileEntityTypeExceptionList.
        •  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: Overrides tileEntityMode for tileEntityTypes in this list.
        •  tileEntitySafetyMode: Overrides tileEntitySafetyMode for tileEntityTypes in this list.
        •  blockMode: Overrides blockMode for tileEntityTypes in this list.
        •  blockDefault: Overrides blockDefault for tileEntityTypes in this list.
        •  blockMetaDefault: Overrides blockMetaDefault for tileEntityTypes in this list.
        •  tileEntityTypes: A list of Tile Entity IDs for which the above Modes and Defaults are to be overridden.
          • A Tile Entity ID (such as "Chest" or "Music") to match for.
    •  entityTypeExceptionLists: A list of entityTypeExceptionLists, which allow the updater.dat to define Exceptions for Entities by 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 entityTypeExceptionList.
        •  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: Overrides entityMode for entityTypes in this list.
        •  entityTypes: A list of Entity IDs for which entityMode is to be overridden.
          • An Entity ID (such as "Villager" or "FallingSand") to match for.
    •  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.
        •  tileEntitySafetyMode: Overrides tileEntitySafetyMode 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. If this list is omitted or empty, all Tile Entities will be matched.
          • 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. If this list is omitted or empty, all Entities will be matched.
          • 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. If any overlap, each chunk will still only be processed once, so essentially the set of chunks affected by these exceptions are the boolean union of all listed chunks and ranges.
    •  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: Overrides biomesMode for regions in this list. Note that all columns overlapping a region will be affected, as biomes are defined per-column rather than per-block.
        •  biomesDefault: Overrides biomesDefault for regions in this list. Note that all columns overlapping a region will be affected, as biomes are defined per-column rather than per-block.
        •  blockMode: Overrides blockMode for regions in this list.
        •  blockDefault: Overrides blockDefault for regions in this list.
        •  blockMetaDefault: Overrides blockMetaDefault for regions in this list.
        •  tileEntityMode: Overrides tileEntityMode for regions in this list.
        •  tileEntitySafetyMode: Overrides tileEntitySafetyMode for regions in this list.
        •  entityMode: Overrides entityMode for regions in this list.
        •  tileEntityTypes: If present and not empty, tileEntityMode will only be overridden for Tile Entities in regions which match IDs in this list. If this list is omitted or empty, all Tile Entities will be matched.
          • 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 regions which match IDs in this list. If this list is omitted or empty, all Entities will be matched.
          • An Entity ID (such as "Villager" or "FallingSand") to match for.
        •  regions: The list of regions for which the above Modes and Defaults are to be overridden. Note that overlapping regions is safe: similar to overlapping chunks in chunkExceptionLists, each block will only actually be processed once and the regions in this list are effectively unified.
          • An individual region.
            •  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: A list of Int tags describing this region's first corner as block coordinates.
              • The x coordinate of this block.
              • The y coordinate of this block.
              • The z coordinate of this block.
            •  posMax: A list of Int tags describing this region's second corner as block coordinates. Same format as posMin, above. Note that no coordinate of posMax needs to actually be greater than those of posMin; they can also be equal or less than.
    •  tileEntityExceptionLists: A list of tileEntityExceptionLists, which allow the updater.dat to define Exceptions for specific Tile Entities by location. 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: Overrides tileEntityMode for tileEntities in this list.
        •  tileEntitySafetyMode: Overrides tileEntitySafetyMode for tileEntities in this list.
        •  blockMode: Overrides blockMode for tileEntities in this list.
        •  blockDefault: Overrides blockDefault for tileEntities in this list.
        •  blockMetaDefault: Overrides blockMetaDefault for tileEntities in this list.
        •  tileEntities: A list of Tile Entities for which the above Modes and Defaults are to be overridden.
          • An individual Tile Entity.
            •  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: A list of Int tags describing this Tile Entity's position as block coordinates. Note that if no Tile Entity exists at these coordinates in the expected map (based on tileEntityMode), blockMode/blockDefault/blockMetaDefault will be ignored.
              • The x coordinate of this block.
              • The y coordinate of this block.
              • The z coordinate of this block.
    •  entityExceptionLists: A list of entityExceptionLists, which allow the updater.dat to define Exceptions for specific Entities by UUID. 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 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: Overrides entityMode for entities in this list.
        •  entities: A list of Entities for which entityMode is to be overridden.
          • An individual Entity.
            •  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: The UUIDMost tag of this entity. This, combined with UUIDLeast, form the entity's Universally Unique IDentifier.
            •  UUIDLeast: The UUIDLeast tag of this entity.

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 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 - Same as Mode 3, but also replace [default] from the source map with [data] from the update map when a chunk exists in both maps.
  • 6 - Same as Mode 4, but also replace [default] from the update map with [data] from the source map when a chunk exists in both maps.
  • 7 - Always set value to [default].

Note that these modes only apply to [data] which is located in chunks which exist in the output map. Data will not be copied if a chunk does not exist at the expected location of the output map. Also note that [default] will not be used at all in Modes 0, 3, and 4. In Modes 5 and 6, [default] can be used as a sort of "mask" for determining what gets copied through.

Some of these values have effects similar to the File Mode Values. Dimension Modes 1 and 2 correspond roughly to File Modes 0 and 1, while Dimension Modes 5, 6, and 7 correspond roughly to File Modes 2, 3, and 4.

ExceptionLists and Priorities

ExceptionLists allow the updater.dat to contain exceptions to the general rules defined by Modes/Defaults. Each ExceptionList contains a set of tags which override the corresponding global tags, and lists the chunks, regions, Tile Entities, or Entities to which these exceptions apply. These lists make it possible to define sections of the world data which are treated differently than the rest, effectively permitting a high level of fine-tuning.

ExceptionLists also introduce a concept of "priority" in the update process, as they can tell the Updater to process the same parts of a world's data multiple times, with different instructions for each pass. This becomes particularly important when chunks or regions overlap each other.

The Updater executes Modes/Defaults in the following order:

  1. Apply global Modes and Defaults, i.e. those which aren't inside any ExceptionLists.
  2. Apply Modes and Defaults within tileEntityTypeExceptionLists.
  3. Apply Modes and Defaults within entityTypeExceptionLists.
  4. Apply Modes and Defaults within chunkExceptionLists.
  5. Apply Modes and Defaults within regionExceptionLists.
  6. Apply Modes and Defaults within tileEntityExceptionLists.
  7. Apply Modes and Defaults within entityExceptionLists.

As a result, ExceptionLists are higher-priority the lower they are in the above list. For example, a tileEntityExceptionList will have the final say in what happens to an individual Tile Entity, even if said Tile Entity was also in a region controlled by a regionExceptionList and a chunk controlled by a chunkExceptionList. Similarly, the global Modes and Defaults are of the lowest priority, and can be overridden by any ExceptionList.

Note that a lower-priority ExceptionList, such as a regionExceptionList, will never override a higher-priority ExceptionList (such as a tileEntityExceptionList). Also, if a Mode or Default in an ExceptionList has been omitted (or, in the case of Modes, set to -1, aka "don't override"), then a lower-priority ExceptionList (or the global Modes/Defaults) can have its say. If a Mode besides chunkMode is set to 0 (whether overridden or globally set), it will base its effects on the highest-priority override of chunkMode available, only using the global chunkMode if no override exists for the given chunk. Similarly, tileEntitySafetyMode and its overrides will base their effects on the highest-priority blockMode and tileEntityMode values available.

Priority within the ExceptionLists is also important. ExceptionLists of a given type are always executed sequentially in the order in which they were defined. Note that priority does not apply to elements within chunks and regions, as they are essentially merged together so all chunks/blocks only need to be processed once. Naturally, of course, priority still applies to chunks in separate chunkExceptionLists and regions in separate regionExceptionLists. Also note that an omitted Default or a Mode of -1 will effectively override previous ExceptionLists of the same type, because it defaults to the lower-priority Default/Mode outside this category of ExceptionList.

Advertisement