Hytale Custom Blocks

Reference for creating custom blocks in Hytale plugins via asset packs and JSON item definitions with BlockType configuration.

Source: https://hytalemodding.dev/en/docs/guides/plugin/creating-block Related skills: For block components and ECS ticking behavior, see hytale-ecs. For items and interactions, see hytale-items.

Quick Reference

Prerequisites

Enable Asset Packs

Your plugin's manifest.json must declare asset pack inclusion:

{
  "IncludesAssetPack": true,
  "dependencies": ["Hytale:EntityModule", "Hytale:BlockModule"]
}

Folder Structure

src/main/resources/
├── manifest.json
├── Server/
│   ├── Item/
│   │   └── Items/
│   │       └── my_new_block.json       # Block definition
│   └── Languages/
│       └── en-US/
│           └── items.lang              # Translations
└── Common/
    ├── Icons/                          # Item icons
    ├── Blocks/
    │   └── my_new_block/
    │       └── model.blockymodel       # Block model
    └── BlockTextures/
        └── my_new_block.png            # Block texture

Translations

Create Server/Languages/en-US/items.lang:

my_new_block.name = My New Block
my_new_block.description = My Description

The filename items becomes the translation key prefix, so "items.my_new_block.name" resolves to My New Block.

Block JSON Definition

Create Server/Item/Items/my_new_block.json:

{
  "TranslationProperties": {
    "Name": "items.my_new_block.name",
    "Description": "items.my_new_block.description"
  },
  "Id": "My_New_Block",
  "MaxStack": 100,
  "Icon": "Icons/ItemsGenerated/my_new_block.png",
  "Categories": [
    "Blocks.Rocks"
  ],
  "PlayerAnimationsId": "Block",
  "Set": "Rock_Stone",
  "BlockType": {
    "Material": "Solid",
    "DrawType": "Cube",
    "Group": "Stone",
    "Flags": {},
    "Gathering": {
      "Breaking": {
        "GatherType": "Rocks",
        "ItemId": "my_new_block"
      }
    },
    "BlockParticleSetId": "Stone",
    "Textures": [
      {
        "All": "BlockTextures/my_new_block.png"
      }
    ],
    "ParticleColor": "#aeae8c",
    "BlockSoundSetId": "Stone",
    "BlockBreakingDecalId": "Breaking_Decals_Rock"
  },
  "ResourceTypes": [
    {
      "Id": "Rock"
    }
  ]
}

BlockType Properties

Texture Configuration

Textures are defined as an array of objects. Use "All" to apply one texture to all faces, or specify per-face:

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

Per-face texturing (when supported):

"Textures": [
  {
    "Top": "BlockTextures/my_block_top.png",
    "Bottom": "BlockTextures/my_block_bottom.png",
    "Side": "BlockTextures/my_block_side.png"
  }
]

Item Properties (Top-Level)

These properties are standard item fields that the block also uses:

Edge Cases & Gotchas

• All referenced files (textures, models, icons) must exist at the specified paths or the block will fail to load
• The Id field is case-sensitive and must be unique across all items and blocks
• Translation keys follow the pattern <lang-filename>.<key>.name — the .lang filename is the prefix
• IncludesAssetPack must be true in manifest — without it, Common/ assets are ignored
• Block textures go in Common/BlockTextures/, not Common/Textures/
• The ItemId in Gathering.Breaking should match the block's Id for the block to drop itself when broken
• Check lib/Server/ for existing block definitions to see all available property values