Skip to main content
The Blocks surface provides operations for placing, reading, and asserting on blocks in the world. BlockTestAdapter handles block manipulation, while BlockAssert offers targeted checks for material, state, group, and trigger properties. Blocks are the building material of Hytale worlds. Every surface, structure, and terrain feature is made of block types. If your mod adds custom blocks, modifies block behavior, or builds structures programmatically, you need tests to verify that blocks have the correct material properties, belong to the right groups, and respond to triggers as expected.
Block type IDs use the asset name without a namespace prefix (e.g., Soil_Dirt not hytale:dirt). The exact block names available depend on the game version and installed content packs. Use BlockTestAdapter.blockTypeExists(id) to check if a block type is available before testing with it.

​
Block Type Asset System

Blocks in Hytale are defined as assets identified by their asset name (like "Rock_Sandstone" or "Soil_Dirt"). Each block type has properties defined in its asset file:
  • Material - The physical material type (stone, wood, dirt, etc.) which affects tool interactions, sounds, and particle effects
  • State - Block state variants (default, powered, open, etc.) that change behavior without changing the block type
  • Group - Logical groups the block belongs to (ores, transparent, vegetation, etc.) used for batch queries
  • Trigger - Whether the block acts as a trigger block for game logic (pressure plates, tripwires, etc.)
BlockAssert lets you verify all of these properties in your tests.

​
Complete Example Suite

package com.example.tests;

import com.frotty27.hrtk.api.annotation.HytaleSuite;
import com.frotty27.hrtk.api.annotation.WorldTest;
import com.frotty27.hrtk.api.annotation.Tag;
import com.frotty27.hrtk.api.annotation.DisplayName;
import com.frotty27.hrtk.api.annotation.Order;
import com.frotty27.hrtk.api.assert_.BlockAssert;
import com.frotty27.hrtk.api.assert_.HytaleAssert;
import com.frotty27.hrtk.api.assert_.WorldAssert;
import com.frotty27.hrtk.api.context.WorldTestContext;
import com.frotty27.hrtk.api.lifecycle.IsolationStrategy;
import com.hypixel.hytale.server.core.asset.type.blocktype.config.BlockType;

@HytaleSuite(value = "Block Surface Tests", isolation = IsolationStrategy.DEDICATED_WORLD)
@Tag("blocks")
public class BlockSurfaceTests {

    @WorldTest
    @Order(1)
    @DisplayName("Place a stone block and verify its material")
    void placeAndVerifyMaterial(WorldTestContext ctx) {
        ctx.setBlock(5, 64, 5, "Rock_Sandstone");

        Object blockType = BlockType.fromString("Rock_Sandstone");
        BlockAssert.assertBlockMaterial(blockType, "stone");
    }

    @WorldTest
    @Order(2)
    @DisplayName("Verify block state is 'default' after placement")
    void blockStateIsDefault(WorldTestContext ctx) {
        ctx.setBlock(10, 64, 10, "Rock_Sandstone");

        Object blockType = BlockType.fromString("Rock_Sandstone");
        BlockAssert.assertBlockState(blockType, "default");
    }

    @WorldTest
    @Order(3)
    @DisplayName("Verify trigger block is detected correctly")
    void triggerBlockIsDetected(WorldTestContext ctx) {
        ctx.setBlock(15, 64, 15, "Pressure_Plate");

        Object blockType = BlockType.fromString("Pressure_Plate");
        BlockAssert.assertBlockIsTrigger(blockType);
    }

    @WorldTest
    @Order(4)
    @DisplayName("Verify block group membership")
    void blockBelongsToGroup(WorldTestContext ctx) {
        ctx.setBlock(20, 64, 20, "Iron_Ore");

        Object blockType = BlockType.fromString("Iron_Ore");
        BlockAssert.assertBlockGroup(blockType, "ores");
    }

    @WorldTest
    @Order(5)
    @DisplayName("Place blocks in a region and verify corners")
    void fillRegionAndVerify(WorldTestContext ctx) {
        // fillRegion is batched into a single world-thread dispatch.
        // This means the entire region is consistent when you assert.
        ctx.fillRegion(0, 60, 0, 10, 60, 10, "Grass_Full");

        WorldAssert.assertBlockAt(ctx.getWorld(), 0, 60, 0, "Grass_Full");
        WorldAssert.assertBlockAt(ctx.getWorld(), 10, 60, 10, "Grass_Full");
        WorldAssert.assertBlockAt(ctx.getWorld(), 5, 60, 5, "Grass_Full");
    }

    @WorldTest
    @Order(6)
    @DisplayName("Replacing a block changes its type")
    void replacingBlockChangesType(WorldTestContext ctx) {
        ctx.setBlock(25, 64, 25, "Rock_Sandstone");
        WorldAssert.assertBlockAt(ctx.getWorld(), 25, 64, 25, "Rock_Sandstone");

        // Overwrite the stone with dirt.
        ctx.setBlock(25, 64, 25, "Soil_Dirt");
        WorldAssert.assertBlockAt(ctx.getWorld(), 25, 64, 25, "Soil_Dirt");
        WorldAssert.assertBlockNotAt(ctx.getWorld(), 25, 64, 25, "Rock_Sandstone");
    }

    @WorldTest
    @Order(7)
    @DisplayName("Read block type at coordinates")
    void readBlockType(WorldTestContext ctx) {
        ctx.setBlock(30, 64, 30, "Rock_Sandstone");

        String blockType = ctx.getBlock(30, 64, 30);
        HytaleAssert.assertEquals("Rock_Sandstone", blockType);
    }
}

​
Adapter Methods

MethodParametersReturnsDescription
setBlockint x, int y, int z, String typeIdvoidPlace a block at the given coordinates
getBlockint x, int y, int zStringGet the block type ID at coordinates
fillRegionint x1, int y1, int z1, int x2, int y2, int z2, String typeIdvoidFill a cuboid region with the specified block type
getBlockMaterialObject blockTypeStringGet the material name of a block type
getBlockStateObject blockTypeStringGet the default state key of a block type
isBlockTriggerObject blockTypebooleanCheck if a block type is a trigger block

​
Assertion Methods

MethodParametersFailure Message
assertBlockMaterialObject blockType, String expected”Expected block material [expected] but was [actual]“
assertBlockIsTriggerObject blockType”Expected block to be a trigger but isTrigger() returned false”
assertBlockStateObject blockType, String expected”Expected block default state [expected] but was [actual]“
assertBlockGroupObject blockType, String groupName”Expected block group [groupName] but was [actual]“

​
BlockAssert vs WorldAssert

Use WorldAssert.assertBlockAt() for simple type-ID checks (is this block stone?). Use BlockAssert when you need material-level, state-level, or group-level detail.
Pair block tests with IsolationStrategy.DEDICATED_WORLD so block changes do not affect the live server. The dedicated world starts as a void world, giving you a clean slate for every suite.

​
Next Steps

  • World Testing - entity spawning and positioning
  • Items - test item stacks and durability
  • Physics - test entity movement on blocks