A fully comprehensive tutorial for webbukkit/dynmap to render the nether roof in Minecraft

Rendering-the-Nether-Roof.md

Initial Setup of the Nether Roof Map

1. Assuming dynmap is already initialized and the folder structure has been generated during a first-time run, <Spigot_Server>/plugins/dynmap/custom-perspectives.txt should exist.
2. Open custom-perspectives.txt in a text editor.
3. In this file below the line perspectives: add the following lines of text.

  - class: org.dynmap.hdmap.IsoHDPerspective
    name: nether_top_map_lowres
    maximumheight: 256
    minimumheight: 129
    inclination: 90
    scale: 4
    azimuth: 180

4. If SpigotMC is not running, start it and wait for everything to load, remaining in the server console. If SpigotMC is running, you can re-attach to the console using whatever method you have set up.
5. Run dynmap pause all to halt all live updates to the map.

[12:49:49] [Server thread/INFO]: [dynmap] Full/radius render pause set to true
[12:49:49] [Server thread/INFO]: [dynmap] Update render pause set to true
[12:49:49] [Server thread/INFO]: Full/Radius renders are PAUSED
[12:49:49] [Server thread/INFO]: Update renders are PAUSED
[12:49:49] [Server thread/INFO]: Zoom out processing is ACTIVE

6. If it does not already exist, add a new nether roof map with the command dmap mapadd world_nether:nether_roof title:"The Roof" perspective:nether_top_map_lowres.
7. If it DOES already exist, you can change the perspective of an existing map with dmap mapset world_nether:nether_roof perspective:nether_top_map_lowres.

[12:50:25] [Server thread/INFO]: Refreshing configuration for world world_nether
[12:50:25] [Server thread/INFO]: [dynmap] Loaded 4 maps of world 'world_nether'.
[12:50:25] [Server thread/INFO]: If you are done editing map data, run '/dynmap pause none' to resume rendering

8. Run dynmap pause none.

[12:51:37] [Server thread/INFO]: [dynmap] Full/radius render pause set to false
[12:51:37] [Server thread/INFO]: [dynmap] Update render pause set to false
[12:51:37] [Server thread/INFO]: Full/Radius renders are ACTIVE
[12:51:37] [Server thread/INFO]: Update renders are ACTIVE
[12:51:37] [Server thread/INFO]: Zoom out processing is ACTIVE

9. Run dynmap cancelrender world_nether.

[12:54:27] [Server thread/INFO]: Cancelled render for 'world_nether'

(This could also be blank, meaning no fullrender was in progress.)

10. Run dynmap fullrender world_nether:nether_roof.

[12:56:54] [Server thread/INFO]: Full render starting on world 'world_nether'...
[12:58:34] [Dynmap Render Thread/INFO]: Full render of map 'nether_roof' of 'world_nether' in progress - 100 tiles rendered (50.30 msec/tile, 18.75 msec per render)
[13:00:13] [Dynmap Render Thread/INFO]: Full render of map 'nether_roof' of 'world_nether' in progress - 200 tiles rendered (53.48 msec/tile, 16.67 msec per render)
[13:01:54] [Dynmap Render Thread/INFO]: Full render of map 'nether_roof' of 'world_nether' in progress - 300 tiles rendered (49.51 msec/tile, 15.78 msec per render)
[13:03:34] [Dynmap Render Thread/INFO]: Full render of map 'nether_roof' of 'world_nether' in progress - 400 tiles rendered (45.63 msec/tile, 15.27 msec per render)

11. Note in the browser that the new map will not be assigned an icon in the right-hand map list, and as the new perspective starts at y=129, the nether roof texture will not be included. However, the spawn icon should be displayed at (0,0). As I have a standard ilmango zombie pigman gold farm on the nether roof, that is displayed near spawn as well.

Giving the new map an icon

1. In the server console run dynmap pause all
2. Run the command dmap mapset world_nether:nether_roof icon:images/sign_warp.png
3. Return to the browser and note the updated icon now displays something like a white chat bubble with a black "><":
4. Icons are stored in <Spigot_Server>/plugins/dynmap/web/images.
5. You can create or find 16x16px custom PNG images, copying them into this folder for use within the server console.
6. To load the newly copied PNG image, repeat step 2, changing the icon:images/sign_warp.png bit to icon:images/<filename>.png

Example

I threw together this one called which blends the bedrock block texture and the nether_portal block texture, and copied it in as <Spigot_Server>/plugins/dynmap/web/images/bedrock_portal.png.

