How Galacticraft background mapping works

gistfile1.txt

There are three levels of map:

A.  An overworld map covering approximately 48000 x 24000 blocks, centered on 0,0

- scale: 1 map data point represents a 64x64 block area
- this produces a 768 x 376 data point map - visually the image of that is made 1536 x 768 pixels to give 4 pixels per map data point
- the reason for using 4 pixels per data point that is some map biomes e.g. forest are drawn with two colours, and so 4 pixels per map data point allows both colours to be used
- the map size is chosen because on most servers players don't travel much further than 12000 blocks from spawn (sometimes a WorldBorder plugin limits them to even less than that)
- also this size is good for making something which "looks" like a world map, with several continents and several large bodies of water
- (a smaller map would maybe only cover 1 continent, a larger map would show that Minecraft has endless repeating continents)
- the 2:1 aspect ratio is simply so that this will look good on a wide display screen
- could maybe reduce this to 24000 x 12000 blocks to match (B) below
- an average modern PC takes around 15 minutes to generate this complete map, starting on server start

B.  An overworld map covering approximately 24000 x 6000 blocks, centered on 0,0

- scale: 1 data point represents a 128x128 block area
- this produces a 192 x 48 data point map
- this is then abstracted and averaged to a 48 x 12 texture, using nearest colour matching to the standard Overworld image
- this produces a seed-specific planet texture for the Overworld which has some resemblence to the actual overworld map - maybe recognisable continents
- there is no point in increasing this to cover a larger block area, Minecraft maps become homogenous when zoomed out very far (50/50 water/land in an endless repeating pattern)
- an average modern PC takes around 10 seconds to generate this map, starting on server world start

C.  A local map covering approximately 700 x 700 blocks, centered on a given block location
- scale: 1 map data point represents a 2x2 block area
- this produces a 352 x 352 pixel image which is recognisably the local area, but shows a wider area than any mapping plugin
- behind the scenes this map is constructed using 176x176 tiles of map on a fixed grid.  Depending on centre point location, any given 352x352 image could cover up to 9 tiles
- an average modern PC takes around 2 seconds to generate each tile
- building the tiles is triggered by placing a block which requests them - currently a Display Screen but it can also be a Launch Pad
- therefore on a reasonable system this map should be fully built during the 20 second rocket launch countdown sequence, even if a player builds a new Launch Pad and immediately launches a rocket

In all three cases, the map is created on the *server* and the chunks are not generated.  There is no impact at all on the vanilla game, this map generation is invisible to the vanilla game.
Building the maps is CPU intensive, it will max out one or two cores on a CPU (depending on system and JVM).  The thread priority is set to 1 less than Normal - that's a thread priority of 4 on a Windows system.

The server stores the maps it has already built in the world save folder, subfolder: galacticraft/overworldMap
The maps are specific to each world (they depend on the world seed).  Once generated, unless somebody tampered with the save folder, they will persist from server session to server session.
(If a map file is not present, the server will attempt - once each server session - to create any map file it needs.)
There is no index or other persistent data structure pointing to these map files.  The server simply looks for the files, uses them if they are already there, and tries to create them otherwise.
It's around 64kB per tile for the local map, so a busy server could maybe have 20-30MB of these map tiles or more.

The server transmits the raw map data to clients on client request (queued in MapUtil.clientrequests).
The server can also push map data to clients, depending on game/tile logic.
Clients store the map data received as files in the .minecraft folder, subfolder assets/temp.  This subfolder is cleared on each new client session.
[TODO: name that folder galacticraft!]
The client constructs the actual map images (textures) using the raw map data it has received.
Therefore the client constructs:
A. a texture representing the whole world map (currently for beta preview purposes, this is simply saved on disk as a .jpeg)
B. a 192x48 pixel texture for rendering the Overworld as a planet: like other planet textures, this renders the original texture at a ratio of 1:4, so the original texture only has 48x12 different colour blocks, but it will render better in Minecraft if it has 4x4 pixels for each block of colour instead of 1 pixel
C. multiple 352x352 pixel textures, whenever rendering local maps at different locations

The mapping is based solely on biome and height data.  Height data is relevant to identifying bodies of water: the vanilla game will put ponds, lakes and rivers whereever the height of generated terrain is less than 63 (not in deserts, though...)
Blocks or even large structures built by the player will therefore *not* show up on maps
Trees and other map 'decorations' also do not show up.  The map rendering simulates trees, in forested biomes, by using two different pixel colours stippled randomly.
The map colours use Minecraft biome colours with some adjustments to give a more natural looking map - essentially the colour should reflect the most common blocks in the biome, when seen from above
(so Roofed Forest is rather dark, for example, because it has dark leaves).  See MapUtil.setupColours()
It might be possible to customise the colours using a config in future - no current provision for this.

TODO:  Test with Biomes O'Plenty, ExtraBiomes, Natura, and other major biome adding mods
In geneneral we have *not* coded adjustments for the biome colours given by those mods, and their colours are likely to be unnatural