Custom/Mod Blocks

WorldPainter supports the use of mod blocks in custom materials, for use in e.g. Custom Terrain types, Custom Ground Cover layers, Custom Underground Pockets layers, etc.. One way to do this is to manually enter the block ID ("resource location") on the material selector (the Select Custom Material or Edit Material screen), and manually add any properties the block might have. This is a lot of work though, and WorldPainter will not know how to treat the block properly during the Export, post processing and lighting phases. As a result the blocks may not be correctly lit, may inadvertently block the placement of Custom Objects, etc.

To alleviate these problems, it is possible to tell WorldPainter about the properties of the known blocks of existing mods, by installing Custom Block Definition Files.

You can create such a file yourself, but ideally they will be created by the authors of mods, or volunteer users. If there is no definition file listed below for a mod you would like to use, please contact the authors of the mod and point them to this page.

Installing Custom Block Definition Files

To add support for a mod's blocks to WorldPainter, follow these steps:

1. Download the Custom Block Definition File for the mod below
2. In WorldPainter, select Open custom materials folder from the Tools menu
3. Move the downloaded .csv file into the opened folder
4. Restart WorldPainter

For now, everyone working on the same world will have to do this separately; the definitions do not travel with the .world file. This will be improved in the future.

Supported Mods

Here you can find Custom Block Definition Files for select mods:

None yet. Please contact the authors of your favourite mods and ask them to create such files, or do it yourself, and have them emailed to info@…!

Creating Custom Block Definition Files

Custom Block Definition Files are tables in the form of CSV files that describe basic properties such as the ID, lighting, colouring, and the block properties each block has.

IMPORTANT: Do not use Excel or other spreadsheet software to create or edit these files! They will mangle them. Use a text editor or programmer's editor, for example ​Visual Studio Code.

For an example, see the bottom of this page.

Basic format

The files should be CSV files with the following properties:

• Filename extension: csv
• Encoding: UTF-8 without a BOM
• Field separator: comma
• The first row should contain the field names
• String values should be quoted with double quotes: "
• Boolean values should be either true or false

Columns

The data can contain the following columns. Note that you can leave out any empty columns:

Column	Mandatory	Type	Default	Description
name	*	String		The namespace and name of the block separated by a colon ("ID" or "resource location")
discriminator		String	-	An optional discriminator to discriminate multiple rows with the same name. See below for details
properties		String	-	A comma-separated list of the names and types of all the properties this block can have. See below for details
opacity		Integer	1)	The opacity of the block (how much light it blocks), from 0 (fully transparent) to 15 (fully opaque)
receivesLight		Boolean	1)	Whether the block should be lit itself, despite being fully opaque (e.g. stair blocks, slabs, etc.). Only applies to fully opaque blocks; should be set to false for other blocks
insubstantial		Boolean	1)	Whether the block should be considered insubstantial. See below for details
resource		Boolean	1)	Whether the block should be considered an ore or resource. These are replaced with minecraft:stone by the "remove resources" Merge option
tileEntity		Boolean	false	Whether the block is a tile/block entity
tileEntityId		Boolean	-	If tileEntity is true: the ID of the corresponding behaviour. This is often, but not always, the same as name
treeRelated		Boolean	1)	Whether the block is part of trees, or attached to trees. These are removed by the "remove trees" Merge option
vegetation		Boolean	1)	Whether the block is a plant, other than treeRelated. These are removed by the "remove vegetation" Merge option
blockLight		Integer	0	How much block light the block emits, from 0 - 15
natural		Boolean	1)	Whether the block should be considered natural as opposed to being man-made. Chunks with blocks that are not natural have the Read Only layer applied during Import
watery		Boolean	false	Whether the block is always flooded with water, regardless of its properties (e.g. water plants)
colour		Hex	Magenta	The colour in which the block should be rendered in the editor view, as a hexidecimal number in aarrggbb format, where aa should always be ff (opaque). When not specified, the block will be rendered in magenta
horizontal_orientation_schemes		String	2)	Overrides the detected horizontal orientation scheme(s). Can be none to indicate that the block cannot be rotated or mirrored horizontally, or a comma-separated list of valid horizontal orientation scheme names (see below)
vertical_orientation_scheme		String	2)	Overrides the detected vertical orientation scheme. Can be none to indicate that the block cannot be mirrored vertically, or a valid vertical orientation scheme name (see below)

