Skip to content

Creating a Tectonicus config file

Steven Koeven edited this page Jun 15, 2021 · 18 revisions

When running from the command line the preferred way to configure Tectonicus is to use a config file. For the most up-to-date information, see the example config file here: https://github.com/tectonicus/tectonicus/blob/master/Docs/fullConfig.xml

Tectonicus config files are stored as XML. If you are unfamiliar with XML, then see this basic tutorial: http://www.w3schools.com/xml/xml_syntax.asp

Run Tectonicus by executing the tectonicus script in the bin folder and passing it an xml config file. For example:

bin\tectonicus -c simpleConfig.xml

If you're new then it's easiest to just take the simpleConfig.xml file and modify the file paths so they point to your world folder and output folder.

Remember that config options are case sensitive!

Overview

The basic structure of the config file looks like:

<tectonicus version="2">

	<config />    <!-- general config options go here -->

	<rasteriser />    <!-- rasteriser options go here -->

	<map> <!-- map specific options go here -->
		
                <!-- map marker options go here -->

                <subset>
                    <!-- subset options go here -->
                </subset>

		<layer />    <!-- layer options go here -->
        </map>

	<tweaks />    <!-- tweaks options go here -->

  	<debug />    <!-- debug options go here -->

	<!-- additional maps go here -->

</tectonicus>

These can be in any order. Only 'layer' and 'map' may be present more than once, these nodes will be covered later.

Example configuration file

Here’s a minimal config file for creating a single map:

<?xml version="1.0"?>
<tectonicus version="2">
	<config outputDir="myoutputdirectory"/>

	<map name="mymapname" worldDir="/path/to/level.dat">
		<layer name="Day" lighting="day"/>
	</map>
</tectonicus>

Configuration file defined

Config node

<config mode = "cmd"
	outputDir = "D:\Tectonicus\Map Render"
	outputHtmlName = "Xoozo_Map.html"
        defaultSkin="steve"
	minecraftJar = "filepath to minecraft.jar"
	texturePack = "/Users/xxx/Texture pack.jar"
	useOldColorPalette = "false"
        useProgrammerArt = "false"
        numZoomLevels = "8"
        singlePlayerName = ""
	numDownsampleThreads = "2"
	eraseOutputDir = "false"
	useCache = "true"
	cacheDir = "D:\Minecraft\Tectonicus\Map Render\Cache"
	logFile = "D:\Minecraft\Tectonicus\Map Render\Log.txt"
        loggingLevel = "DEBUG"
        spawnInitiallyVisible = "true"
        playersInitiallyVisible = "true"
        bedsInitiallyVisible = "true"
        signsInitiallyVisible = "true"
        portalsInitiallyVisible = "true"
        viewsInitiallyVisible = "true" />

This controls the basic setup you need to change for your computer. All attributes are optional.

Option name Description Possible values Default
mode controls what mode Tectonicus runs in 'cmd' for command line mode
'players' to just update player information (note Minecraft only reliably updates player information when you log out)
'interactive' for secret interactive mode
'views' to update views only
cmd
outputDir specifies the output folder to put the generated files and folders in. Will be created if it doesn't exist. a directory path Defaults to the directory that Tectonicus is being run from.
outputHtmlName the name for the generated html file a file name map.html
defaultSkin the skin to use for creating the icon for players with no custom skin texture pack file path or local file path steve
minecraftJar specifies the path to your client minecraft.jar which Tectonicus reads (not runs) for resources such as texture packs. a file path this will be autodetected if not set and you have played minecraft on the computer you are using
texturePack specify a path to a minecraft texture pack if you want to use textures other than the default minecraft ones. HD texture packs can be used. a file path none (uses regular minecraft textures)
useOldColorPalette set to true if you want to use the old color palette for Banners and Beacon beams 'true' or 'false' false
useProgrammerArt set to true to use the Programmer Art texture pack 'true' or 'false' false
numDownsampleThreads choose how many threads (cpu cores) to use when creating the layer images a number defaults to your computer's number of cpu cores
eraseOutputDir if set, will delete the *entire* contents of the output dir. Useful if you want to force Tectonicus to start from scratch 'true' or 'false' false
useCache turn this on and Tectonicus will attempt to use the cache information so it only draws the bits of the map that have changed since last time 'true' or 'false' true
cacheDir specify a path to where the tectonicus cache file will be stored. usually this should be a folder in the output directory a directory path outputDir/Cache
logFile specifies an alternate destination file for the log file a complete file path 'TectonicusLog.txt' in the current directory
loggingLevel specify the level of logging output options in order from least verbose to most verbose: OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL DEBUG
spawnInitiallyVisible specifies whether the spawn marker is already turned on when the final render is opened or not 'true' or 'false' true
playersInitiallyVisible specifies whether players are already turned on when the final render is opened or not 'true' or 'false' true
bedsInitiallyVisible specifies whether beds are already turned on when the final render is opened or not 'true' or 'false' true
signsInitiallyVisible specifies whether signs are already turned on when the final render is opened or not 'true' or 'false' true
portalsInitiallyVisible specifies whether portals are already turned on when the final render is opened or not 'true' or 'false' true
viewsInitiallyVisible specifies whether views are already turned on when the final render is opened or not 'true' or 'false' true

