VoxelEngine/doc/en/block-properties.md

Block properties

Visual

texture

Block texture name (name of the file in textures/blocks/ with no path and extension included, just name)

Texture file must be a png image

texture-faces

Important

Can't be used if texture already specified

An array of 6 texture names for block sides.

Example:

"texture-faces": [
    "grass_side",
    "grass_side",
    "dirt",
    "grass_top",
    "grass_side",
    "grass_side"
]

model

Block model type from list:

• "block" - default block model
• "none" - invisible block (air)
• "X" - grass model (two crossed sprites)
• "aabb" - model based of block hitbox (complex hitbox will be combined into one). Examples: pipes, bulbs, panels.
• "custom" - used when specifying custom models via model-name

model-name

In addition to built-in model types, you can use your own, loaded from file.

The property specifies the model name without entry_point:models/ nor extension.

Warning

Textures (materials) used in the model must be in the blocks atlas and specified in the atlas-texture format: blocks:texture_name

draw-group

Integer specifying number of block draw group (render order). Used for semi-transparent blocks.

translucent

Enables translucency support in block textures (examples: water, ice). Should only be used when needed, as it impacts performance. Not required for full transparency (grass, flowers).

rotation

Rotation profile (set of available block rotations and behaviour of placing block rotation) from list:

• "none" - no rotation available (default profile)
• "pipe" - wood logs, pipes, pillars
• "pane" - panels, doors, signs
• "stairs" - "pane" + flipped variants

Variants

Some properties can vary dynamically, depending on the variant number stored in the user bits of the block.

Variability parameters are specified in the state-based block:

{
    ...
    "state-based": {
        "offset": 0,
        "bits": 4,
        "variants": [
            {...},
            ...
        ]
    }
}

• offset specifies the bit offset from which the variant index starts. (Default is 0)
• bits specifies the number of bits encoding the variant index. (Default is 4). Currently, the maximum number of variants is 16, so specifying more than 4 bits does not make practical sense.

Properties available for variance:

• model
• model-name
• texture
• texture-faces
• model-primitives (deprecated)

Variants are managed via block.set_variant(x, y, z, index).

Custom model variants (geometry switching)

You can use different custom models for different variants. Provide a separate model-name for each variant that needs different geometry. The renderer caches geometry per (block id, variant).

The base model (specified in root) becomes variant 0. The variants array maps to indices 1+.

Example (default + two custom variants):

{
    "model": "custom",
    "model-name": "stairs_middle",
    "state-based": {
        "bits": 4,
        "variants": [
            { "model": "custom", "model-name": "stairs_left" },
            { "model": "custom", "model-name": "stairs_right" }
        ]
    }
}

In this example:

• Variant 0 = stairs_middle (from root)
• Variant 1 = stairs_left (from variants[0])
• Variant 2 = stairs_right (from variants[1])

Lighting

emission

An array of 3 integers - R, G, B of light in range [0, 15]

Examples:

• [15, 15, 15] - white with maximal intensity
• [7, 0, 0] - dim red light
• [0, 0, 0] - no emission (default value)

light-passing

Light ignores block if true

sky-light-passing

Vertical sky light ray ignores block if true. (used for water)

shadeless

Turns off block model shading

ambient-occlusion (Vertex-based Ambient-Occlusion)

Determines the presence of the vertex AO effect. Turned-on by default.

culling

Face culling mode:

• default - normal face culling
• optional - face culling among blocks of the same rendering group can be disabled via the graphics.dense-render setting.
• disabled - face culling among blocks of the same rendering group disabled.

Physics

obstacle

Block is not a physical obstacle if false

hitbox

An array of 6 numbers describing an offset an size of a block hitbox.

The numbers are specified in the range [0.0, 1.0] - i.e. within the block (in the case of an extended block, the hitbox can be larger than one, but must not go beyond the "size" property).

Array [0.25, 0.0, 0.5, 0.75, 0.4, 0.3] describes hitbox width:

• offset 0.25m east
• offset 0.0m up
• offset 0.5m north
• 0.75m width (from east to west)
• 0.4m height
• 0.3m length (from south to north)

