ClassicWorld file format

From wiki.vg
Revision as of 03:24, 4 October 2013 by F (talk | contribs) (→‎Notes)
Jump to navigation Jump to search

ClassicWorld World Format is a level format devised by tyteen4a03 with input from fragmer for all Classic Custom Servers to use. Originally designed for cloudBox, it is designed in order for every servers that implement Classic Protocol Extension to also be able to share world formats. This will allow server owners to switch solutions easily according to their needs, and ensure that CPE features will be well-implemented in all server softwares.

Specification

Basic Structure

TAG_Compound("ClassicWorld"): 14 entries {
  TAG_Byte("LevelVersion")
  TAG_String("Name")
  TAG_Byte_Array("UUID")
  TAG_Short("X")
  TAG_Short("Y")
  TAG_Short("Z")
  TAG_Compound("CreatedBy"): 2 entries {
    TAG_String("Service")
    TAG_String("Username")
  }
  TAG_Compound("MapGenerator"): 2 entries {
    TAG_String("Software")
    TAG_String("MapGeneratorName")
  }
  TAG_Long("TimeCreated")
  TAG_Long("LastAccessed")
  TAG_Long("LastModified")
  TAG_Compound("Spawn"): 5 entries {
    TAG_Short("X")
    TAG_Short("Y")
    TAG_Short("Z")
    TAG_Byte("H")
    TAG_Byte("P")
  }
  TAG_Byte_Array("BlockArray")
  TAG_Compound("Metadata") {}
}

Notes

  • LevelVersion is a constant, currently at 1
  • Name should be limited to 64 characters in length, and contain only characters that can be displayed in Minecraft.
  • UUID is a unique 128-bit identifier for this map (for example a GUID), saved as a 16-byte array.
  • X is the width (first horizontal dimension) of the map.
  • Y is the height (vertical dimension) of the map.
  • Z is the length (second horizontal dimension) of the map.
  • CreatedBy identifies the creator of this map. Optional.
    • Username is the name of a player.
    • Service can be "Minecraft" (for Minecraft.net usernames) or "ClassiCube" (for ClassiCube.net usernames).
  • MapGenerator contains information related to map generation. Optional.
    • Software is the name of software that originally generated this map (e.g. "cloudBox" or "fCraft").
    • MapGeneratorName is the name of a specific generation method used by the software (e.g. "Realistic" or "Flat").
  • TimeCreated is a UTC Unix timestamp that's set when the map is originally generated. Optional.
  • LastModified is a UTC Unix timestamp that's set when the map's blocks are modified. Changes to spawn point or metadata should not affect this date. Optional.
  • LastAccessed is a UTC Unix timestamp that's set when the map is accessed by any player. Optional.
  • Spawn compound tag defines the point where players spawn on the map. All coordinates are in player-position units (32 units per block).
    • X is the first horizontal component of player's position.
    • Y is the vertical component of player's position.
    • Z is the second horizontal component of player's position.
    • H is the heading (yew) component of player's orientation.
    • P is the pitch component of player's orientation.
  • BlockArray contains the actual block data, 1 byte per block. Same packing order as in LevelDataChunk packets.
  • Metadata contains all kinds of software- and plugin-specific data.

Metadata entry

The Metadata compound tag must contain zero or more named Compound tags, each named after a specific software that produced them. Each of those compound tags should contain zero or more named Compound. The contents of those tags are implementation-specific.

TAG_Compound("(SomeSoftware)") {
  TAG_Compound("(OneSection)") {
    (implementation-specific contents)
  }
  TAG_Compound("(AnotherSection)") {
    (implementation-specific contents)
  }
}
TAG_Compound("(OtherSoftware)") {
  TAG_Compound("(Section)") {
    (implementation-specific contents)
  }
}

Classic Protocol Extension metadata

Metadata name "CPE" is reserved for Classic Protocol Extension data, and has standardized contents. Any or all of the below sections may be present, each corresponding to a CPE extension. Each section contains an Int tag named ExtensionVersion.

ClickDistance

TAG_Compound("ClickDistance"): 2 entries {
  TAG_Int("ExtensionVersion")
  TAG_Short("Distance")
}

CustomBlocks

TAG_Compound("CustomBlocks"): 3 entries {
  TAG_Int("ExtensionVersion")
  TAG_Short("SupportLevel")
  TAG_Byte_Array("Fallback"): [256 bytes]
}

The purpose of the Fallback array is to allow servers with lower SupportLevel to load maps created by servers with higher SupportLevel. In such cases, any unsupported block IDs can be substituted using Fallback mapping. For instance, when a [hypothetical] block ID 200 is encountered, loading software should substitute it with the value of Fallback[200].

EnvColors

TAG_Compound("EnvColors"): 6 entries {
  TAG_Int("ExtensionVersion")
  TAG_Compound("Sky"): 3 entries {
    TAG_Short("R")
    TAG_Short("G")
    TAG_Short("B")
  }
  TAG_Compound("Cloud"): 3 entries {
    TAG_Short("R")
    TAG_Short("G")
    TAG_Short("B")
  }
  TAG_Compound("Fog"): 3 entries {
    TAG_Short("R")
    TAG_Short("G")
    TAG_Short("B")
  }
  TAG_Compound("Ambient"): 3 entries {
    TAG_Short("R")
    TAG_Short("G")
    TAG_Short("B")
  }
  TAG_Compound("Sunlight"): 3 entries {
    TAG_Short("R")
    TAG_Short("G")
    TAG_Short("B")
  }
}

EnvMapAppearance

TAG_Compound("EnvMapAppearance"): 5 entries {
  TAG_Int("ExtensionVersion")
  TAG_String("TextureURL")
  TAG_Byte("SideBlock")
  TAG_Byte("EdgeBlock")
  TAG_Short("SideLevel")
}

Support

These custom servers plan to add support for CW World Format: cloudBox, fCraft