Skip to content
Hytale Modding Manual

Block Definitions

Overview

Block definitions describe the visual and physical properties of blocks placed in the world. Most block data lives inside the BlockType object of an item definition file, but standalone block files exist for fluids, fluid effects, and breaking decals. Textures can be specified per-face or as a single All shorthand, with optional Weight values for randomized variants.

File Location

Block data is stored in two places:

  • Item-embedded blocks (rocks, wood, soil, etc.): BlockType object inside Assets/Server/Item/Items/<Category>/<ItemId>.json
  • Standalone block files (fluids, decals, fluid effects): Assets/Server/Item/Block/<Subcategory>/<BlockId>.json

Subcategories under Assets/Server/Item/Block/:

Block/Fluids/          — Fluid blocks (Lava, Water, Slime, Poison, Fire)
Block/BreakingDecals/  — Break-animation crack overlays
Block/FluidFX/         — Fluid visual effect configs
Block/Hitboxes/        — Custom hitbox shape definitions
Block/Blocks/_Debug/   — Debug-only test blocks

Schema

Texture Object Fields

Each entry in the Textures array defines one texture variant. Multiple entries with Weight values enable random texture selection.

FieldTypeRequiredDefaultDescription
AllstringNo—Texture path applied to all six faces of the block.
SidesstringNo—Texture applied to the four side faces (North, South, East, West).
UpDownstringNo—Texture applied to top and bottom faces.
TopstringNo—Texture applied to the top face only.
BottomstringNo—Texture applied to the bottom face only.
NorthstringNo—Texture applied to the north face only.
SouthstringNo—Texture applied to the south face only.
EaststringNo—Texture applied to the east face only.
WeststringNo—Texture applied to the west face only.
WeightnumberNo1Relative probability weight for this variant when multiple texture entries are present.

BlockType / Block-Level Fields

FieldTypeRequiredDefaultDescription
Texturesobject[]No—Array of texture variant objects (see above).
MaterialstringNo—Physical material category. Values: Solid, Fluid, Empty, Plant. Controls collision and interaction behavior.
DrawTypestringNo—Rendering mode. Common values: Model (custom mesh), Block (standard cube), Plant (billboard foliage).
OpacitystringNo—Transparency level. Values: Opaque, Semitransparent, Transparent.
LightobjectNo—Light emission config. Contains Color (hex string, e.g. "#e90") and optionally Level (number).
ParticleColorstringNo—Hex color for block-break particle effects (e.g. "#58ad9b").
CustomModelstringNo—Path to a .blockymodel file used instead of a standard cube mesh.
CustomModelTextureobject[]No—Array of { "Texture": "<path>", "Weight": <number> } for custom model texture variants.
CustomModelScalenumberNo1.0Scale multiplier for the custom model.
HitboxTypestringNo—ID of a hitbox definition from Block/Hitboxes/.
RandomRotationstringNo—Rotation randomization when placed. Example: "YawStep1".
BlockParticleSetIdstringNo—Particle set used for ambient block particles (e.g. "Lava", "Dust").
BlockSoundSetIdstringNo—Sound set ID for block interaction sounds.
GatheringobjectNo—Harvesting configuration. Child objects Harvest, Soft, and Breaking each accept a GatherType string.
Aliasesstring[]No—Alternative string IDs for this block, used by commands and world generation.

Fluid-Specific Fields

These fields appear in standalone fluid block files under Block/Fluids/.

FieldTypeRequiredDefaultDescription
MaxFluidLevelnumberNo—Maximum fluid level integer. Source blocks typically use 1; flowing fluids use 8.
Effectstring[]No—List of effect IDs applied when an entity enters this fluid (e.g. ["Lava"]).
FluidFXIdstringNo—References a fluid visual effect config from Block/FluidFX/.
TickerobjectNo—Fluid flow behavior. Contains CanDemote (boolean), SpreadFluid (string), FlowRate (number), SupportedBy (string), and Collisions (object mapping block IDs to placement results).
InteractionsobjectNo—Block-level interaction chains (e.g. collision effects). Uses the same chain format as item interactions.
ParentstringNo—ID of a parent block to inherit fields from.

Example

Assets/Server/Item/Items/Rock/Rock_Aqua.json (BlockType section):

{
  "TranslationProperties": {
    "Name": "server.items.Rock_Aqua.name"
  },
  "Icon": "Icons/ItemsGenerated/Rock_Aqua.png",
  "Parent": "Rock_Stone",
  "BlockType": {
    "Textures": [
      {
        "All": "BlockTextures/Rock_Aqua.png",
        "Weight": 1
      }
    ],
    "ParticleColor": "#58ad9b",
    "Gathering": {
      "Breaking": {
        "GatherType": "Rocks"
      }
    },
    "Aliases": [
      "aqua",
      "aqua00"
    ]
  }
}

Assets/Server/Item/Block/Blocks/_Debug/Debug_Test_Block.json (standalone block with light):

{
  "Textures": [
    {
      "All": "Blocks/_Debug/Texture.png"
    }
  ],
  "Material": "Solid",
  "Light": {
    "Color": "#f0f"
  }
}

Assets/Server/Item/Block/Fluids/Lava_Source.json (fluid block):

{
  "MaxFluidLevel": 1,
  "Effect": ["Lava"],
  "Opacity": "Transparent",
  "Textures": [
    {
      "Weight": 1,
      "All": "BlockTextures/Fluid_Lava.png"
    }
  ],
  "Light": {
    "Color": "#e90"
  },
  "Ticker": {
    "CanDemote": false,
    "SpreadFluid": "Lava",
    "FlowRate": 2.0,
    "Collisions": {
      "Water": {
        "BlockToPlace": "Rock_Stone_Cobble",
        "SoundEvent": "SFX_Flame_Break"
      }
    }
  }
}