Block Textures

Block textures define the visual appearance of blocks in the game world. The texture system supports per-face textures, weighted texture variants, and biome-based tinting.

Asset Location

DirectoryAssets/Common/
- DirectoryBlockTextures/
  - Soil_Dirt.png
  - Soil_Grass_Side.png
  - Soil_Grass_Top_GS.png
  - Rock_Basalt.png
  - Rock_Basalt_Brick.png
  - Clay_Blue.png
  - …645 texture files
- DirectoryBlocks/
  - DirectoryDecorative_Sets/
    DirectoryVillage/
    …
    DirectoryTavern/
    …
    DirectoryAncient/
    …
  - DirectoryStone/
    …
  - DirectoryFoliage/
    …
  - DirectoryFarming/
    …
- DirectoryTintGradients/
  - Grass_Cold.png
  - Grass_Warm.png

Texture Organization

Block Textures Directory

The BlockTextures/ directory contains ~645 PNG texture files for standard blocks. Textures are organized by naming convention rather than subdirectories.

Naming Conventions

Base Textures

{Category}_{Material}.png

Examples:

Soil_Dirt.png - Basic dirt texture
Rock_Basalt.png - Basalt rock texture
Clay_Blue.png - Blue clay texture
Chalk.png - Chalk texture

Directional Variants

Blocks with different appearances on different faces use suffixes:

Suffix	Description
`_Top`	Top face of block
`_Side`	Side faces
`_Bottom`	Bottom face

Examples:

Soil_Grass_Top.png - Grass top face
Soil_Grass_Side.png - Grass side face (dirt with grass edge)
Bone_Top.png - Bone block top
Bone_Side.png - Bone block sides

Variant Textures

Multiple visual variants use numeric suffixes:

{Name}_{Variant}.png

Examples:

Peachstone_Brick.png
Peachstone_Brick02.png
Peachstone_Brick03.png
Peachstone_Brick04.png

Decorative Variants

Suffix	Description
`_Brick`	Brick pattern
`_Cobble`	Cobblestone pattern
`_Smooth`	Smooth surface
`_Ornate`	Decorative pattern
`_Decorative`	Complex decorative pattern

Examples:

Calcite.png - Base calcite
Calcite_Brick.png - Calcite bricks
Calcite_Brick_Smooth.png - Smooth calcite bricks
Calcite_Brick_Ornate.png - Ornate calcite bricks
Calcite_Cobble.png - Calcite cobblestone

Tint Gradient Textures

Suffix _GS indicates a grayscale texture used with biome tinting:

Soil_Grass_Top_GS.png - Grayscale grass for tinting
Soil_Grass_Side_GS.png - Grayscale grass side
Moss_Block_GS_Top.png - Grayscale moss

Texture Definition in JSON

In a block type’s JSON definition, the Textures property is an array of BlockTypeTextures objects. Each entry assigns a texture path to specific faces and has an optional weight for random selection.

Face Keys

Key	Face	Protocol Mapping
`Up`	Top (+Y)	`top`
`Down`	Bottom (-Y)	`bottom`
`North`	North	`back`
`South`	South	`front`
`East`	East	`right`
`West`	West	`left`

Shortcut Keys

Key	Sets
`All`	All six faces at once
`Sides`	North, South, East, West
`UpDown`	Up and Down

Example

{
  "Textures": [
    {
      "All": "BlockTextures/Soil_Dirt.png"
    }
  ]
}

A block with different top and side textures:

{
  "Textures": [
    {
      "Up": "BlockTextures/Soil_Grass_Top.png",
      "Down": "BlockTextures/Soil_Dirt.png",
      "Sides": "BlockTextures/Soil_Grass_Side.png"
    }
  ]
}

Weighted Variants

Multiple texture entries with Weight values allow random variation. The weights are normalized into ratios when sent to the client.

{
  "Textures": [
    {
      "All": "BlockTextures/Rock_Stone.png",
      "Weight": 3
    },
    {
      "All": "BlockTextures/Rock_Stone02.png",
      "Weight": 1
    }
  ]
}

The first variant appears 75% of the time (3/4), the second 25% (1/4). Default weight is 1.

Default Texture

If no textures are specified, all faces fall back to BlockTextures/Unknown.png.

Biome Tint

