| | 27 | |
| | 28 | Custom Block Definition Files are tables in the form of CSV files that describe basic properties such as lighting, colouring, and the block properties it has: |
| | 29 | |
| | 30 | == Basic format == |
| | 31 | |
| | 32 | The files should be CSV files with the following properties: |
| | 33 | |
| | 34 | * Filename extension: `csv` |
| | 35 | * Encoding: UTF-8 without a BOM |
| | 36 | * Field separator: comma |
| | 37 | * The first row should contain the field names |
| | 38 | * String values should be quoted with double quotes |
| | 39 | * Boolean values should be either `true` or `false` |
| | 40 | |
| | 41 | == Columns == |
| | 42 | |
| | 43 | The data should contain the following columns: |
| | 44 | |
| | 45 | | Column | Mandatory | Type | Description | |
| | 46 | |-----------------|-----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| | 47 | | `name` | * | String | The namespace and name of the block separated by a colon ("ID" or "resource location") | |
| | 48 | | `discriminator` | | String | An optional discriminator to discriminate multiple rows with the same `name` | |
| | 49 | | `properties` | * | String | A comma-separated list of the names and types of all the properties this block can have. See below for details | |
| | 50 | | `opacity` | * | Integer | The opacity of the block (how much light it blocks), from 0 (fully transparent) to 15 (fully opaque) | |
| | 51 | | `receivesLight` | * | Boolean | 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 | |
| | 52 | | `insubstantial` | * | Boolean | Whether the block should be considered insubstantial. See below for details | |
| | 53 | | `resource` | * | Boolean | Whether the block should be considered an ore or resource. These are replaced with `minecraft:stone` by the "remove resources" Merge option | |
| | 54 | | `tileEntity` | * | Boolean | Whether the block is a tile/block entity | |
| | 55 | | `tileEntityId` | | Boolean | If `tileEntity` is `true`: the ID of the corresponding behaviour. This is often, but not always, the same as `name` | |
| | 56 | | `treeRelated` | * | Boolean | Whether the block is part of trees, or attached to trees. These are removed by the "remove trees" Merge option | |
| | 57 | | `vegetation` | * | Boolean | Whether the block is a plant, other than `treeRelated`. These are removed by the "remove vegetation" Merge option | |
| | 58 | | `blockLight` | * | Integer | How much block light the block emits, from 0 - 15 | |
| | 59 | | `natural` | * | Boolean | 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 | |
| | 60 | | `watery` | * | Boolean | Whether the block is always flooded with water, regardless of its properties (e.g. water plants) | |
| | 61 | | `colour` | | Hex | 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 | |
| | 62 | |
| | 63 | == Discriminator == |
| | 64 | |
| | 65 | The discriminator is used if a block occurs multiple times with the same name but different values (e.g. a different |
| | 66 | `blockLight`). It consists of a comma-separated list of key-value pairs (separated by equals signs) describing the |
| | 67 | property names and values of blocks to which this row should apply. It should only contain the discriminating properties |
| | 68 | (those whose value actually determines which row applies). |
| | 69 | |
| | 70 | Examples: `berries=false` or `waterlogged=true,pickles=3`. |
| | 71 | |
| | 72 | **NOTE:** when using this field, the block must of course occur at least twice with the same `name`, and you must make |
| | 73 | sure that all possible permutations of the discriminating properties are covered by exactly one row! In other words: it |
| | 74 | must not be possible for no rows to match, or for more than one row to match. |
| | 75 | |
| | 76 | == Properties == |
| | 77 | |
| | 78 | These are all the properties and their types and values that the block can have. It consists of a comma-separated list |
| | 79 | of property definitions. A property definition consist of the property name, a colon, and a type definition. The type |
| | 80 | definition should be one of: |
| | 81 | |
| | 82 | `b`: a boolean |
| | 83 | |
| | 84 | `i[n-m]`: an integer, where `n` is the minimum value and `m` is the maximum value |
| | 85 | |
| | 86 | `e[val1;val2;...]`: an enumeration, where `val1,val2,...` is a semicolon-separated list of possible values |
| | 87 | |
| | 88 | Examples: `facing:e[north;south;west;east],powered:b,face:e[floor;wall;ceiling]` or `distance:i[1-7],persistent:b`. |
| | 89 | |
| | 90 | == Insubstantial blocks == |
| | 91 | |
| | 92 | An "insubstantial" block is an inconsequential block that players would presumably not mind being summarily removed or |
| | 93 | replaced. Usually it is non-blocking (players walk through it) and it implies that it cannot support anything solid. It |
| | 94 | encompasses things like grass, flowers, water and snow, for example. |
| | 95 | |
| | 96 | More concretely for WorldPainter, a block being |
| | 97 | insubstantial has the following consequences: |
| | 98 | |
| | 99 | * It will be replaced by other blocks (substantial or not, except air blocks) when placing Custom Objects or when Merging |
| | 100 | * It will not block the placement of Custom Objects by default |
| | 101 | * Trees and Custom Objects will not be placed on it by default |
| | 102 | * The Frost layer will not deposit snow on it |
| | 103 | * Custom Ground Cover layers will not be placed on it |
| | 104 | |
| | 105 | == Snow == |
| | 106 | |
| | 107 | For a block to be eligible to have snow placed on it by the Frost layer, make sure that it is both fully opaque |
| | 108 | (`opacity` is `15`) and not insubstantial (`insubstantial` is `false`). |
