Rendermode Options Guide

(currently, rendermode options are only supported in agrif's rendermode-options branch)

Rendermode options are a new way of changing how existing render modes work, by passing in values at startup. For example, you can change how dark the 'night' mode is, or enable lighting in 'cave' mode.

Options and Rendermode Inheritance

Each mode will accept its own options, as well as the options for parent modes; for example the 'night' mode will also accept options listed for 'lighting' and 'normal'. Also, if you set an option on a mode, all its children will also have that option set. So, setting the 'edge_opacity' option on 'normal' will also set it on 'lighting' and 'night'.

Basically, each mode inherits available options and set options from its parent.

Eventually the --list-rendermodes option will show parent relationships. Right now, it looks something like this:

• normal
  • lighting
    • night
  • cave
• overlay
  • spawn
  • mineral

How to Set Options

Available options for each mode are listed below, but once you know what to set you'll have to edit settings.py to set them. Here's an example:

rendermode_options = {
    'lighting': {
        'edge_opacity': 0.5,
    },

    'cave': {
        'lighting': True,
        'depth_tinting': False,
    },
}

As you can see, each entry in rendermode_options starts with the mode name you want to apply the options to, then a dictionary containing each option. So in this example, 'lighting' mode has 'edge_opacity' set to 0.5, and 'cave' mode has 'lighting' turned on and 'depth_tinting' turned off.

Defining Custom Rendermodes

Sometimes, you want to render two map layers with the same mode, but with two different sets of options. For example, you way want to render a cave mode with depth tinting, and another cave mode with lighting and no depth tinting. In this case, you will want to define a 'custom' render mode that inherits from 'cave' and uses the options you want. For example:

custom_rendermodes = {
    'cave-lighting': {
        'parent': 'cave',
        'description': 'cave mode, with lighting',
        'options': {
            'depth_tinting': False,
            'lighting': True,
        }
    },
}

rendermode = ['cave', 'cave-lighting']

Each entry in custom_rendermodes starts with the mode name, and is followed by a dictionary of mode information, such as the parent mode and description (for your reference), as well as the options to apply.

Every custom rendermode you define is on exactly equal footing with the built-in modes: you can put them in the rendermode list to render them, you can inherit from them in other custom modes, and you can even add options to them with rendermode_options, though that's a little redundant.

Option Listing

Soon there should be a way to pull out supported options from Overviewer directly, but for right now, here's a reference of currently supported options.

normal

• edge_opacity - darkness of the edge lines, from 0.0 to 1.0 (default: 0.15)
• min_depth - lowest level of blocks to render (default: 0)
• max_depth - highest level of blocks to render (default: 127)
• height_fading - darken or lighten blocks based on height (default: False)

lighting

all the options available in 'normal', and...

• shade_strength - how dark to make the shadows, from 0.0 to 1.0 (default: 1.0)

night

'night' mode has no options of its own, but it inherits options from 'lighting'.

cave

all the options available in 'normal', and...

• depth_tinting - tint caves based on how deep they are (default: True)
• only_lit - only render lit caves (default: False)
• lighting - render caves with lighting enabled (default: False)

mineral

The mineral overlay supports one option, minerals, that has a fairly complicated format. minerals must be a list of (blockid, (r, g, b)) tuples that tell the mineral overlay what blocks to look for. Whenever a block with that block id is found underground, the surface is colored with the given color.

See the settings.py example below for an example usage of minerals.

Example settings.py

This settings.py will render three layers: a normal 'lighting' layer, a 'cave' layer restricted to between levels 40 and 55 to show off a hypothetical subway system, and a 'mineral' layer that has been modified to show underground rail tracks instead of ore.

rendermode = ['lighting', 'subway-cave', 'subway-overlay']

custom_rendermodes = {
    'subway-cave' : {'parent' : 'cave', 
                     'description' : 'a subway map, based on the cave rendermode',
                     'options' : {
                         'depth_tinting' : False,
                         'lighting' : True,
                         'only_lit' : True,
                         'min_depth' : 40,
                         'max_depth' : 55,
                     }
    },
    'subway-overlay' : {'parent' : 'mineral',
                        'description' : 'an overlay showing the location of minecart tracks',
                        'options' : {'minerals' : [
                            (27, (255, 234, 0)),
                            (28, (255, 234, 0)),
                            (66, (255, 234, 0)),
                        ]}
    },
}

rendermode_options = {
    'lighting' : {'edge_opacity' : 0.5},
#    'night' : {'shade_strength' : 0.5},
#    'cave' : {'only_lit' : True, 'lighting' : True, 'depth_tinting' : False},
}