The BiomeTint property is an integer index applied per face. You can set it for all faces at once or individually with BiomeTintUp, BiomeTintDown, BiomeTintNorth, BiomeTintSouth, BiomeTintEast, BiomeTintWest.

{
  "BiomeTint": 1
}

Texture Side Mask

The TextureSideMask property specifies a separate texture path used as a side mask overlay. It follows the same asset validation rules as regular textures (must be a .png in a valid root directory).

Texture Categories

Soil & Natural

Category	Count	Examples
Soil	~40	`Soil_Dirt`, `Soil_Grass`, `Soil_Clay`
Rock	~100	`Rock_Basalt`, `Rock_Aqua`, `Rock_Crystal`
Sand	~15	`Sand`, `Sand_Red`, `Sand_Volcanic`
Clay	~30	`Clay_Blue`, `Clay_Smooth_Red`

Processed & Building

Category	Count	Examples
Brick	~50	`Calcite_Brick`, `Rock_Basalt_Brick`
Plank	~20	`Plank_Oak`, `Plank_Pine`
Metal	~15	`Metal_Iron`, `Metal_Gold`
Glass	~10	`Glass`, `Glass_Stained_*`

Special

Category	Count	Examples
Crystal	~20	`Rock_Crystal_Blue`, `Rock_Crystal_Purple`
Mushroom	~15	`Mushroom_Block_Blue`, `Mushroom_Block_Brown`
Cloth	~15	`Cloth_Black`, `Cloth_Blue`

Block Type Lists

Block types are organized into lists for tool interactions and game logic.

DirectoryAssets/Server/BlockTypeList/
- Soils.json
- Rock.json
- Ores.json
- Snow.json
- TreeWood.json
- TreeLeaves.json
- Gravel.json
- PlantsAndTrees.json

Soils List

{
  "Blocks": [
    "Soil_Dirt",
    "Soil_Dirt_Burnt",
    "Soil_Dirt_Cold",
    "Soil_Dirt_Dry",
    "Soil_Dirt_Poisoned",
    "Soil_Grass",
    "Soil_Grass_Burnt",
    "Soil_Grass_Cold",
    "Soil_Grass_Deep",
    "Soil_Grass_Dry",
    "Soil_Grass_Full",
    "Soil_Grass_Sunny",
    "Soil_Grass_Wet"
  ]
}

These lists are used by tools to determine mining behavior and durability loss.

Decorative Sets

The Blocks/Decorative_Sets/ directory contains themed block collections with models and textures.

Available Sets

Set	Contents	Theme
Village	Furniture, containers	Human village
Tavern	Tables, chairs, barrels	Inn furnishings
Ancient	Ruins, artifacts	Ancient civilization
Desert	Desert structures	Arid region
Frozen_Castle	Ice furniture	Frozen region
Jungle	Jungle structures	Tropical region
Kweebec	Kweebec-style	Kweebec architecture
Temple_Light	Temple blocks	Light temple
Temple_Dark	Temple blocks	Dark temple
Temple_Emerald	Temple blocks	Emerald temple
Scarak_Hive	Organic shapes	Scarak structures
Scarak_Temple	Temple blocks	Scarak temple

Set Contents

Each decorative set typically includes:

Directoryfunction Set() { [native code] }/
- Barrel.blockymodel
- Barrel_*.png texture variants
- Bed.blockymodel
- Bed_Texture.png
- Chair.blockymodel
- Chair_Texture.png
- Chest.blockymodel
- Chest_Texture.png
- Door.blockymodel
- Door_Texture.png
- Table.blockymodel
- Table_Texture.png
- Lantern.blockymodel
- Lantern_Texture.png
- …

Village Set Example

DirectoryVillage/
- Barrel.blockymodel
- Barrel_Ancient.png
- Barrel_Crude.png
- Barrel_Tavern.png
- Bed.blockymodel
- Bed_Texture.png
- Bench.blockymodel
- Chest.blockymodel
- Chest_Small.blockymodel
- Door.blockymodel
- Lantern.blockymodel
- Lantern_Ceiling.blockymodel
- Painting*.blockymodel various sizes
- Pot.blockymodel
- Pot_Broken.blockymodel
- Table.blockymodel
- Wardrobe.blockymodel
- Window*.blockymodel connected block variants

