HyCodeYourTale
Official Docs

Block Types

Block Types

Detailní dokumentace k typům bloků a blok systému v Hytale.

---

Přehled Architektury

Block System
    │
    ├── BlockType (Asset definition)
    │   ├── Id, DrawType, Material
    │   ├── Textures, Model
    │   └── State, BlockEntity
    │
    ├── BlockState (ECS Component - DEPRECATED)
    │   ├── Position in chunk
    │   └── Custom data per block
    │
    ├── BlockModule (Plugin)
    │   ├── BlockStateInfo component
    │   └── Block entity management
    │
    └── Block Events
        ├── BreakBlockEvent
        ├── PlaceBlockEvent
        └── UseBlockEvent

---

BlockType

Definice typu bloku z assets:

public class BlockType implements JsonAssetWithMap>,
                                  NetworkSerializable {
    // Asset CODEC pro načítání z JSON
    public static final AssetBuilderCodec CODEC;
    // Základní vlastnosti
    protected String id;
    protected String group;
    protected DrawType drawType;           // Cube, Cross, etc.
    protected BlockMaterial material;      // Stone, Wood, Metal, etc.
    protected Opacity opacity;             // Solid, Transparent, etc.
    // Textury a model
    protected BlockTypeTextures[] textures;
    protected String customModel;
    protected CustomModelTexture[] customModelTexture;
    // Fyzika a interakce
    protected BlockBoundingBoxes boundingBoxes;
    protected RootInteraction interaction;
    protected StateData state;
    // Block entity (ECS data)
    protected Holder blockEntity;
    // Zvuky a částice
    protected String blockSoundSetId;
    protected BlockParticleSet blockParticleSet;
}

Získání BlockType

// Z eventu
BlockType blockType = event.getBlockType();
// Z asset mapy
BlockTypeAssetMap assetMap = BlockType.getAssetMap();
BlockType stone = assetMap.getAsset("Stone");
// Z ID
BlockType blockType = BlockType.getAssetMap().getAsset(blockId);
// Kontrola prázdného bloku
if (blockType == BlockType.EMPTY || blockType.isUnknown()) {
    return;  // Prázdný blok nebo neznámý
}

BlockType Properties

// ID bloku
String id = blockType.getId();
// Materiál
BlockMaterial material = blockType.getMaterial();  // STONE, WOOD, METAL...
// Draw type
DrawType drawType = blockType.getDrawType();  // CUBE, CROSS, MODEL...
// Opacity
Opacity opacity = blockType.getOpacity();  // SOLID, TRANSPARENT...
// Group
String group = blockType.getGroup();
// Má state/block entity
boolean hasState = blockType.getState() != null;
boolean hasBlockEntity = blockType.getBlockEntity() != null;

---

DrawType

Typy vykreslování bloků:

public enum DrawType {
    CUBE,           // Standardní kostka
    CROSS,          // Křížový (tráva, květiny)
    MODEL,          // Custom 3D model
    NONE,           // Neviditelný
    SIMPLE_CROSS,   // Jednoduchý kříž
    SIMPLE_CUBE,    // Jednoduchá kostka
    WATER,          // Tekutina
    GRASS           // Speciální tráva
}

---

BlockMaterial

Materiály bloků ovlivňující zvuky, nástroje, a fyziku:

public enum BlockMaterial {
    STONE,
    WOOD,
    METAL,
    DIRT,
    SAND,
    GLASS,
    CLOTH,
    PLANT,
    WATER,
    LAVA,
    ICE,
    SNOW,
    // ... další
}

---

BlockState (Deprecated)

BlockState je starší systém pro ukládání dat per-block. Nově se používají ECS komponenty.

@Deprecated(forRemoval = true)
public abstract class BlockState implements Component {
    public static final CodecMapCodec CODEC;
    // Pozice v chunku (0-31, y, 0-31)
    private Vector3i position;
    // Reference na ECS entitu
    protected Ref reference;
    // Chunk ve kterém je blok
    private WorldChunk chunk;
    // Metody
    public Vector3i getPosition() { ... }
    public Vector3i getBlockPosition() { ... }  // Světové souřadnice
    public BlockType getBlockType() { ... }
    public int getRotationIndex() { ... }
    public void markNeedsSave() { ... }
}

Vytvoření BlockState

// Zajištění BlockState na pozici
BlockState state = BlockState.ensureState(worldChunk, x, y, z);
// Načtení z dokumentu
BlockState state = BlockState.load(bsonDoc, chunk, position);

---

BlockModule

Plugin pro správu bloků:

public class BlockModule extends JavaPlugin {
    public static final PluginManifest MANIFEST = PluginManifest.corePlugin(BlockModule.class)
        .depends(LegacyModule.class)
        .build();
    // Singleton
    public static BlockModule get() { return instance; }
    // Component types
    public ComponentType getLaunchPadComponentType();
    public ComponentType getRespawnBlockComponentType();
    public ComponentType getBlockMapMarkerComponentType();
    public ComponentType getBlockStateInfoComponentType();
    // Resource types
    public ResourceType getBlockMapMarkersResourceType();
}

Získání Block Entity

// Získání reference na block entity
Ref blockRef = BlockModule.getBlockEntity(world, x, y, z);
// Získání komponenty z block entity
LaunchPad launchPad = BlockModule.get().getComponent(
    BlockModule.get().getLaunchPadComponentType(),
    world, x, y, z
);

BlockStateInfo

Info komponenta pro block entities:

