Creating a Tectonicus config file
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.xmlIf 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 |