= !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 1. In !WorldPainter, select `Open custom materials folder` from the `Tools` menu 1. Move the downloaded `.csv` file into the opened folder 1. 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 [mailto:info@worldpainter.net?subject=Custom%20block%20definition%20file info@worldpainter.net]! = 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 [https://code.visualstudio.com/ 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 should contain the following 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 [#Discriminator below] for details || || `properties` || || String || - || A comma-separated list of the names and types of all the properties this block can have. See [#Properties 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 [#Insubstantialblocks 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 || ^1^) The default value is guessed based on the block name == 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 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`). == Example == View an example of a Custom Block Definition File [attachment:custom-blocks-example.csv​ 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.