Rasteriser node (Optional)

<rasteriser type = "lwjgl"
            colourDepth = "32"
	    alphaBits = "8"
	    numSamples = "4"
	    tileSize = "512"
            useEGL = "false" />

These values are used to configure your graphics card when drawing the map. All attributes are optional.

Option name Description Possible values Default
type the rasteriser type to use. 'lwjgl' for the OpenGL / LWJGL renderer (currently the only option) 'lwjgl'
colourDepth colour depth to perform rendering in 16, 24 or 32 32
alphaBits number of alpha bits to use when rendering. Set this to zero if you have display initialisation problems. 0 or 8 8
numSamples the number of antialiasing samples to use. Use 0 or 1 to disable antialiasing (may help compatibility) 0, 1, 2, 4, 8 or 16 4
tileSize the size of the output image tiles, in pixels a number between 64 and 1024 512
useEGL whether to use EGL to create an OpenGL context, useful for rendering on headless machines 'true' or 'false' false

Map node

<!-- Maps to process (must have at least one map) -->
<map name=""
     worldDir="/Users/xxxx/AppData/Roaming/.minecraft/saves/My World" <!-- REQUIRED -->
     dimension="terra / nether / end"
     closestZoomSize="12"
     cameraAngle="45"
     cameraElevation="45"
     north="-z / +z / -x / +x" <!-- compass rose north direction -->
     compassRose="" <!-- custom image path --> >

</map>

Only the 'worldDir' attribute is required, all other attributes are optional.

Option name Description Possible values Default
name The name of the Map. Anything you want. ""
worldDir This tells Tectonicus which Minecraft world to render. file path -
closestZoomSize When zoomed-in all the way this value determines the area that will be visible in one of the rendered picture files. Increase [x] to "widen" the camera lens of this closest view. Sometimes used in conjunction with numZoomLevels (see below). For example, closestZoomSize=24 will create tiles that show 100% more terrain than at the default 12 (i.e. you will be "further back"). It is from these closest tiles (zoom8) that the other, wider tiles are rendered (zoom7 - zoom0). Increasing this number requires more memory, so making it too large may result in out-of-memory errors. a number 12
dimension The dimension to draw. 'terra'
for the regular minecraft overworld
'nether'
for the nether dimension
'end'
for The End dimension
terra
cameraAngle Use this command to change the orientation of north. The default setting of 45 produces an oblique view with north at the upper right of the map (north west at the top). Increase this number to rotate the map’s cardinal directions counter-clockwise (or decrease to rotate clockwise). 90 (or -270) will give you north at the top, 225 (or -45) will give you north at the bottom left and south east at the top; and so on. an angle in degrees from -360 to 360 45 (north at upper right)
cameraElevation This specifies the angle of elevation for the camera, in degrees. 10 is looking mostly horizontal, 90 is looking directly down. Defaults to 45. Choose 30 for a more traditional isometric view. an angle in degrees from 10 to 90 45
north compass rose north direction '-z' / '+z'/ '-x' / '+x' -
compassRose custom image for map compass rose a file path ""

Subset (Optional)

A sub-node of the map node, this will limit the rendering to a circular area of the world map of specified location and size, rather than rendering the entire map. This is useful when testing Tectonicus options to drastically reduce rendering time.