For composite hitboxes, the hitboxes property is used - an array of hitboxes, for example:

"hitboxes": [
  [0, 0, 0, 1, 0.625, 1],
  [0, 0.6875, 0, 1, 0.3125, 1]
]

grounded

Is block may only be set on a solid block and destructs on below block destruction.

selectable

Cursor ray will ignore block if false.

replaceable

Is block replaceable. Examples: air, water, grass, flower.

breakable

Is block breakable by mouse click.

Inventory

hidden

If true an item will not be generated for block. picking-item must be specified

picking-item

Item will be chosen on MMB click on the block.

Example: block door:door_open is hidden, so you need to specify picking-item: "door:door.item" to bind it to not hidden door:door block item.

ui-layout

Block UI XML layout name. Default: string block id.

Examples for block containermod:container:

• default: containermod:container (containermod/layouts/container.xml)
• if containermod:randombox specified: (containermod/layouts/randombox.xml)

inventory-size

Number of block inventory slots. Default - 0 (no inventory).

Extended blocks

size

Array of three integers. Default value is [1, 1, 1].

Block fields

Block fields allow you to write more data unique to a specified voxel than the user bits allow.

Block fields are declared in the following format:

"fields": {
    "name": {"type": "data_type"},
    "array_name": {"type": "data_type", "length": "array_length"}
}

In addition to type and length, the convert-strategy parameter determines the value conversion strategy when narrowing the data type.

The parameter takes one of two values:

• reset - a value that does not exists in the new range will be reset to 0
• clamp - the value will be reduced to the closest one in the new range

Example: the number 231 when changing the field type from int16 to int8:

• in reset mode will turn into 0
• in clamp mode will turn into 127

Available data types:

Type	Size	Description
int8	1 byte	signed integer 8 bits
int16	2 bytes	signed integer 16 bits
int32	4 bytes	signed integer 32 bits
int64	8 bytes	integer signed 64 bits
float32	4 bytes	floating-point 32 bits
float64	8 bytes	floating-point 64 bits
char	1 byte	character

• Currently, the total sum of the field sizes cannot exceed 240 bytes.
• A field without an array length specification is equivalent to an array of 1 element.
• A character array can be used to store UTF-8 strings.

User properties

User properties must be declared in pack:config/user-props.toml file:

"pack:property_name" = {}

Example: user properties of pack base.

Properties introduced by the base pack

Access to custom properties is provided through the table block.properties[id]["property"] where id is the numeric id (index) of the block.

base:durability

The time it takes to break a block without tools or effects, measured in seconds.

Loot - base:loot

A list of tables with properties:

{
    "item": "pack:item",
    "min": 1,
    "max": 3,
    "chance": 0.5
}

• count defaults to 1. It does not need to be specified if min and max are provided.
• min, max - the minimum and maximum quantity of the item.
• chance - the probability of the item dropping. Defaults to 1.0.

It should be noted that the item refers specifically to the item. That is, to specify the item of a block, you need to add .item after the block name. Example: base:dirt.item.

To generate loot, the function block_loot(block_id: int) in the base:util module should be used.

Other properties

script-name

Used to specify block script name (to reuse one script to multiple blocks). Name must not contain packid:scripts/ and extension. Just name.

Tick Interval - tick-interval

The interval in ticks (1/20th of a second). A value of 20 results in an on_block_tick call interval of one second.

Methods

Methods are used to manage the overwriting of properties when extending a block with other packs.

property_name@append

Adds elements to the end of the list instead of completely overwriting it.

Tags

Tags allow you to designate general properties of blocks. Names should be formatted as prefix:tag_name. The prefix is ​​optional, but helps avoid unwanted logical collisions. Example:

{
    "tags": [
        "core:ore",
        "base_survival:food",
    ]
}

Block tags can also be added from other packs using the your_pack:tags.toml file. Example:

"prefix:tag_name" = [
    "random_pack:some_block",
    "another_pack:item",
]
"other_prefix:other_tag_name" = [
    # ...
]
``