1 files changed, 38 insertions, 7 deletions

diff --git a/src/BlockTypePalette.h b/src/BlockTypePalette.h
index 2d0985f08..3b6cb9ec0 100644
--- a/src/BlockTypePalette.h
+++ b/src/BlockTypePalette.h
@@ -15,7 +15,25 @@ The object itself provides no thread safety, users of this class need to handle
 Note that the palette itself doesn't support erasing;
 to erase, create a new instance and re-add only the wanted items.
 
-Internally, the object uses two synced maps, one for each translation direction. */
+Internally, the object uses two synced maps, one for each translation direction.
+
+The palette can be loaded from a string (file). The loader supports either the blocks.json file exported by
+the vanilla server itself (https://wiki.vg/Data_Generators), or a processed text file generated by
+our tool $/Tools/BlockTypePaletteGenerator/, or a hand-written text file describing the upgrade from
+1.12 BlockType + BlockMeta to 1.13 string representations.
+The text file is a TSV (tab-separated values), which basically means the data is generally structured as
+<value1><tab><value2><tab><value3><tab>...<valueN><eol>, where eol is the platform's CR / CRLF / LF lineend.
+The file starts with a single value on the first line, "BlockTypePalette" or "UpgradeBlockTypePalette", which
+is used to detect the file format. The following lines are "headers", simple <key><tab><value><eol> entries
+that contain the metadata about the file. "FileVersion" is a compulsory key, "CommonPrefix" is supported, others
+are ignored.
+The headers are followed by an empty line (that signalizes the end of headers) and then the actual data.
+For regular BlockTypePalette TSV file of version 1, the data is in the format:
+<index><tab><blockTypeName><tab><state1Name><tab><state1Value><tab><state2Name> ... <eol>
+For the UpgradeBlockTypePalette TSV file of version 1, the data is in the format:
+<blockType><tab><blockMeta><tab><blockTypeName><tab><state1Name><tab><state1Value><tab><state2Name> ... <eol>
+If a CommonPrefix header is present, its value is pre-pended to each blockTypeName loaded (thus allowing
+the file to be overall smaller). */
 class BlockTypePalette
 {
 public:
@@ -78,10 +96,11 @@ public:
 	std::map<UInt32, UInt32> createTransformMapWithFallback(const BlockTypePalette & aFrom, UInt32 aFallbackIndex) const;
 
 	/** Loads the palette from the string representation.
-	Throws a LoadFailedException if the loading fails hard (bad string format).
+	Throws a LoadFailedException if the loading fails hard (bad string format);
+	but still a part of the data may already be loaded at that point.
 	If the string specifies duplicate entries (either to already existing entries, or to itself),
 	the duplicates replace the current values silently (this allows us to chain multiple files as "overrides".
-	Currently handles only JSON representation, expected to handle also Lua representation in the future. */
+	Auto-detects the string format (json / tsv, normal / upgrade palette) and calls the appropriate load function. */
 	void loadFromString(const AString & aString);
 
 
@@ -100,9 +119,21 @@ protected:
 	UInt32 mMaxIndex;
 
 
-	/** Loads the palette from the JSON representation.
-	Throws a LoadFailedException if the loading fails hard (bad string format).
-	If the string specifies duplicate entries (either to already existing entries, or to itself),
-	the duplicates replace the current values silently (this allows us to chain multiple files as "overrides". */
+	/** Loads the palette from the JSON representation, https://wiki.vg/Data_Generators
+	Throws a LoadFailedException if the loading fails hard (bad string format);
+	but still a part of the data may already be loaded at that point.
+	See also: loadFromString(). */
 	void loadFromJsonString(const AString & aJsonPalette);
+
+	/** Loads the palette from the regular or upgrade TSV representation.
+	aIsUpgrade specifies whether the format is an upgrade TSV (true) or a regular one (false)
+	Throws a LoadFailedException if the loading fails hard (bad string format);
+	but still a part of the data may already be loaded at that point.
+	See also: loadFromString(). */
+	void loadFromTsv(const AString & aTsvPalette, bool aIsUpgrade);
+
+	/** Adds a mapping between the numeric and stringular representation into both maps,
+	updates the mMaxIndex, if appropriate.
+	Silently overwrites any previous mapping for the ID, if present, but keeps the old string->id mapping. */
+	void addMapping(UInt32 aID, const AString & aBlockTypeName, const BlockState & aBlockState);
 };