Explore the example map, using real (SMP) locations

Example map with oceans

Download .zip file

type,             x,     z,    description,                      owner,       href, icon-index

DesertVillage,  245,   350, "Ghost town"
WitchHut,     -4056, -2487,
PlayerHouse,   -800, -1800, "Dr.Frankenstone's mountain lair", "Dr.Frankenstone", "", 31

The first column specifies the type of location, and must be one of the following:

• Spawn
• PlayerHouse
• PlayerCastle
• PlayerFarm
• PlayerMachine
• PlayerStructure - a generic catch-all block for things players have built that defy any more specific icons.
• EnchantingRoom
• Village
• DesertVillage
• SavannahVillage
• JungleTemple
• DesertTemple
• WitchHut
• NetherFortress
• NetherPortal
• Forest
• FlowerForest
• MushroomIsland
• Horse
• Wolf
• Dragon - a dragon. You can use it to indicate an End portal, the Ender Dragon, or just as "Here be dragons" map decoration.
• SeaMonster
• Ship - a sailing ship. You can use it to decorate the map and indicate ocean.
• FenceOverlay
• IslandOverlay
• Label - a location-type that has no icon by default, you can use it to place plain text onto the map.

The location-type determines the default icon to be drawn at the location, and some have a default href (for example, Village locations link to http://minecraft.gamepedia.com/Village by default). However both the icon and the href of a location-type can be overridden by placing your own values in the appropriate columns.

Given that any location-type can be set to display any icon or href, their purpose is only to make the list easier to read, and to save having to repeatedly type out the details.

The x and z columns should contain the area's coordinates from Minecraft (press F3 in the game to see your coordinates).

Don't worry about decimal places, just round the coordinates to whole numbers.

Description and owner are optional and determine how the map location will be labelled. They don't need to be inside double-quotation marks (") but putting them in quotemarks allows the following:

• You can insert a \n in your text if you want to split the line.
• You can add spaces to pad out the start or end of your label if you want to nudge its position slightly to avoid something else on the map nearby.
  (Note that html collapses multiple spaces into one, so in a wiki you'd have to type out the code   lots of times instead of just hitting the spacebar)
• You can use quotation marks inside a label when it's surrounded by quotation marks. Do this by placing two in a row, for example "My ""Scare quotes""" will be drawn as My "Scare quotes".
  (Note that quotation marks cannot be used in a label unless it's surrounded with quotation marks)
• You can also use commas inside a label when it's surrounded by quotation marks.

Having full control of this markup is why I recommend editing the file with a text editor instead of a spreadsheet or office application.

If you want to make a label invisible, you can surround it with tildes, e.g:

PlayerHouse, 100, 100, Mansion, ~owner~

If you want to force a label to always be shown - even when it will overlap another label or icon, you can surround it with exclamation marks, e.g:

PlayerHouse, 100, 100, !Mansion!, owner

When two labels overlap, locations that are higher in the list will have their label displayed in preference to the label of a location lower in the list. By default, all labels are shown in the most zoomed-in view.

The visibility of labels can also be controlled using the hidelabelsabove and showlabelsbelow settings.

By placing a URL in this column you can make the map location clickable (and the chain-link icon appears when hovering the mouse over the location). Some suggested uses:

• A link to pictures of the location, or information.
• A link to information about the player
• If the location is a portal, then link to a Nether map. The portal in the example map demonstrates this (however, to understand the example portal links you should also read about specifying an href target, below).
• If the location is a player town, then link to a town-scale map (the same way the portal in the example map works).

Clearing a link

If the location-type has a default link but you don't want the location to link to anything, then place a hyphen in the href column to disable the link.

Specifying an href target (Advanced stuff)

Normally this is not necessary and you don't need to know it. However if you decide to use the map inside an iframe then the default href target will become “_parent” — to ensure that clicking on a link will open it in the main window instead of just inside the iframe's area.

But if you want the link to open only inside the iframe's area, for example if the URL was a link such as ?src=example_nether.txt (to load the map with Nether locations), then you will have to specify that “_self” is the target.

To specify both a target and a URL in this column, write the target followed by an underscore followed by the URL. For example if the target is “_self” then the value written in the href column might be _self_http://my-url.com.

Valid targets are “_blank”, “_self”, “_parent”, or “_top”.

There are more icons available than can be specified with the location-type. The icon-index field lets you manually choose the icon to be displayed at the location. The stock icons and their icon-index can be viewed in this Legend Map. You can also add your own.

You'll notice two styles of icons, some are in Minecraft style and others are in the hand-drawn fantasy map style, the idea was to give the impression of Minecraft structures on a fantasy map.

title = Map of Treasure Island
range = 6400

https://buildingwithblocks.info/map173/index.html?src=example.txt&title=Map%20of%20Treasure%20Island&range=1600  

The URL must always^* include the src setting. The src setting cannot be specified in the location-list file.

There are no other required settings.

src tells the map generator where to get the location-list file, or webpage. It can be a relative or absolute URL, and you should encode its value to help keep the map URL nicely formatted.

^* This setting can be hard-coded into the html file if you are hosting it yourself. This avoids requiring it on the URL.

This sets the radius the map will cover, it defaults to 3200 which makes the map 6400 Minecraft blocks wide and 6400 Minecraft blocks high by default.

Tip: Try to make the range a multiple of 32, as this results in the scale at the bottom-left of the map showing nice round numbers. (This is because there are 64 blocks in the map background texture, and the scale is aligned to the texture to help make it easier to estimate distances)

Example - map with range set to 1600

This defaults to "Map of the Overworld", but you probably want to give your map its own name, or have a "Map of the Nether", this option lets you set the title of the map.

You can put HTML in the value for this. If you are specifying the title in the URL remember to encode the value. (You don't need to encode it if you're setting the title from within the location-list file - which is the normal way of doing it)

This defaults to "Use up/down or mousewheel to zoom, drag to scroll", but you might have something more interesting to say, or something you want to link to.

You can put HTML in the value for this. If you are specifying the blurb in the URL remember to encode the value. (You don't need to encode it if you're setting the title from within the location-list file - which is the normal way of doing it)

Setting these values allows you to specify where the map will be centered. The map defaults to 0, 0.

Example - map centered on the spawn point

This can either be set to true or false. If set to false then the crosshairs at the 0,0 position on the map will not be drawn. The default value is true.

This can either be set to true or false. If set to false then the distance scale at the bottom-left of the map will not be drawn. The default value is true.

Example - map with no distance scale

This can either be set to true or false. If set to true then the Minecraft coordinates of a location will be displayed when you hover the mouse over it. The default value is false, because Notch gave Steve a compass, not a GPS ;)

This specifies the "zoom-level" that must be reached before labels are displayed. It defaults to 0, which means labels are always shown.

Example - map with labels disabled on the outermost zoom-level.

This specifies the "zoom-level" at which all labels will be displayed, even if they overlap other labels or icons (labels are normally only displayed when then don't overlap other items in the map). It defaults to 3, which means that at the last zoom-level (3), all labels are shown.

Example - map with all labels shown at all zoom-levels.

If you want to make your own icons you can place them in a .png file, make the .png file available from the same location as the location list file, and use the icons setting to add them to the list of icons available to the map (their icon-indexes will begin at 64).

Icons are square and all icons in a file are the same size, the .png file should be twice the height of the icons (to allow room for the icon and its background). You specify the size of your icons via the height of the .png file, see the iconguide.png file.

The icons setting can be a relative or absolute URL. Remember if you are specifying it from the URL to encode the value to help keep the map URL nicely formatted - you don't need to encode it when you're setting icons from within the location-list file, which is the normal way of doing it.

Use this if you want your map to show oceans^*. See the section on adding oceans for usage examples.

oceansrc tells the map generator where to get the ocean map file (aka ocean mask). It can be a relative or absolute URL, and you should encode its value to help keep the map URL nicely formatted.

If you use oceansrc then you should also read the section Optimizing oceans for faster load times.

^* This setting can be hard-coded into the html file if you are hosting it yourself. This avoids requiring it on the URL.

Selects the style in which to draw oceans on the map. The following themes are available:

• bluecoastline (default)
• bluecoastlinehard
• coastalrelief
• coastalreliefhard
• darkseas
• darkseashard

So currently there are three themes, and with each you can choose whether the pixelation should be hard or more shaded. Hard doesn't look as nice, but is perhaps truer to Minecraft's artistic style. Coastal Relief is quite a hard theme already, so coastalreliefhard looks very similiar.

It's better to specify oceansrc in the URL rather than in the locations list file, because when specified in the locations list it means the page can't begin loading the ocean map file until after the locations list file has finished loading (and it can't start creating the map until the ocean map file has finished loading).

When the ocean map file is provided on the URL, it can be loaded in parallel with the locations list file, so the map can begin as soon as the locations list has loaded.

If you are hosting your own copy of the Ink & Parchment Map, you can also make it faster by specifying the ocean map file inside the html file.

Instead of scrolling around fully zoomed in, the entire map can be printed out as a large poster.

When viewing a map online, there's a small icon at the bottom-left corner of the screen, clicking on that brings up options for make a poster sized image of the map.

Here's the poster I made from our server's map, and how I made it.

You can include maps inside your own webpages by using iframes.

iframe demonstration, with example HTML.

If you're hosting an Ink & Parchment Map page on your own website, and want the src to be built-in rather than specified on the page's URL, you can edit the index.html file to do this.

Find the following line in index.html:

// SetDefaultSrc('default.txt');	  	 	  

Uncomment it (i.e. remove the // from the start of it), and set 'default.txt' to be whatever you want the location-list file to be called (or just name your location-list file default.txt).

If you're hosting an Ink & Parchment Map page on your own website, and want the oceansrc to be built-in rather than specified on the page's URL, you can edit the index.html file to do this.

Find the following lines in index.html:

<div class="resources" style="position: absolute; visibility: hidden;">
	<img id="map-background" src="img/map64.png"/>
	<img id="map-tileset" src="img/glyphs.png"/>
</div>

and add your ocean map image, using the id "oceanmask", for example:

<div class="resources" style="position: absolute; visibility: hidden;">
	<img id="map-background" src="img/map64.png"/>
	<img id="map-tileset" src="img/glyphs.png"/>
	<img id="oceanmask" src="img/example-ocean.png"/>	
</div>

Now oceansrc will no longer be needed.

If you replace index.html in your map URLs with theme2.html, then the ShadedBay background theme will be used instead of the Superflat background theme.

In the future I hope to add more themes, and other people are welcome to contribute. A theme consists of a background image than can compress reasonably small, and a background colour which is displayed under the background image (in case the image doesn't reach all the way to the bottom of the browser window).

Example map, using theme2

Overlays are where a map location overlays more than one icon to represent itself, for example the island icon can be combined with the mushroom icon to show a mushroom island.

Documentatin yet to come...

Until I write this section, you can have a look near the bottom of the legend.txt file - it implements overlays - see the bottom right corner.

You can use the paper texture to estimate distance, as the distance scale is aligned with it and tells you how far 1 block of the paper texture represents.

So those two villages are about 3 squares, or 600 meters (Minecraft blocks) apart.

When the map is fully zoomed in, all the labels will be shown - even if they overlap. Players always build things too close together, so you'll end up wanting to adjusting labels so they don't all overlap, here are some ways to avoid overlaps

• Decreasing the scale of the map by decreasing the range causes locations to be shown further apart.
  
• Caption width can be reduced by splitting it into more than one line.

  e.g. "aeduna's\nreanimated\nvillage"

• Lines can be nudged left or right by adding spaces to the beginning or end of the line.

  (Note that html collapses multiple spaces into one, so if the locations list is a wiki page then you'll have to type out the code   lots of times instead of just hitting the spacebar)
  e.g. "    Fortified\n     village"

• Captions can be nudged down by adding a new-line to beginning of the caption.

  e.g. "\nGhost town"

• Using tildes, the owner part of the caption can be hidden, or the description part, or both parts. Hidden captions can still be viewed with the hover-text.

  e.g. "    Fortified\n     village" , "~Lex86~"

For more information see description format, or the example map where all the examples above were borrowed from.

You can add more/deeper levels of zoom. However there are drawbacks to this so the released version doesn't do it.

Instructions on how to add more zoom levels are given in these two forum posts.

You can use TinyUrl or bit.ly to hide the settings you include in the URL, and to make the URL shorter.

If you use Rei's Minimap and already have locations saved as waypoints, you can extract the location information from the .point files to add to your map. The .point files can be found at:

%appdata%\.minecraft\mods\rei_minimap\

They can be opened with Notepad or a text editor, and each location is stored as line of text in the following format:

name:x:y:z:visible:color