Then I ran the command dmap mapset world_nether:nether_roof icon:images/bedrock_portal.png, which I'm quite happy with!

5. Finally, run dynmap pause none to resume the fullrender or active rendering process. If a full render is not in progress, the map will only update when a player loads the nether roof chunks and remains there for some minimum amount of time.

Rendering the bedrock layer

(Assuming you've already done everything previously mentioned)

1. In the server console run dynmap pause all.
2. In the file manager, open <Spigot_Server>/plugins/dynmap/custom-perspectives.txt in a text editor.
3. Edit the line minimumheight: 129, changing it to minimumheight: 128
4. Save and close the text editor.
5. In the server console run reload and wait for all server and plugin configurations to be re-read from their respective files.
6. Run dynmap pause none.
7. Run dynmap cancelrender world_nether. You'll either see Cancelled render for 'world_nether' if a fullrender was in progress, or nothing.
8. Run dynmap fullrender world_nether:nether_roof and wait a few minutes for the first few tiles to render in the browser. If all is well, whatever was displayed before should now be overwritten with a dark grey houndstoothy bedrock texture.

Lighting (June 29, 2020)

With Dynmap 3.1 beta released for 1.16 (Nether) I am watching the Nether biome updates roll in gradually as I re-run a full render of world_nether:flat.

And as I wait, I realized that in the time I wrote this to now my brothers and I also defeated the dragon and and started raiding End cities at which point I realized that its default lighting profile "brightnight" is extremely useful in finding cities and End gateways as the diamond flaring of end rods and torches really help when scanning a 10k x 10k map.

So I decided perhaps since the nether roof is most often used for portal hubs, I could change the lighting profile of world_nether:nether_roof to brightnight as well.

1. dynmap pause all
2. dmap mapset world_nether:nether_roof lighting:brightnight
3. dynmap pause none
4. dynmap fullrender world_nether:nether_roof

And the result is quite stupendous!

Dark Red Background (November 27, 2020)

Someone in the comments asked about how to add the red background you see in the world_nether:flat and world_nether:surface maps. Turns out this is all to do with some undocumented and unautomated dynmap features that live in the very hard-to-find HD Map Configuration help file.

1. Open <SpigotMC Directory>/plugins/dynmap/worlds.txt.
2. Scroll down to world_nether and in the maps section, search for all separate map definitions.
3. Note that by default, the "flat" and "surface" maps for world_nether have a background property of #300806.
4. Copy this line into all applicable map sections. For our purposes, the nether_roof will look something like this:

-   name: world_nether
    title: The Nether
    enabled: true
    extrazoomout: 2
    maps:
    ...
    ...
    -   class: org.dynmap.hdmap.HDMap
        name: nether_roof
        title: The Roof is on Fire!
        icon: images/bedrock_portal.png
        prefix: nether_roof
        perspective: nether_top_map_lowres
        ...
        ...
        background: '#300806'
        append_to_world: ''

5. Reload the server and watch the nether roof map refresh into new, smoldering red gloriousness!

Additional Options

rgba() with transparency settings instead of the #RRGGBB format actually works!

In worlds.txt, replace background:'#300806' with background: 'rgba(48,8,6,1.0)' and reload.

Additionally I did some digging into the .js files and found that dynmap may be simply translating the background options of map definitions here into raw CSS. In this case, I tried another thing:

background: 'url("images/book.png")'

YIKES!! What are we seeing!?

Also w3schools' CSS3 background documentation describes a method of embedding not only a background image, but also its positioning, tiling, repeat, and additionally a backup color into the same line.

background: 'lightblue url("images/book.png") fixed'

As docm77 is fond of saying, "Lawd a'mercy..."

We can also replace 'lightblue' with an RGB definition in #RGB, #RRGGBB, and rgba() formats.

background: 'rgba(48,8,6,0.5) url("images/book.png") fixed'

Not so spectactular, and the image is layered on top of the background color, so the alpha channel does not darken it any

This simply means that to properly make a GOOD background image, choosing something less busy and/or manually darkening it in photo editing software it may be preferrable.

@DarkFenix139 Just compared with my own, and the only difference I can see is that I'm using stdtexture as my shader, rather than default. But I can't see that being a problem either..

Otherwise, it looks perfectly reasonable to me!

@depwl9992, Very very very strange, but now everything is fine...

Any chance you could add instructions for adding a 3D/Surface view for nether roof maps?

would also very much like a 3D/Surface onceover

For those asking how to get a 3D/Surface view, simply change "azimuth" to "135" and "inclination" to "30". This will make the map have the same camera angle as Overworld_Surface.