Hytale Custom Blocks

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

Block Entities vs. Plain Blocks

Not every block has a "block entity" (a ChunkStore ECS entity with components). Plain blocks are just block IDs in the chunk data. A block entity only exists when one has been explicitly created for that position \u2014 either by the engine (for blocks with engine-managed state) or by a plugin.

• BlockModule.getBlockEntity(world, x, y, z) \u2014 lookup only. Returns null for plain blocks. Never auto-creates.
• To attach custom data to a plain block you must create the entity manually. See the hytale-ecs skill \u2014 "Block Entity Lookup and Creation".
• To react to a block component's lifecycle (add/remove), use RefChangeSystem<ChunkStore, YourComponent>.

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"
    }
  ]
}

Animated Blocks

To create blocks with animated textures, you use a custom model and an animation file instead of static textures. This involves setting DrawType to "Model" and providing paths to your assets.

For a complete guide, see the Animated Block Textures reference.

BlockType Properties

Texture Configuration

For DrawType: "Cube", 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:

Querying Block Data at Runtime

BlockChunk (obtained via chunkStore.getComponent(chunkRef, BlockChunk.getComponentType())) provides palette-based query methods that are O(unique block types), not O(chunk volume):

// Count all blocks of a specific type in this chunk (palette-based, cheap)
int count = blockChunk.count(blockTypeIndex);

// Map of blockTypeIndex → count for every type present (iterate unique types only)
Int2IntMap counts = blockChunk.blockCounts();

// Set of all block type indices present in the chunk
IntSet presentTypes = blockChunk.blocks();

// Fast existence check — no iteration
boolean hasWood = blockChunk.contains(blockTypeIndex);

Use these to cheaply detect whether a chunk's content has changed (e.g. compare a cached count against the current value) before doing an expensive per-block scan.

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