public static class BlockStateInfo implements Component {
    private final int index;  // Index v chunku
    private final Ref chunkRef;
    public static ComponentType getComponentType() {
        return BlockModule.get().getBlockStateInfoComponentType();
    }
    public int getIndex() { return index; }
    public Ref getChunkRef() { return chunkRef; }
    public void markNeedsSaving() { ... }
}

---

Block Events

BreakBlockEvent

public class BlockBreakSystem extends EntityEventSystem {
    @Override
    public void handle(int i, ArchetypeChunk chunk,
                       Store store, CommandBuffer buffer,
                       BreakBlockEvent event) {
        // DŮLEŽITÉ: Vždy kontroluj EMPTY
        if (event.getBlockType() == BlockType.EMPTY) return;
        // Informace o bloku
        BlockType blockType = event.getBlockType();
        String blockId = blockType.getId();
        BlockMaterial material = blockType.getMaterial();
        // Hráč
        Ref ref = chunk.getReferenceTo(i);
        Player player = store.getComponent(ref, Player.getComponentType());
        if (player != null) {
            player.sendMessage(Message.raw("Rozbit blok: " + blockId));
            // Zrušení rozbití
            // event.cancel();
        }
    }
    @Override
    public Query getQuery() {
        return PlayerRef.getComponentType();
    }
}

PlaceBlockEvent

public class BlockPlaceSystem extends EntityEventSystem {
    @Override
    public void handle(int i, ArchetypeChunk chunk,
                       Store store, CommandBuffer buffer,
                       PlaceBlockEvent event) {
        Ref ref = chunk.getReferenceTo(i);
        Player player = store.getComponent(ref, Player.getComponentType());
        if (player != null) {
            // Zrušení položení
            // event.cancel();
        }
    }
    @Override
    public Query getQuery() {
        return PlayerRef.getComponentType();
    }
}

UseBlockEvent

public class BlockUseSystem extends EntityEventSystem {
    @Override
    public void handle(int i, ArchetypeChunk chunk,
                       Store store, CommandBuffer buffer,
                       UseBlockEvent event) {
        // Interakce s blokem (truhla, dveře, tlačítko...)
        Ref ref = chunk.getReferenceTo(i);
        Player player = store.getComponent(ref, Player.getComponentType());
        if (player != null) {
            // Zpracování interakce
        }
    }
    @Override
    public Query getQuery() {
        return PlayerRef.getComponentType();
    }
}

---

Vestavěné Block Components

LaunchPad

public class LaunchPad {
    public static final BuilderCodec CODEC;
    public static ComponentType getComponentType() {
        return BlockModule.get().getLaunchPadComponentType();
    }
    // Získání
    LaunchPad pad = BlockModule.get().getComponent(
        LaunchPad.getComponentType(), world, x, y, z
    );
}

RespawnBlock

public class RespawnBlock {
    public static final BuilderCodec CODEC;
    public static ComponentType getComponentType() {
        return BlockModule.get().getRespawnBlockComponentType();
    }
}

BlockMapMarker

public class BlockMapMarker {
    public static final BuilderCodec CODEC;
    public static ComponentType getComponentType() {
        return BlockModule.get().getBlockMapMarkerComponentType();
    }
}

---

Block Asset JSON

Bloky jsou definovány v asset souborech:

{
    "Id": "Stone",
    "Group": "Natural",
    "DrawType": "Cube",
    "Material": "Stone",
    "Opacity": "Solid",
    "Textures": [
        {
            "Side": "All",
            "Texture": "Blocks/Stone.png"
        }
    ],
    "BoundingBoxes": {
        "Type": "FullBlock"
    },
    "BlockSoundSetId": "BSS_Stone"
}

S Custom Model

{
    "Id": "Torch",
    "DrawType": "Model",
    "CustomModel": "Models/Blocks/Torch.fbx",
    "Opacity": "Transparent",
    "Light": {
        "Color": [255, 200, 100],
        "Intensity": 14
    }
}

S Block Entity

{
    "Id": "Chest",
    "DrawType": "Model",
    "CustomModel": "Models/Blocks/Chest.fbx",
    "State": {
        "Id": "ItemContainerState"
    },
    "Interaction": {
        "Type": "OpenContainer"
    }
}

---

Práce s WorldChunk

// Získání bloku z chunku
WorldChunk chunk = world.getChunk(chunkX, chunkZ);
BlockType blockType = chunk.getBlockType(localX, y, localZ);
// Nastavení bloku
chunk.setBlockType(localX, y, localZ, newBlockType);
// Rotace bloku
int rotation = chunk.getRotationIndex(localX, y, localZ);
chunk.setRotationIndex(localX, y, localZ, newRotation);
// Block component entity
Ref blockRef = chunk.getBlockComponentEntity(localX, y, localZ);

---

Shrnutí

| Třída | Účel |
|-------|------|
| BlockType | Asset definice typu bloku |
| BlockState | Per-block data (deprecated) |
| BlockModule | Plugin pro block management |
| BlockStateInfo | ECS komponenta pro block entity |
| WorldChunk | Chunk obsahující bloky |

| Event | Popis | Cancellable |
|-------|-------|-------------|
| BreakBlockEvent | Rozbití bloku | Ano |
| PlaceBlockEvent | Položení bloku | Ano |
| UseBlockEvent | Interakce s blokem | Ano |
| DamageBlockEvent | Poškození bloku | Ano |

| Property | Popis |
|----------|-------|
| DrawType | Způsob vykreslení (CUBE, MODEL...) |
| Material | Materiál (STONE, WOOD...) |
| Opacity | Průhlednost (SOLID, TRANSPARENT...) |
| BoundingBoxes | Kolizní boxy |
| State | BlockState definice |
| BlockEntity | ECS holder pro block data |

Last updated: 20. ledna 2026