HyTale Plugin Development Documentation

Interní dokumentace pro vývoj Hytale server-side pluginů.

Struktura

HyTale-Docs/
├── README.md                           # Tento soubor
│
├── threading/                          # Thread safety a synchronizace
│   ├── README.md
│   └── THREAD_SAFETY_GUIDELINES.md
│
├── events/                             # Event systém (31 eventů)
│   ├── README.md
│   ├── PLAYER_EVENTS.md                # 13 player eventů
│   ├── ECS_EVENTS.md                   # 7 ECS eventů
│   ├── WORLD_EVENTS.md                 # 7 world eventů
│   └── INVENTORY_EVENTS.md             # 4 inventory eventy
│
├── commands/                           # Command systém
│   ├── README.md
│   ├── COMMAND_TYPES.md                # 4 typy příkazů
│   └── ARGUMENTS.md                    # ArgTypes reference
│
├── ecs/                                # ECS architektura
│   ├── README.md
│   ├── COMPONENTS.md                   # Komponenty
│   └── SYSTEMS.md                      # Systémy
│
├── messages/                           # Message API
│   └── README.md                       # Zprávy, překlady, barvy
│
├── configuration/                      # Konfigurace
│   └── README.md                       # BSON/JSON, codecs
│
├── teleportation/                      # Teleportace
│   └── README.md                       # Teleport, spawn, warpy
│
├── lifecycle/                          # Plugin lifecycle
│   └── README.md                       # setup(), start(), shutdown()
│
├── permissions/                        # Oprávnění
│   └── README.md                       # Permission systém
│
├── player-data/                        # Data hráčů
│   └── README.md                       # Ukládání, cache, persistence
│
├── assets/                             # Game assets
│   └── README.md                       # Modely, markery, entity
│
├── ui/                                 # Custom UI
│   └── README.md                       # UI komponenty
│
├── networking/                         # Síťování
│   └── README.md                       # Pakety, synchronizace
│
├── manifest/                           # Plugin manifest
│   └── README.md                       # manifest.json, závislosti
│
├── scheduler/                          # Tasky a plánování
│   └── README.md                       # Periodické a delayed tasky
│
├── blocks-items/                       # Bloky a itemy
│   └── README.md                       # BlockType, ItemStack
│
├── debugging/                          # Debugging
│   └── README.md                       # Logging, řešení problémů
│
├── entities-npc/                       # Entity a NPC
│   └── README.md                       # Spawn, komponenty
│
├── effects/                            # Efekty a buffy
│   └── README.md                       # EffectController
│
├── combat/                             # Bojový systém
│   └── README.md                       # Damage, Death, DamageModule
│
└── best-practices/                     # Best practices
    └── README.md                       # Souhrn doporučení

Rychlý Přehled

Hytale vs Minecraft

| Aspekt | Minecraft | Hytale |
|--------|-----------|--------|
| Threading | Single-threaded | Multi-threaded |
| Architektura | Event-driven OOP | ECS (Entity Component System) |
| Světy | Jeden tick thread | Každý World má vlastní thread |
| Komponenty | Přímý přístup | Přes Store, thread-safe |

Klíčová Pravidla

1. Používej AbstractPlayerCommand pro příkazy s přístupem ke komponentům
2. Používej world.execute() pro async → sync přechody
3. Používej EntityEventSystem pro ECS eventy (BreakBlockEvent, DeathEvent)
4. Používej registerAsync() pro async eventy (PlayerChatEvent)
5. Nikdy neblokuj world thread s I/O nebo sleep

Event Typy

| Typ | Registrace | Příklad |
|-----|------------|---------|
| Sync | register() | PlayerReadyEvent |
| Async | registerAsync() | PlayerChatEvent |
| ECS | EntityEventSystem | BreakBlockEvent |

Package Names

Skutečné package v Hytale serveru (ne z dokumentace):

com.hypixel.hytale.server.core.plugin.JavaPlugin
com.hypixel.hytale.server.core.command.system.*
com.hypixel.hytale.server.core.entity.entities.Player
com.hypixel.hytale.server.core.universe.world.World
com.hypixel.hytale.component.*

Zdroje

Online

• Oficiální dokumentace


• Thread Safety


• Event System


• ECS Architecture

Lokální



• Dekompilovaný kód: TeraFlex/decompiled/com/hypixel/hytale/


• Assets: Assets/Server/ a Assets/Common/

Příklad: Minimální Plugin

package com.example;
import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import com.hypixel.hytale.server.core.entity.entities.Player;
import com.hypixel.hytale.server.core.Message;
public class ExamplePlugin extends JavaPlugin {
    private static ExamplePlugin instance;
    public ExamplePlugin(JavaPluginInit init) {
        super(init);
    }
    public static ExamplePlugin get() {
        return instance;
    }
    @Override
    protected void setup() {
        instance = this;
        // Sync event
        getEventRegistry().registerGlobal(PlayerReadyEvent.class, event -> {
            Player player = event.getPlayer();
            player.sendMessage(Message.raw("Vítej!"));
        });
        // Async event
        getEventRegistry().registerAsyncGlobal(PlayerChatEvent.class, future -> {
            future.thenAccept(event -> {
                getLogger().atInfo().log("Chat: " + event.getMessage());
            });
        });
        // ECS system
        getEntityStoreRegistry().registerSystem(new MyBlockBreakSystem());
    }
    @Override
    protected void start() {
        getLogger().atInfo().log("Plugin started!");
    }
    @Override
    protected void shutdown() {
        getLogger().atInfo().log("Plugin shutdown!");
    }
}