¹) The default value is guessed based on the block name

²) The default value is guessed based on the block properties

Discriminator

The discriminator is used if a block occurs multiple times with the same name but different values (e.g. a different blockLight). It consists of a comma-separated list of key-value pairs (separated by equals signs) describing the property names and values of blocks to which this row should apply. It should only contain the discriminating properties (those whose value actually determines which row applies).

Examples: berries=false or waterlogged=true,pickles=3.

NOTE: when using this field, the block must of course occur at least twice with the same name, and you must make sure that all possible permutations of the discriminating properties are covered by exactly one row! In other words: it must not be possible for no rows to match, or for more than one row to match.

Legacy/numbered mod blocks

For mod blocks for Minecraft 1.12 or older, which uses numerical block IDs and data values rather than names and properties, set the name column to legacy:block_n (where n is the numerical block ID) and the discriminator column to data_value=n (where n is the data value).

Properties

These are all the properties and their types and values that the block can have. It consists of a comma-separated list of property definitions. A property definition consist of the property name, a colon, and a type definition. The type definition should be one of:

b: a boolean

i[n-m]: an integer, where n is the minimum value and m is the maximum value

e[val1;val2;...]: an enumeration, where val1,val2,... is a semicolon-separated list of possible values

Examples: facing:e[north;south;west;east],powered:b,face:e[floor;wall;ceiling] or distance:i[1-7],persistent:b.

Insubstantial blocks

An "insubstantial" block is an inconsequential, often decorative block that players would presumably not mind being summarily removed or replaced. Usually it is non-blocking (players walk through it) and it implies that it cannot support anything solid. It encompasses things like grass, flowers, water and snow, for example.

More concretely for WorldPainter, a block being insubstantial has the following consequences:

• It will be replaced by other blocks (substantial or not, except air blocks) when placing Custom Objects or when Merging
• It will not block the placement of Custom Objects by default
• Trees and Custom Objects will not be placed on it by default
• The Frost layer will not deposit snow on it
• Custom Ground Cover layers will not be placed on it

Snow

For a block to be eligible to have snow placed on it by the Frost layer, make sure that it is both fully opaque (opacity is 15) and not insubstantial (insubstantial is false).

Horizontal orientation scheme

This describes how to horizontally rotate and/or mirror blocks to which that applies. WorldPainter normally auto-detects these based on the properties that are present. A block can have multiple horizontal orientation schemes. Note that if this value is specified it will override all horizontal orientation schemes:

Name	Description
none	The block cannot be rotated or mirrored
axis	axis property containing x, y or z
cardinal_directions	north, east, south and west properties, each containing some arbitrary value
facing	facing property containing the cardinal direction north, east, south or west
facing_asym	facing property containing the cardinal direction north, east, south or west. This variant is for blocks which are not symmetrical and uses rotation to implement mirroring. Not autodetected
rotation	rotation property containing an integer from 0 to 15 (inclusive) where 0 is south, 4 is west, etc.
shape	shape property containing north_south, east_west, etc. as used by Minecraft for rails
stair_corner	shape property set to inner_left, inner_right, outer_left or outer_right as used by e.g. Minecraft stair corner blocks
type	type property containing left or right
hinge	hinge property containing left or right

Example

View an example of a Custom Block Definition File here​ (click on Original Format at the bottom of the page to download the file). These are some blocks from WorldPainter's own internal block definitions. Don't use these! This is just an example of how to create such a file.