Block API

Blocks are accessed through World, WorldChunk, or the BlockAccessor interface. See Chunks for chunk access and indexing.

Reading Blocks

// get block ID at position
int blockId = world.getBlock(x, y, z);

// get BlockType (asset)
BlockType blockType = world.getBlockType(x, y, z);

// get block from chunk (local coordinates)
WorldChunk chunk = world.getChunk(chunkIndex);
int blockId = chunk.getBlock(x, y, z);

Setting Blocks

// simple block placement (via World)
world.setBlock(x, y, z, "hytale:stone");

// with settings flags
world.setBlock(x, y, z, "hytale:stone", settings);

// via chunk with BlockType (full control: id, rotation, filler, settings)
WorldChunk chunk = world.getChunk(ChunkUtil.indexChunkFromBlock(x, z));
chunk.setBlock(x, y, z, blockId, blockType, rotationIndex, filler, settings);

SetBlockSettings Flags

Combine flags with bitwise OR (|):

Flag	Value	Effect
`NO_NOTIFY`	1	Skip neighbor notifications
`NO_UPDATE_STATE`	2	Don’t update block state
`NO_SEND_PARTICLES`	4	Skip particle effects
`NO_SET_FILLER`	8	Skip filler block logic
`NO_BREAK_FILLER`	16	Don’t break filler blocks
`PHYSICS`	32	Enable physics
`FORCE_CHANGED`	64	Force change notification
`NO_UPDATE_NEIGHBOR_CONNECTIONS`	128	Skip neighbor connection updates
`PERFORM_BLOCK_UPDATE`	256	Trigger block update event
`NO_UPDATE_HEIGHTMAP`	512	Skip heightmap recalculation
`NO_SEND_AUDIO`	1024	Skip block sounds
`NO_DROP_ITEMS`	2048	Don’t drop items when breaking

For bulk operations, combine flags to minimize updates:

int bulkFlags = SetBlockSettings.NO_NOTIFY
    | SetBlockSettings.NO_SEND_PARTICLES
    | SetBlockSettings.NO_SEND_AUDIO;

See Bulk Operations for large-scale editing patterns.

Breaking Blocks

// break block at position (settings = 0 for defaults)
world.breakBlock(x, y, z, 0);

// with custom settings
world.breakBlock(x, y, z, settings);

When a player breaks a block, BreakBlockEvent fires as an ECS event. In adventure mode, DamageBlockEvent fires on each hit first — BreakBlockEvent only fires when the block’s health reaches zero. In creative mode, BreakBlockEvent fires immediately with no damage phase.

Block Placement Validation

// test if block can be placed
boolean canPlace = chunk.testPlaceBlock(x, y, z, blockType, rotationIndex);

// place with validation
boolean placed = chunk.placeBlock(x, y, z, "hytale:chair",
    Rotation.DEG_0, Rotation.DEG_0, Rotation.DEG_0, settings);

When a player places a block, PlaceBlockEvent fires as a cancellable ECS event. When a player uses a block (e.g. opening a door), UseBlockEvent fires with Pre and Post phases.

BlockType

Package: com.hypixel.hytale.server.core.asset.type.blocktype.config

Block type definitions loaded from JSON assets.

Accessing BlockTypes

// get asset map
BlockTypeAssetMap<String, BlockType> assetMap = BlockType.getAssetMap();

// get by string ID
BlockType stone = assetMap.getAsset("hytale:stone");

// get by numeric index
BlockType blockType = assetMap.getAsset(blockId);

// get numeric index from string ID
int index = assetMap.getIndex("hytale:stone");

Key Properties

Method	Return Type	Description
`getId()`	`String`	Asset ID (e.g., `"hytale:stone"`)
`getGroup()`	`String`	Block group for categorization
`getMaterial()`	`BlockMaterial`	Physical material type
`getOpacity()`	`Opacity`	Light blocking behavior
`getDrawType()`	`DrawType`	Rendering style (`Empty`, `Cube`, `Model`, `CubeWithModel`, `GizmoCube`)
`getParticleColor()`	`Color`	Block color used for map rendering and particles
`getLight()`	`ColorLight`	Light emission for emissive blocks
`getTextures()`	`BlockTypeTextures[]`	Per-face texture paths
`getCustomModel()`	`String`	Custom model path for `Model`/`CubeWithModel` draw types
`getHitboxTypeIndex()`	`int`	Index into hitbox asset map
`hasSupport()`	`boolean`	Whether block uses physics support
`isUnknown()`	`boolean`	True for missing/invalid blocks

Special Values

// empty block (air)
BlockType.EMPTY

// check if empty
if (blockType == BlockType.EMPTY || blockType.getMaterial() == BlockMaterial.Empty) {
    // air or passable
}