A Cuberite plugin to allow maps to be customized and used like canvases
Go to file
Mike Jagdis 1c99ac1a87 Add support for trackingPosition and unlimitedTracking
Signed-off-by: Mike Jagdis <mjagdis@eris-associates.co.uk>
2024-05-06 10:09:46 +01:00
bin License update, add headers 2024-05-02 10:05:34 +01:00
commands Add support for trackingPosition and unlimitedTracking 2024-05-06 10:09:46 +01:00
images Update custom name handling 2024-05-02 11:28:48 +01:00
lib Add support for GIFs to the "image" command 2024-04-22 14:41:28 +01:00
palettes License update, add headers 2024-05-02 10:05:34 +01:00
config.lua Make palette loadable and add version variants 2024-04-28 18:29:31 +01:00
functions.lua Add support for trackingPosition and unlimitedTracking 2024-05-06 10:09:46 +01:00
Info.lua Add support for trackingPosition and unlimitedTracking 2024-05-06 10:09:46 +01:00
LICENSE License update, add headers 2024-05-02 10:05:34 +01:00
main.lua Add support for trackingPosition and unlimitedTracking 2024-05-06 10:09:46 +01:00
README.md Correct typos: CustomMap should be CustomMaps 2024-05-04 11:18:50 +01:00

Enables images to be placed on maps.

Getting Started

Don't forget to set permissions in Cuberite. Not everyone should be an op!