<!-- Limit world rendering to a sub region. Optional, omit for the full world -->
<!-- Radius is in world units. Remove 'origin' to center around the spawn point -->
<subset>
	<CircularSubset origin="0, 0" radius="200" />  <!-- note capital ‘C’ -->
</subset>
Option name Description Possible values Default
origin the center point of the circular region to include a world x and z coord in the form "x, y" defaults to the spawn position if not set
radius radius (in minecraft blocks) to actually include in the map a number -

Layer

A sub-node of the map node. This controls how the map layers appear in the final rendering.

<layer  name = "Day"
        lighting = "day"
	renderStyle = "normal"
	imageFormat = "png"
	imageCompressionLevel = "1.0"		
	useDefaultBlocks="true"
	customBlocks="/Users/xxx/TectonicusTests/customBlocks.xml" />
Option name Description Possible values Default
name The name of the layer. The name can be anything you wish. ""
lighting the lighting style to use 'day' for daylight
'night' for night time lighting
'none' for no lighting (full bright)
'cave' for cave lighting (like night time, but deeper caves are darker)
day
renderStyle the rendering style to use 'regular' for normal drawing
'cave' for cave rendering (strips off the surface layer)
'nether' for nether rendering (strips off the nether roof) 'exploredcaves' for only explored caves
regular
imageFormat the format to write these layer images in 'png' for png files (highest quality, largest file size)
'gif' for gif files (max 256 colours per image. Good quality and file size if using default minecraft textures or another low-colour texture pack)
'jpg' for jpg files (variable quality, good for photo realistic texture packs)
png
imageCompressionLevel the image compression level to use (only applies when using jpg image format) a decimal between zero and one. 1 is highest quality. Creating jpg tiles at 0.75 (75%) instead of the default png's will result 50%+ space savings. 0.95
useDefaultBlocks specifies whether to render using the default set of blocks or not 'true' or 'false' true
customBlocks specifies the path to the xml file where custom block data is stored a file path none

Markers

Sub-nodes of a map node, these options control which markers appear on the final rendered map.

Signs (Optional)

<signs filter="special" />
Option name Description Possible values Default
filter a filter to apply when exporting signs 'all' to export all signs 'none' to export no signs 'special' to export signs which begin and end with one of the special characters: ! # - or ~. E.g. a sign like "-- lookout point --" Empty signs will always be skipped special

Views (Optional)

Option name Description Possible values Default
filter a filter to apply when exporting view markers 'all' for all views or 'none' for none all
imageFormat the format to write the view images in 'png' for png files (highest quality, largest file size)
'gif' for gif files (max 256 colours per image. Good quality and file size if using default minecraft textures or another low-colour texture pack)
'jpg' for jpg files (variable quality, good for photo realistic texture packs)
png
imageCompressionLevel the image compression level to use (only applies when using jpg image format) a decimal between zero and one. 1 is highest quality. Creating jpg tiles at 0.75 (75%) instead of the default png's will result 50%+ space savings. 0.95
drawDistance distance in number of blocks to show in the image integer value greater than 0 200
fov the field of view of the image 30 - 110 (same as Minecraft) 70

Players (Optional)

<players filter="all" playerFilterFile="players.txt" />
Option name Description Possible values Default
filter a filter to apply when exporting players 'all' to export all players 'none' to export no players 'ops' to only export players with ops privilege 'whitelist' to only export players within the player filter file 'blacklist' to export all players except those in the player filter file all
playerFilterFile a path to a text file to use with the 'whitelist' and 'blacklist' options. Should contain one player name per line (the same as a minecraft ops file) a file path empty

Portals (Optional)

<portals filter="all" />
Option name Description Possible values Default
filter a filter to apply when exporting portal markers 'all' for all portals or 'none' for none all

Tweaks Node (Optional)

<tweaks	forceLoadAwt = "false" />

These are options you shouldn't need to change, but can workaround quirks on some machines. All attributes are optional.

Option name Description Possible values Default
forceLoadAwt force the loading of the Awt display system when Tectonicus starts 'true' or 'false' false

Debug node (Optional)

<debug maxTiles = "-1"
       verbose = "false" />

These are debugging options not intended for general use.

Option name Description Possible values Default
maxTiles sets a maximum amount of tiles to draw, after which drawing stops. any positive number, or -1 to disable -1 (disabled)
verbose override the log level to TRACE 'true' or 'false' false