Texture Requirements

Format

The server validates that all block textures must be .png files located in one of these root directories: BlockTextures/, Blocks/, Items/, NPC/, Resources/, or VFX/.

Dimensions

Requirement	Value
Standard block	32x32 pixels
High-detail	64x64 or 128x128 pixels
Format	PNG

Alpha Channel

Opaque blocks: No alpha needed
Transparent blocks (glass, leaves): Alpha for transparency
Connected blocks: Alpha for edge blending

Creating Custom Textures

Basic Block Texture

Create a 32x32 PNG file and place it in your plugin’s BlockTextures/ directory:

BlockTextures/MyPlugin_Block_Custom.png

Then reference it in your block type definition:

{
  "Id": "MyPlugin_CustomBlock",
  "Textures": [
    {
      "All": "BlockTextures/MyPlugin_Block_Custom.png"
    }
  ]
}

Directional Block

Create separate texture files for different faces, then assign them using face keys:

{
  "Id": "MyPlugin_GrassBlock",
  "Textures": [
    {
      "Up": "BlockTextures/MyPlugin_Grass_Top.png",
      "Down": "BlockTextures/MyPlugin_Dirt.png",
      "Sides": "BlockTextures/MyPlugin_Grass_Side.png"
    }
  ]
}

Tinted Block

Create a grayscale texture (conventionally using a _GS suffix) and set the BiomeTint index:

{
  "Id": "MyPlugin_TintedGrass",
  "Textures": [
    {
      "Up": "BlockTextures/MyPlugin_Grass_Top_GS.png",
      "Down": "BlockTextures/MyPlugin_Dirt.png",
      "Sides": "BlockTextures/MyPlugin_Grass_Side_GS.png"
    }
  ],
  "BiomeTint": 1
}

Texture Variants

Use multiple entries in the Textures array with weights for random variation:

{
  "Id": "MyPlugin_StoneBlock",
  "Textures": [
    { "All": "BlockTextures/MyPlugin_Stone.png", "Weight": 2 },
    { "All": "BlockTextures/MyPlugin_Stone02.png", "Weight": 1 },
    { "All": "BlockTextures/MyPlugin_Stone03.png", "Weight": 1 }
  ]
}

Color Categories

Natural Colors by Biome

Biome	Grass Tint	Soil Color
Plains	Bright green	Brown
Desert	Yellow-green	Tan
Cold/Taiga	Blue-green	Gray-brown
Jungle	Deep green	Dark brown
Volcanic	Orange	Black/gray
Burnt	Brown	Charred

Clay Colors

Available clay colors:

Black, Blue, Cyan, Green, Grey
Lime, Orange, Pink, Purple
Red, White, Yellow

Each has both rough (Clay_*) and smooth (Clay_Smooth_*) variants.

Crystal Colors

Blue, Cyan, Green, Pink, Purple, Red

Each crystal color has base and _Top variants.

Best Practices

Follow naming conventions - Use established prefixes and suffixes
Match existing style - Study vanilla textures for art direction
Use weights for variation - Multiple weighted texture entries reduce visual repetition
Use grayscale for tinting - Pair _GS textures with BiomeTint for biome adaptation
Prefix custom IDs - Use your plugin name to avoid asset path collisions
Place in valid roots - Textures must be in BlockTextures/, Blocks/, or other validated directories

Block Types - Block definitions
Decorative Sets - Themed block sets
Animations - Block animations
Connected Blocks - Multi-block connections

Block Textures

Asset Location

Texture Organization

Block Textures Directory

Naming Conventions

Base Textures

Directional Variants

Variant Textures

Decorative Variants

Tint Gradient Textures

Texture Definition in JSON

Face Keys

Shortcut Keys

Example

Weighted Variants

Default Texture

Biome Tint

Texture Side Mask

Texture Categories

Soil & Natural

Processed & Building

Special

Block Type Lists

Soils List

Decorative Sets

Available Sets

Set Contents

Village Set Example

Texture Requirements

Format

Dimensions

Alpha Channel

Creating Custom Textures

Basic Block Texture

Directional Block

Tinted Block

Texture Variants

Color Categories

Natural Colors by Biome

Clay Colors

Crystal Colors

Best Practices

Related