Configure the palette of map colours to use in the config.lua file (the available palettes can be found in the "palettes/" folder. The default is for Minecraft 1.12 and assumes you will be using 1.12 clients. The older 1.8 and 1.7 clients have fewer map colours and some of the colours are swapped around. Newer 1.17 clients have a few more colours available. After changing the palette you will need to restart the server or run the "reload" console command. You could also use the "/custommap palette ..." command to load a palette temporarily (this does NOT change the config and IS common to all players!)

Now get a map (craft some empty maps, hold them and right click to create an active map) and hold it. CustomMaps commands work on the held map.

Put an image in the images/ folder, say "images/cuberite128.gif"

Apply an image to your map with /custommap image cuberite128. By default CustomMaps uses the top left 128 x 128 (the standard map size) portion of the image. It does NOT scale the image but it will map the colours in the image to the "closest" available in the map palette.

For larger images you can create composite maps and place them in item frames to create wall-art. Create an image that is a multiple of 128 in each direction, say 384 x 384 (3 maps square) and place it in the "images/" folder. Let's say that's "images/cuberite384.gif".

When you apply the image to a map you can specify which piece of the composite you want by specifying x:y before the filename. The top row of a 3 x 3 map composite will be 1:1, 2:1, 3:1, the second row 1:2, 2:2, 3:2 and the last row 1:3, 2:3, 3:3. So holding each of 9 different maps in turn run:

  • /custommap image 1:1 cuberite384
  • /custommap image 2:1 cuberite384
  • /custommap image 3:1 cuberite384
  • /custommap image 1:2 cuberite384
  • ...
  • /custommap image 3:3 cuberite384

When creating composite maps CustomMaps will automatically update each map's custom name with "image [x:y]" so you know which piece is which.

Now place your item frames, add the maps, stand back and admire!


What permissions are not appropriate for ordinary users?

  • custommap.clone - there is nothing to stop a player cloning someone else's map{/%li}
  • custommap.palette - this changes the palette globally so only useful for testing and experimentation{/%li}
  • custommap.scale - this overrides game mechanics as scale would normally be changed by adding paper{/%li}

What is the preferred image format?

GIF is the preferred image format. The PNG support is seriously limited and will probably not work unless you know how to wrangle PNG images.

What is the maximum size for composite maps?

Cuberite currently limits you to 65536 maps per world so that would let you create a composite of 256 x 256 maps. However if some parts of the image are identical you could use /custommap clone <n> to make each of those map items refer to the same underlying map. Using map clones and a repeating pattern there would be no practical limit.

I want to clone a map but it's part of a composite and the custom name hides the map number!

Hold the map item and use /custommap info to find the underlying map number.

Are animated GIFs supported?

No, but it's under consideration. It isn't really clear if this is a good idea or not. Animated GIFs have the potential to generate a LOT of load and traffic on busy servers.

Can I just, y'know, draw on a map?

Yes! Images can be Lua scripts. That's how /custommap image palette works for instance so see images/palette.lua for an example. No libraries of useful drawing functions are currently provided however.

Colour Palettes and Mapping

Maps have a VERY limited range of colours available and you may want to take that into account when creating image. Use, /custommap image palette, on a map to see all the colours available.

When loading images CustomMaps will map colours in the image to the "nearest" map colour. There are several methods of converting colours the "nearest" map colour. These are (in increasing order of computational load):

  • rgb - simple RGB distance
  • rgbw - weighted RGB distance
  • cie76 (or cie) - CIELAB distance using the 1976 formula
  • cie76taxi (or cietaxi) - CIELAB distance using taxicab distance
  • cie94 - CIELAB distance using the 1994 formula

The chosen method can be given as the 4th argument to the image subcommand, e.g. /map image foo.gif cie94. If no method is given the default is cie76taxi.

They are all likely to produce different (sometimes wildly different) results and the best choice is likely to vary between images.

Feel free to implement other methods such as CIEDE2000 or CMC if you want.

You may (optionally) choose to pre-process arbitrary images in order to map them on to the correct palette. For example, you can use the provided .ppm files in palettes/ with NetPBM tools:

pngtopam .../myimage.png | pnmremap -mapfile=palette.ppm -fs | pamtogif > images/myimage.gif

Note that the -fs option to pnmremap enables FloydSteinberg dithering. Given the low resolution and limited colour space of maps this has a tendency to create a nasty speckled appearance unless you are really careful with the choice of colours in your image however it could work well for larger pieces of wall-art intended to be viewed from a distance.

Known Issues

  • Maps have low resolution and a small, restricted colour palette. Contain your expectations appropriately!
  • Because the image loaders are written in pure Lua they are not necessarily fast. In particular, attempting to use large images could cause your Cuberite server's deadlock detector to fire. It is recommended that you scale your images first and quantize true colour images to a reduced set of colours.
  • Cuberite does not currently support maps without decorations. CustomMaps works around this as best it can by setting the map's position to 2^30, 2^30 when you apply an image.

PNG Limitations

  • Indexed colour images are not supported
  • Only filter types 0 and 1 are supported


The following libraries are used by CustomMaps. None has been touched for years so they're simply included here verbatim rather than being added as submodules. Their respective licenses, credits, etc. can be found in their GitHub repositories.



Command Permission Description
/custommap clear custommap.clear Clear the map
/custommap clone custommap.clone Clone a map (set this item's map number)
/custommap fill custommap.fill Fill with solid colour
/custommap image custommap.image Put an image on the map. The image is clipped, NOT scaled to fit!
/custommap info custommap.info Information about the held map
/custommap position custommap.position Set the centre position
/custommap scale custommap.scale Set the map scale


Commands useful for testing

Command Permission Description
/custommap colour custommap.colour Colour tests
/custommap palette custommap.palette Set the palette of colours


Permissions Description Commands Recommended groups
custommap.clear Allows players to clear the held map /custommap clear Default
custommap.clone Allows players to clone an arbitrary map number to the held map /custommap clone Admin, Operator, Everything
custommap.colour Allows players to test colour conversions/matching /custommap colour Developer
custommap.fill Allows players to fill the held map with a solid colour /custommap fill Default
custommap.image Allows players to put an image on the held map /custommap image Default
custommap.info Allows players to see information about the held map /custommap info Default
custommap.palette Allows players to change the global palette /custommap palette Developer
custommap.position Allows players to set the centre position of the held map /custommap position Default
custommap.scale Allows players to change the scale of the held map /custommap scale Admin, Everything