Hytale Server

https://hytale-docs.pages.dev
Admin
Hytale Server is a dedicated game server for the Hytale game, enabling players to host, configure,...
Tokens:259,311
Snippets:2,183
Trust Score:7.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### MyPlugin quick start example

Source: https://hytale-docs.pages.dev/modding/plugins

Minimal plugin class extending JavaPlugin. Overrides setup(), start(), and shutdown() lifecycle methods, logging messages at INFO level. Requires a JavaPluginInit argument in the constructor.

```java
package com.example;


import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;


import java.util.logging.Level;


public class MyPlugin extends JavaPlugin {


    public MyPlugin(JavaPluginInit init) {
        super(init);
    }


    @Override
    protected void setup() {
        getLogger().at(Level.INFO).log("Plugin setup!");
    }


    @Override
    protected void start() {
        getLogger().at(Level.INFO).log("Plugin started!");
    }


    @Override
    protected void shutdown() {
        getLogger().at(Level.INFO).log("Plugin shutting down!");
    }
}
```

--------------------------------

### Register system example

Source: https://hytale-docs.pages.dev/modding/ecs/components

Shows how to register a system in the setup() method using getEntityStoreRegistry().registerSystem().

```java
@Override
protected void setup() {
    getEntityStoreRegistry().registerSystem(new HealthRegenSystem(healthComponentType));
}

```

--------------------------------

### ZoneDiscoveryConfig example configurations

Source: https://hytale-docs.pages.dev/modding/worldgen/zones

Shows three example configurations: a major zone with notification, a minor zone without notification, and a partial configuration using the factory method with defaults. The minor zone example uses null for sound and icon, and the factory method defaults major to true, duration to 4.0f, and fade durations to 1.5f.

```java
// Major zone with notification
ZoneDiscoveryConfig forest = new ZoneDiscoveryConfig(
    true,                        // display
    "Emerald Grove",             // zone name
    "zone.forest.discover",      // sound event
    "icons/zone_forest.png",     // icon
    true,                        // major zone
    5.0f,                        // 5 second duration
    2.0f,                        // 2 second fade in
    2.0f                         // 2 second fade out
);


// Minor zone without notification
ZoneDiscoveryConfig cave = new ZoneDiscoveryConfig(
    false,                       // no display
    "Deep Caverns",              // zone name
    null,                        // no sound
    null,                        // no icon
    false,                       // minor zone
    4.0f,                        // duration (unused)
    1.5f,                        // fade in (unused)
    1.5f                         // fade out (unused)
);


// Using the factory method with defaults
ZoneDiscoveryConfig partial = ZoneDiscoveryConfig.of(
    true,                        // display
    "Ancient Ruins",             // zone name
    null,                        // no sound
    null,                        // no icon
    null,                        // default major (true)
    null,                        // default duration (4.0f)
    null,                        // default fade in (1.5f)
    null                         // default fade out (1.5f)
);
```

--------------------------------

### Main plugin class example

Source: https://hytale-docs.pages.dev/modding/plugins/plugin-system

Main plugin class extending JavaPlugin. The constructor takes a JavaPluginInit parameter, and the setup(), start(), and shutdown() methods are overridden to log lifecycle events.

```java
package com.example;


import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import javax.annotation.Nonnull;


public class MyPlugin extends JavaPlugin {


    private static MyPlugin instance;


    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);
    }


    public static MyPlugin get() {
        return instance;
    }


    @Override
    protected void setup() {
        instance = this;
        getLogger().at(Level.INFO).log("Plugin setup complete!");
    }


    @Override
    protected void start() {
        getLogger().at(Level.INFO).log("Plugin started!");
    }


    @Override
    protected void shutdown() {
        getLogger().at(Level.INFO).log("Plugin shutting down!");
    }
}
```

--------------------------------

### Register Command in setup()

Source: https://hytale-docs.pages.dev/modding/plugins/commands

Registers the HelloCommand in the plugin's setup() method using getCommandRegistry().registerCommand().

```java
@Override
protected void setup() {
    getCommandRegistry().registerCommand(new HelloCommand());
}
```

--------------------------------

### Register command, event, and task in setup()

Source: https://hytale-docs.pages.dev/modding/plugins/plugin-system

Overrides setup() to register a command, an event listener for PlayerConnectEvent, an async task, and a log message. Uses the registries available to each plugin.

```java
import com.hypixel.hytale.server.core.event.events.player.PlayerConnectEvent;


@Override
protected void setup() {
    // Commands
    getCommandRegistry().registerCommand(new MyCommand());


    // Events - use PlayerConnectEvent for player connection handling
    getEventRegistry().register(PlayerConnectEvent.class, this::onPlayerConnect);


    // Tasks - register a CompletableFuture<Void> for async operations
    getTaskRegistry().registerTask(myFuture);


    // Logging
    getLogger().at(Level.INFO).log("Setup complete!");
}
```

--------------------------------

### Start Hytale server Windows service with NSSM

Source: https://hytale-docs.pages.dev/server/service

Command to start the HytaleServer service that was installed with NSSM.

```bash
nssm start HytaleServer
```

--------------------------------

### Loading Prefabs with PrefabStore

Source: https://hytale-docs.pages.dev/modding/content/prefabs

Java example showing how to obtain the PrefabStore singleton and load prefabs from server, asset, world generation, any asset pack, directories, and absolute paths. Note that getAssetPrefabFromAnyPack() returns @Nullable and requires null checks, while the other get methods are @Nonnull and throw PrefabLoadException if the file is missing.

```java
import com.hypixel.hytale.server.core.prefab.PrefabStore;
import com.hypixel.hytale.server.core.prefab.selection.standard.BlockSelection;
import java.nio.file.Path;
import java.util.Map;


PrefabStore store = PrefabStore.get();


// Load from different locations (relative to respective base paths)
BlockSelection serverPrefab = store.getServerPrefab("structures/house.prefab.json");
BlockSelection assetPrefab = store.getAssetPrefab("buildings/tower.prefab.json");
BlockSelection worldGenPrefab = store.getWorldGenPrefab("dungeons/cave.prefab.json");


// Load from any asset pack (returns null if not found)
BlockSelection anyPrefab = store.getAssetPrefabFromAnyPack("trees/oak.prefab.json");


// Load all prefabs from a directory
Map<Path, BlockSelection> prefabs = store.getServerPrefabDir("structures/houses");
Map<Path, BlockSelection> assetPrefabs = store.getAssetPrefabDir("buildings");
Map<Path, BlockSelection> worldGenPrefabs = store.getWorldGenPrefabDir("dungeons");


// Load from absolute path (with caching)
BlockSelection customPrefab = store.getPrefab(Path.of("/absolute/path/to/prefab.prefab.json"));
```

--------------------------------

### Register and access a resource

Source: https://hytale-docs.pages.dev/modding/ecs/components

Registers a resource with the entity store registry and accesses it via store.getResource. The example shows the setup method and how to retrieve and use the resource.

```java
private ResourceType<EntityStore, GameStateResource> gameStateType;


@Override
protected void setup() {
    gameStateType = getEntityStoreRegistry().registerResource(
        GameStateResource.class,
        GameStateResource::new
    );
}


// Access in code
Store<EntityStore> store = /* ... */;
GameStateResource state = store.getResource(gameStateType);
state.addScore(100);

```

--------------------------------

### Complete World Configuration Example

Source: https://hytale-docs.pages.dev/server/world-config

Complete world configuration example with all available options. Use as a reference for configuring a world in JSON format. Includes settings for world generation, chunk storage, spawn provider, gameplay flags, and client effects.

```json
{
  "UUID": "550e8400-e29b-41d4-a716-446655440000",
  "DisplayName": "Adventure World",
  "Seed": 1234567890,
  "WorldGen": {
    "Type": "Hytale",
    "Name": "Default"
  },
  "ChunkStorage": {
    "Type": "Hytale"
  },
  "ChunkConfig": {
    "PregenerateRegion": { "Min": [-512, -512], "Max": [512, 512] },
    "KeepLoadedRegion": { "Min": [-128, -128], "Max": [128, 128] }
  },
  "SpawnProvider": {
    "Type": "FitToHeightMap",
    "SpawnProvider": {
      "Type": "Global",
      "SpawnPoint": { "Position": [0, -1, 0], "Rotation": [0, 0, 0] }
    }
  },
  "IsTicking": true,
  "IsBlockTicking": true,
  "IsPvpEnabled": false,
  "IsFallDamageEnabled": true,
  "IsGameTimePaused": false,
  "GameTime": "1970-01-01T05:30:00Z",
  "GameMode": "Adventure",
  "GameplayConfig": "Default",
  "IsSpawningNPC": true,
  "IsSpawnMarkersEnabled": true,
  "IsAllNPCFrozen": false,
  "IsObjectiveMarkersEnabled": true,
  "IsCompassUpdating": true,
  "IsSavingPlayers": true,
  "IsSavingChunks": true,
  "SaveNewChunks": true,
  "IsUnloadingChunks": true,
  "ClientEffects": {
    "SunHeightPercent": 100.0,
    "SunAngleDegrees": 0.0,
    "BloomIntensity": 0.3,
    "BloomPower": 8.0,
    "SunIntensity": 0.25,
    "SunshaftIntensity": 0.3,
    "SunshaftScaleFactor": 4.0
  }
}
```

--------------------------------

### Server config.json example

Source: https://hytale-docs.pages.dev/server/server-config

Example of the main server configuration file. It shows the default values for server-wide settings, including identity, player limits, display options, connection timeouts, rate limiting, and module placeholders.

```json
{
  "ServerName": "Hytale Server",
  "MOTD": "",
  "Password": "",
  "MaxPlayers": 100,
  "MaxViewRadius": 32,
  "LocalCompressionEnabled": false,
  "DisplayTmpTagsInStrings": false,
  "Defaults": {
    "World": "default",
    "GameMode": "Adventure"
  },
  "ConnectionTimeouts": {
    "InitialTimeout": "PT10S",
    "AuthTimeout": "PT30S",
    "PlayTimeout": "PT1M",
    "JoinTimeouts": {}
  },
  "RateLimit": {
    "Enabled": true,
    "PacketsPerSecond": 2000,
    "BurstCapacity": 500
  },
  "Modules": {},
  "LogLevels": {},
  "Mods": {},
  "PlayerStorage": {},
  "AuthCredentialStore": null
}
```

--------------------------------

### Registering an Asset with HytaleAssetStore

Source: https://hytale-docs.pages.dev/modding/content

Java example for registering a custom asset in a plugin's setup method. Uses getAssetRegistry() and HytaleAssetStore.builder with a String key, IndexedLookupTableAssetMap, path, codec, and key function. Includes a comment for custom key types.

```java
// In your plugin's setup method, use getAssetRegistry()
@Override
protected void setup() {
    // For String-keyed assets (most common case)
  getAssetRegistry().register(
        HytaleAssetStore.builder(MyAsset.class, new IndexedLookupTableAssetMap<>(MyAsset[]::new))
            .setPath("MyAssets")
            .setCodec(MyAsset.CODEC)
            .setKeyFunction(MyAsset::getId)
            .build()
    );


    // For custom key types, use the 3-parameter builder
    // HytaleAssetStore.builder(KeyClass.class, AssetClass.class, assetMap)
}
```

--------------------------------

### Install Hytale server as Windows service with NSSM

Source: https://hytale-docs.pages.dev/server/service

Commands to install the Hytale server as a Windows service using NSSM. The first command installs the service with the Java executable path, the second sets the application parameters (JVM options and server jar), and the third sets the application directory.

```bash
nssm install HytaleServer "C:\Program Files\Java\jdk-25\bin\java.exe"
nssm set HytaleServer AppParameters "-Xms4G -Xmx4G -jar HytaleServer.jar --assets ..\HytaleAssets"
nssm set HytaleServer AppDirectory "C:\hytale-server"
```

--------------------------------

### World config.json example

Source: https://hytale-docs.pages.dev/server/world-config

Example world configuration file stored at universe/worlds/<worldname>/config.json. Shows all available settings including world identity, generation, chunk storage, ticking, PvP, game time, and gameplay configuration.

```json
{
  "UUID": "generated-uuid-here",
  "DisplayName": "My World",
  "Seed": 1234567890,
  "WorldGen": {
    "Type": "Hytale"
  },
  "ChunkStorage": {
    "Type": "Hytale"
  },
  "ChunkConfig": {
    "PregenerateRegion": { "Min": [-512, -512], "Max": [512, 512] },
    "KeepLoadedRegion": { "Min": [-256, -256], "Max": [256, 256] }
  },
  "IsTicking": true,
  "IsBlockTicking": true,
  "IsPvpEnabled": false,
  "IsFallDamageEnabled": true,
  "IsGameTimePaused": false,
  "GameTime": "1970-01-01T05:30:00Z",
  "GameMode": "Adventure",
  "IsSpawningNPC": true,
  "IsSpawnMarkersEnabled": true,
  "IsAllNPCFrozen": false,
  "IsSavingPlayers": true,
  "IsSavingChunks": true,
  "SaveNewChunks": true,
  "IsUnloadingChunks": true,
  "IsCompassUpdating": true,
  "IsObjectiveMarkersEnabled": true,
  "GameplayConfig": "Default"
}
```

--------------------------------

### Spawning a Projectile from Code (FireballLauncher)

Source: https://hytale-docs.pages.dev/modding/systems/projectiles

Example class showing how to spawn a projectile from code. It retrieves a ProjectileConfig asset, gets the shooter's transform, calculates launch position and direction, and calls ProjectileModule.get().spawnProjectile(). The projectile is then simulated by StandardPhysicsTickSystem.

```java
public class FireballLauncher {
    public void launchFireball(
        Ref<EntityStore> shooterRef,
        CommandBuffer<EntityStore> commandBuffer
    ) {
        // Get config
        ProjectileConfig config = ProjectileConfig.getAssetMap()
            .getAsset("mymod:fireball");
        if (config == null) return;


        // Get shooter transform
        TransformComponent transform = commandBuffer.getComponent(
            shooterRef,
            TransformComponent.getComponentType()
        );
        if (transform == null) return;


        // Calculate launch position and direction
        Vector3d position = transform.getPosition().clone();
        position.y += 1.6; // Eye height


        Vector3d direction = new Vector3d(
            transform.getRotation().getYaw(),
            transform.getRotation().getPitch()
        );


        // Spawn projectile
        Ref<EntityStore> projectile = ProjectileModule.get().spawnProjectile(
            shooterRef,
            commandBuffer,
            config,
            position,
            direction
        );


        // Projectile now exists and will be simulated by StandardPhysicsTickSystem
    }
}
```

--------------------------------

### Optional Arguments Example (TeleportCommand)

Source: https://hytale-docs.pages.dev/modding/plugins/commands

Shows how to register optional arguments using withOptionalArg. Optional arguments use --name value syntax. Use worldArg.provided(context) to check if the argument was provided before calling get().

```java
import com.hypixel.hytale.server.core.command.system.arguments.system.OptionalArg;
import com.hypixel.hytale.server.core.command.system.arguments.system.RequiredArg;
import com.hypixel.hytale.server.core.command.system.arguments.types.ArgTypes;


public class TeleportCommand extends AbstractCommand {


    private final RequiredArg<Double> xArg;
    private final RequiredArg<Double> yArg;
    private final RequiredArg<Double> zArg;
    private final OptionalArg<String> worldArg;


    public TeleportCommand() {
        super("tp", "Teleport to coordinates");


        xArg = withRequiredArg("x", "X coordinate", ArgTypes.DOUBLE);
        yArg = withRequiredArg("y", "Y coordinate", ArgTypes.DOUBLE);
        zArg = withRequiredArg("z", "Z coordinate", ArgTypes.DOUBLE);


        // Optional argument: --world <name>
        worldArg = withOptionalArg("world", "Target world", ArgTypes.STRING);
    }


    @Override
    @Nullable
    protected CompletableFuture<Void> execute(@Nonnull CommandContext context) {
        double x = xArg.get(context);
        double y = yArg.get(context);
        double z = zArg.get(context);


        // Check if optional arg was provided and get value
        String world = worldArg.provided(context) ? worldArg.get(context) : "default";


        // Teleport implementation
        return CompletableFuture.completedFuture(null);
    }
}
```

--------------------------------

### Asset JSON file example

Source: https://hytale-docs.pages.dev/modding/content/assets

Example JSON file for an asset, with fields 'Id', 'Name', and 'Value'.

```json
{
  "Id": "my_asset_id",
  "Name": "My Asset",
  "Value": 42
}
```

--------------------------------

### Register components in plugin setup

Source: https://hytale-docs.pages.dev/modding/ecs/components

Shows how to register a component type in the plugin's setup method, with and without serialization. The serialized version uses a CODEC and is saved to disk; the runtime-only version uses a factory method.

```java
public class MyPlugin extends JavaPlugin {
    private ComponentType<EntityStore, HealthComponent> healthComponentType;


    @Override
    protected void setup() {
        // With serialization (saved to disk)
        healthComponentType = getEntityStoreRegistry().registerComponent(
            HealthComponent.class,
            "Health",
            HealthComponent.CODEC
        );


        // Without serialization (runtime only)
        ComponentType<EntityStore, TempData> tempType =
            getEntityStoreRegistry().registerComponent(
                TempData.class,
                TempData::new
            );
    }


    public ComponentType<EntityStore, HealthComponent> getHealthComponentType() {
        return healthComponentType;
    }
}
```

--------------------------------

### Register component, system, and command in setup()

Source: https://hytale-docs.pages.dev/modding/examples

Registers a component, system, and command in the plugin's setup() method. Uses getEntityStoreRegistry() to register a HealthComponent with a JSON name and codec, a HealthRegenSystem, and getCommandRegistry() to register a HealthCommand. Logs an info message when done.

```java
import com.hypixel.hytale.component.ComponentType;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;


@Override
protected void setup() {
    // Register component with name and codec for JSON serialization
    ComponentType<EntityStore, HealthComponent> healthType =
        getEntityStoreRegistry().registerComponent(
            HealthComponent.class,
            "Health",                    // Component name in JSON
            HealthComponent.CODEC        // Serialization codec
        );


    // Register system that processes entities with HealthComponent
    getEntityStoreRegistry().registerSystem(new HealthRegenSystem(healthType));


    // Register command collection
    getCommandRegistry().registerCommand(new HealthCommand(healthType));


    getLogger().at(Level.INFO).log("Health system registered!");
}
```

--------------------------------

### Register BootEvent listener in setup()

Source: https://hytale-docs.pages.dev/modding/plugins/plugin-system

Registers a listener for the BootEvent during setup() to log a message when the server boots. The event class is imported from the Hytale server core event package.

```java
import com.hypixel.hytale.server.core.event.events.BootEvent;


// In setup()
getEventRegistry().register(BootEvent.class, event -> {
    getLogger().at(Level.INFO).log("Server booted!");
});
```

--------------------------------

### Inline Markup Java Examples

Source: https://hytale-docs.pages.dev/gui/builders

Java examples of appendInline calls for inline UI. The third example shows using a % prefix for translation keys.

```java
// Simple label
builder.appendInline("#container", "Label { Text: No items found; Style: (Alignment: Center); }");
```

```java
// Group container
builder.appendInline("#list", "Group { LayoutMode: Left; Anchor: (Bottom: 0); }");
```

```java
// Localized text (use % prefix for translation keys)
builder.appendInline("#messages", "Label { Text: %customUI.noItems; Style: (Alignment: Center); }");
```

--------------------------------

### Install Java 25 on Ubuntu/Debian

Source: https://hytale-docs.pages.dev/getting-started/installation

Adds the Adoptium repository and installs the Temurin 25 JDK. Requires sudo privileges.

```bash
# Add Adoptium repository
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -
echo "deb https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list


# Install Java 25
sudo apt update
sudo apt install temurin-25-jdk
```

--------------------------------

### permissions.json configuration example

Source: https://hytale-docs.pages.dev/modding/plugins/permissions

Example of the permissions.json file structure. It defines users with their permissions and groups, and groups with their permission lists. The OP group has wildcard '*' permission, while Default has none.

```json
{
  "users": {
    "550e8400-e29b-41d4-a716-446655440000": {
      "permissions": ["myplugin.vip", "myplugin.special"],
      "groups": ["VIP", "Moderator"]
    }
  },
  "groups": {
    "OP": ["*"],
    "Default": [],
    "VIP": ["myplugin.vip.*"],
    "Moderator": ["myplugin.mod.*", "hytale.command.kick"]
  }
}
```

--------------------------------

### Complete Interactive Example

Source: https://hytale-docs.pages.dev/gui/pages

Complete example of an interactive custom UI page that uses UICommandBuilder and UIEventBuilder to build a shop interface.

```APIDOC
## Complete Interactive Example

### Description
Example of an interactive custom UI page that uses UICommandBuilder and UIEventBuilder to build a shop interface.

### Code
```java
public class ShopPage extends InteractiveCustomUIPage<ShopPage.ShopEventData> {

    private final List<ShopItem> items;
    private int playerCoins;

    public ShopPage(PlayerRef playerRef, List<ShopItem> items, int coins) {
        super(playerRef, CustomPageLifetime.CanDismiss, ShopEventData.CODEC);
        this.items = items;
        this.playerCoins = coins;
    }

    @Override
    public void build(Ref<EntityStore> ref, UICommandBuilder commands,
                      UIEventBuilder events, Store<EntityStore> store) {
        commands.append("Pages/ShopPage.ui");
        commands.set("#CoinsLabel.Text", playerCoins + " coins");

        for (int i = 0; i < items.size(); i++) {
            ShopItem item = items.get(i);
            commands.append("#ItemList", "Components/ShopItem.ui");
            commands.set("#Item" + i + ".Name", item.getName());
            commands.set("#Item" + i + ".Price", item.getPrice() + "c");

            // Note: KeyedCodec keys that start with letters must be uppercase
            events.addEventBinding(
                CustomUIEventBindingType.Activating,
                "#BuyBtn" + i,
                EventData.of("Action", "buy").append("Index", Integer.toString(i))
            );
        }

        events.addEventBinding(
            CustomUIEventBindingType.Activating,
            "#CloseBtn",
            EventData.of("Action", "close")
        );
    }

    @Override
    public void handleDataEvent(Ref<EntityStore> ref, Store<EntityStore> store,
                                ShopEventData data) {
        switch (data.action) {
            case "buy":
                ShopItem item = items.get(data.index);
                if (playerCoins >= item.getPrice()) {
                    playerCoins -= item.getPrice();
                    // Give item to player...

                    // Update UI
                    UICommandBuilder update = new UICommandBuilder();
                    update.set("#CoinsLabel.Text", playerCoins + " coins");
                    sendUpdate(update);
                }
                break;
            case "close":
                close();
                break;
        }
    }

    public static class ShopEventData {
        public static final BuilderCodec<ShopEventData> CODEC =
            BuilderCodec.builder(ShopEventData.class, ShopEventData::new)
                .append(new KeyedCodec<>("Action", Codec.STRING),
                    (d, v) -> d.action = v, d -> d.action).add()
                .append(new KeyedCodec<>("Index", Codec.INTEGER),
                    (d, v) -> d.index = v, d -> d.index).add()
                .build();

        public String action;
        public Integer index;
    }
}
```
```

--------------------------------

### Complete Example - Player vs Mob Combat in a Damage handler

Source: https://hytale-docs.pages.dev/modding/systems/damage

Complete example that combines target and source retrieval to handle player-vs-mob combat. It returns early if the damage is not entity-to-entity, then checks whether a player attacked a mob or a mob attacked a player, sending appropriate translated messages with the damage amount.

```java
@Override
public void handle(int index, ArchetypeChunk<EntityStore> chunk,
                   Store<EntityStore> store, CommandBuffer<EntityStore> commandBuffer,
                   Damage damage) {
    // Get target (who received damage)
    Ref<EntityStore> targetRef = chunk.getReferenceTo(index);


    // Get source (who dealt damage)
    Damage.Source source = damage.getSource();
    if (!(source instanceof Damage.EntitySource entitySource)) {
        return; // Not entity-to-entity damage
    }
    Ref<EntityStore> attackerRef = entitySource.getRef();


    // Check if a player hit a mob
    Player attackerPlayer = store.getComponent(attackerRef, Player.getComponentType());
    Player targetPlayer = store.getComponent(targetRef, Player.getComponentType());


    if (attackerPlayer != null && targetPlayer == null) {
        // Player attacked a mob
        String playerName = attackerPlayer.getPlayerRef().getUsername();
        attackerPlayer.sendMessage(Message.translation(
            String.format("You dealt %.1f damage!", damage.getAmount())));
    }


    if (attackerPlayer == null && targetPlayer != null) {
        // Mob attacked a player
        targetPlayer.sendMessage(Message.translation(
            String.format("A mob hit you for %.1f damage!", damage.getAmount())));
    }
}

```

--------------------------------

### systemd service commands for Hytale

Source: https://hytale-docs.pages.dev/server/service

Commands to enable, start, stop, restart, and check the status of the hytale systemd service. Enable the service to start on boot, then use start/stop/restart to manage it, and status to check its current state.

```bash
# Enable service to start on boot
sudo systemctl enable hytale


# Start the server
sudo systemctl start hytale


# Stop the server
sudo systemctl stop hytale


# Restart the server
sudo systemctl restart hytale


# Check status
sudo systemctl status hytale
```

--------------------------------

### Install Java 25 on Windows using winget

Source: https://hytale-docs.pages.dev/getting-started/installation

Installs the Temurin 25 JRE via winget. Requires Windows 10 or later with winget available.

```bash
winget install --id EclipseAdoptium.Temurin.25.JRE
```

--------------------------------

### PrefabWeights

Source: https://hytale-docs.pages.dev/modding/content/prefabs

Documentation for the PrefabWeights class, including its methods, constants, and usage examples.

```APIDOC
## PrefabWeights

### Description
Handle weighted random selection for prefabs.

### Methods

#### setWeight(String name, double weight)
Sets the weight for a specific prefab.

#### setDefaultWeight(double weight)
Sets the default weight for unlisted prefabs (default is 1.0).

#### getWeight(String name)
Returns the weight for a specific prefab, or the default if not set.

#### removeWeight(String name)
Removes a specific weight.

#### get(String[] names, Function<String, String> nameExtractor, Random random)
Selects a weighted random element from an array using a random instance.

#### get(String[] names, Function<String, String> nameExtractor, double randomValue)
Selects a weighted random element from an array using a specific random value (0.0 to 1.0).

#### parse(String mappingString)
Parses a string format "name=weight, name2=weight2" into a PrefabWeights instance.

#### getMappingString()
Returns the mapping as a string, e.g., "oak_tree=3.0, birch_tree=2.0".

#### size()
Returns the number of explicitly set weights.

#### entrySet()
Iterates over entries, each with getKey() and getDoubleValue().

### Constants

#### NONE
An immutable singleton that ignores all setWeight calls and always returns null from get().

### Example
```java
import com.hypixel.hytale.server.core.prefab.PrefabWeights;
import java.util.Random;
import java.util.function.Function;

// Create new weights instance
PrefabWeights weights = new PrefabWeights();

// Set weights for specific prefabs
weights.setWeight("oak_tree", 3.0);
weights.setWeight("birch_tree", 2.0);

// Set default weight for unlisted prefabs (default is 1.0)
weights.setDefaultWeight(1.0);

// Get weight for a specific prefab (returns default if not set)
double weight = weights.getWeight("oak_tree");  // Returns 3.0
double defaulted = weights.getWeight("pine_tree");  // Returns 1.0 (default)

// Remove a specific weight
weights.removeWeight("birch_tree");

// Select weighted random element from array
Random random = new Random();
String[] names = {"oak_tree", "birch_tree", "pine_tree"};
Function<String, String> nameExtractor = name -> name;  // Identity function
String selected = weights.get(names, nameExtractor, random);

// Select with specific random value (0.0 to 1.0)
String selectedWithValue = weights.get(names, nameExtractor, 0.5);

// Parse from string format "name=weight, name2=weight2"
PrefabWeights parsed = PrefabWeights.parse("oak=3.0, birch=2.0");

// Get mapping as string
String mappingString = weights.getMappingString();  // "oak_tree=3.0, birch_tree=2.0"

// Get number of explicitly set weights
int size = weights.size();

// Empty weights singleton (always returns null from get())
PrefabWeights none = PrefabWeights.NONE;

// Iterate over entries
for (var entry : weights.entrySet()) {
    String name = entry.getKey();
    double w = entry.getDoubleValue();
}
```
```

--------------------------------

### Hytale Server Startup Output

Source: https://hytale-docs.pages.dev/getting-started/installation

Example output shown on first launch, indicating successful server startup.

```text
[INFO] Loading assets from Assets.zip
[INFO] Server started on 0.0.0.0:5520
[INFO] Ready for connections
```

--------------------------------

### EntityStatMap Access Example

Source: https://hytale-docs.pages.dev/modding/ecs/entity-stats

Java code showing how to get the EntityStatMap component type and retrieve it from an entity, then get a stat by index.

```java
import com.hypixel.hytale.server.core.modules.entitystats.EntityStatMap;
import com.hypixel.hytale.server.core.modules.entitystats.EntityStatsModule;


// Get the component type
ComponentType<EntityStore, EntityStatMap> statMapType =
    EntityStatsModule.get().getEntityStatMapComponentType();


// Get from entity
EntityStatMap stats = store.getComponent(entityRef, statMapType);


// Get stat by index
EntityStatValue health = stats.get(DefaultEntityStatTypes.getHealth());
```

--------------------------------

### Basic Hytale plugin structure with manifest.json

Source: https://hytale-docs.pages.dev/modding/examples

Complete Hytale plugin example: the Java plugin class defines lifecycle methods (setup, start, shutdown) and placeholder registration methods, while manifest.json declares the plugin metadata required for loading. The manifest's "Main" field points to the plugin class.

```java
package com.example.myplugin;


import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import javax.annotation.Nonnull;


public class MyPlugin extends JavaPlugin {


    private static MyPlugin instance;


    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);
    }


    public static MyPlugin get() {
        return instance;
    }


    @Override
    protected void setup() {
        instance = this;


        // Register components
        registerComponents();


        // Register systems
        registerSystems();


        // Register commands
        registerCommands();


        // Register events
        registerEvents();


        getLogger().at(Level.INFO).log("MyPlugin setup complete!");
    }


    @Override
    protected void start() {
        getLogger().at(Level.INFO).log("MyPlugin started!");
    }


    @Override
    protected void shutdown() {
        getLogger().at(Level.INFO).log("MyPlugin shutting down!");
    }


    private void registerComponents() {
        // Component registration here
    }


    private void registerSystems() {
        // System registration here
    }


    private void registerCommands() {
        // Command registration here
    }


    private void registerEvents() {
        // Event registration here
    }
}

```

```json
{
  "Group": "com.example",
  "Name": "MyPlugin",
  "Version": "1.0.0",
  "Main": "com.example.myplugin.MyPlugin",
  "Description": "A complete example plugin",
  "Authors": [
    {
      "Name": "Your Name"
    }
  ],
  "ServerVersion": ">=0.0.1",
  "Dependencies": {},
  "OptionalDependencies": {},
  "IncludesAssetPack": false
}

```

--------------------------------

### SlideStartDetector detecting slide start

Source: https://hytale-docs.pages.dev/modding/systems/movement

Example of detecting when an entity starts sliding by comparing current and previous movement states. Uses EntityTickingSystem and MovementStatesComponent.

```java
public class SlideStartDetector extends EntityTickingSystem<EntityStore> {
    @Override
    public void tick(float dt, int index, ArchetypeChunk<EntityStore> archetypeChunk,
                     Store<EntityStore> store, CommandBuffer<EntityStore> commandBuffer) {
        MovementStatesComponent component = archetypeChunk.getComponent(index, type);
        MovementStates current = component.getMovementStates();
        MovementStates previous = component.getSentMovementStates();


        // Detect slide start
        if (current.sliding && !previous.sliding) {
            // Slide just started
            Ref<EntityStore> ref = archetypeChunk.getReferenceTo(index);
            handleSlideStart(ref, store, commandBuffer);
        }
    }
}
```

--------------------------------

### UIEventBuilder addEventBinding examples

Source: https://hytale-docs.pages.dev/gui/pages

Three examples of addEventBinding calls showing basic binding, adding event data, and setting locksInterface to false. The second example notes that keys starting with letters must be uppercase. The third example shows the default for locksInterface is true.

```java
// Basic event binding
events.addEventBinding(CustomUIEventBindingType.Activating, "#Button");
```

```java
// With event data (keys that start with letters must be uppercase)
events.addEventBinding(CustomUIEventBindingType.Activating, "#Button", EventData.of("Action", "click"));
```

```java
// With locksInterface parameter (default is true)
events.addEventBinding(CustomUIEventBindingType.Activating, "#Button", EventData.of("Action", "click"), false);
```

--------------------------------

### Placing a Prefab with PrefabStore

Source: https://hytale-docs.pages.dev/modding/content

Java example showing how to retrieve and place a server prefab. Uses PrefabStore.get() and getServerPrefab() to load a structure, then place() with a CommandSender for feedback or placeNoReturn() to skip returning replaced blocks.

```java
PrefabStore store = PrefabStore.get();
BlockSelection prefab = store.getServerPrefab("structures/house.prefab.json");


// Place at position - requires a CommandSender for feedback
// place(CommandSender feedback, World world, Vector3i position, BlockMask mask)
prefab.place(commandSender, world, new Vector3i(100, 64, 100), null);


// Alternative: place without returning replaced blocks
prefab.placeNoReturn(world, new Vector3i(100, 64, 100), componentAccessor);
```

--------------------------------

### Custom Port Example (Multiple Addresses)

Source: https://hytale-docs.pages.dev/getting-started/installation

Runs the server bound to multiple addresses using a comma-separated list with --bind.

```bash
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets ../HytaleAssets --bind 0.0.0.0:5520,0.0.0.0:5521
```

--------------------------------

### Plugin Configuration

Source: https://hytale-docs.pages.dev/modding/examples

Defines a plugin configuration class with a BuilderCodec and registers it via withConfig. The config must be registered before setup() and is accessed in start() after loading.

```java
import com.hypixel.hytale.codec.Codec;
import com.hypixel.hytale.codec.KeyedCodec;
import com.hypixel.hytale.codec.builder.BuilderCodec;
import com.hypixel.hytale.server.core.util.Config;


public class MyPlugin extends JavaPlugin {


    // Define configuration class
    public static class MyPluginConfig {
        public static final BuilderCodec<MyPluginConfig> CODEC =
            ((BuilderCodec.Builder) BuilderCodec.builder(MyPluginConfig.class, MyPluginConfig::new)
                .append(new KeyedCodec<>("Enabled", Codec.BOOLEAN),
                    (c, v) -> c.enabled = v, c -> c.enabled)
                .add())
                .append(new KeyedCodec<>("MaxPlayers", Codec.INTEGER),
                    (c, v) -> c.maxPlayers = v, c -> c.maxPlayers)
                .add()
                .build();


        private boolean enabled = true;
        private int maxPlayers = 100;


        public boolean isEnabled() { return enabled; }
        public int getMaxPlayers() { return maxPlayers; }
    }


    // Register config BEFORE setup() - must be called in constructor or field initializer
    private final Config<MyPluginConfig> config = this.withConfig("MyPlugin", MyPluginConfig.CODEC);


    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);
    }


    @Override
    protected void start() {
        // Access config after loading
        MyPluginConfig cfg = config.get();
        if (cfg.isEnabled()) {
            getLogger().at(Level.INFO).log("Plugin enabled with max players: " + cfg.getMaxPlayers());
        }
    }
}

```

--------------------------------

### Linux/macOS Start Script (start.sh)

Source: https://hytale-docs.pages.dev/getting-started/installation

Shell script to launch the server on Linux/macOS with the same basic arguments.

```bash
#!/bin/bash
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets ../HytaleAssets
```

--------------------------------

### Custom Port Example (Single Address)

Source: https://hytale-docs.pages.dev/getting-started/installation

Runs the server on a custom port by using the --bind argument with a single address.

```bash
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets ../HytaleAssets --bind 0.0.0.0:25565
```

--------------------------------

### Instruction Tree Example

Source: https://hytale-docs.pages.dev/modding/npc-ai/instructions

Builds a root instruction with child instructions for prioritized behaviors: combat, flee, and wander.

```java
// Root behavior
Instruction root = new Instruction(
    alwaysSensor,
    null,
    null,
    new Instruction[] {
        combatInstruction,    // Priority 1: Combat
        fleeInstruction,      // Priority 2: Flee if low health
        wanderInstruction     // Priority 3: Default wander
    }
);
```

--------------------------------

### IPointGenerator interface and usage

Source: https://hytale-docs.pages.dev/modding/content/world-generation

Defines the IPointGenerator interface for placing features at distributed points. Methods find nearest points in 2D/3D, transitions, collect points in an area, and get the spacing interval. The usage example shows how to call nearest2D and collect with a PointConsumer2d lambda.

```java
import com.hypixel.hytale.procedurallib.logic.point.IPointGenerator;
import com.hypixel.hytale.procedurallib.logic.ResultBuffer.*;


public interface IPointGenerator {
    // Find nearest point in 2D
    ResultBuffer2d nearest2D(int seed, double x, double z);


    // Find nearest point in 3D
    ResultBuffer3d nearest3D(int seed, double x, double y, double z);


    // Find transition between points in 2D
    ResultBuffer2d transition2D(int seed, double x, double z);


    // Find transition between points in 3D
    ResultBuffer3d transition3D(int seed, double x, double y, double z);


    // Collect all points in area
    void collect(int seed, double minX, double minZ, double maxX, double maxZ,
                 PointConsumer2d consumer);


    // Get point spacing interval
    double getInterval();
}


// Usage example
IPointGenerator generator = /* ... */;


// Find nearest point
ResultBuffer2d nearest = generator.nearest2D(seed, x, z);
double distance = nearest.distance;
double pointX = nearest.x;
double pointY = nearest.y;
int hash = nearest.hash;


// Collect points in area
generator.collect(seed, minX, minZ, maxX, maxZ, (px, pz) -> {
    // Process each point at (px, pz)
});
```

--------------------------------

### Install Java 25 on macOS using Homebrew

Source: https://hytale-docs.pages.dev/getting-started/installation

Installs Temurin 25 via Homebrew cask. Requires Homebrew to be installed.

```bash
brew install --cask temurin@25
```

--------------------------------

### Make start.sh Executable

Source: https://hytale-docs.pages.dev/getting-started/installation

Command to make the start.sh script executable.

```bash
chmod +x start.sh
```

--------------------------------

### Quick Example: Create and iterate entities with EntityStore

Source: https://hytale-docs.pages.dev/modding/ecs

Shows the core ECS workflow: obtaining the Store, creating an entity via a Holder, adding components, retrieving a component by ComponentType, and iterating over entities with forEachChunk. Note that components are accessed by ComponentType, not Class, and that forEachChunk provides an ArchetypeChunk and CommandBuffer for batch processing.

```java
// Get the EntityStore from a world, then get the underlying Store
EntityStore entityStore = world.getEntityStore();
Store<EntityStore> store = entityStore.getStore();


// Create an entity using a Holder
Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();
holder.addComponent(positionType, new PositionComponent(0, 64, 0));
holder.addComponent(velocityType, new VelocityComponent());
holder.addComponent(healthType, new HealthComponent(100));


Ref<EntityStore> entity = store.addEntity(holder, AddReason.SPAWN);


// Get a component from an entity using ComponentType (not Class)
PositionComponent pos = store.getComponent(entity, positionType);


// Iterate over entities with specific components using forEachChunk
store.forEachChunk(positionType, (archetypeChunk, commandBuffer) -> {
    for (int i = 0; i < archetypeChunk.size(); i++) {
        Ref<EntityStore> ref = archetypeChunk.getReferenceTo(i);
        PositionComponent position = archetypeChunk.getComponent(i, positionType);
        VelocityComponent velocity = archetypeChunk.getComponent(i, velocityType);
        if (position != null && velocity != null) {
            // Process entities with both components
            position.add(velocity);
        }
    }
});
```

--------------------------------

### Plugin Logger Usage Examples

Source: https://hytale-docs.pages.dev/modding/examples

Logging examples using the plugin logger with different levels: INFO, WARNING, and SEVERE with a cause. The WARNING and SEVERE examples use format specifiers for dynamic values.

```java
getLogger().at(Level.INFO).log("Plugin started");
getLogger().at(Level.WARNING).log("Something unexpected: %s", value);
getLogger().at(Level.SEVERE).withCause(exception).log("Failed to process: %s", item);

```

--------------------------------

### Custom .ui File with Texture Background

Source: https://hytale-docs.pages.dev/gui/builders

Example .ui file showing how to include Common.ui, define a texture with PatchStyle, and apply it as a background. Texture paths are relative to the .ui file location.

```hytale-ui
// Include Common.ui to access built-in styles
$Common = "Common.ui";


// Define a texture variable (path relative to this .ui file)
@MyTex = PatchStyle(TexturePath: "MyBackground.png");


Group {
    LayoutMode: Center;


    Group #MyPanel {
        Background: @MyTex;
        Anchor: (Width: 800, Height: 1000);
        LayoutMode: Top;
    }
}
```

--------------------------------

### Getting the HudManager

Source: https://hytale-docs.pages.dev/gui/hud

Retrieves the HudManager instance for a player by getting the Player component and calling getHudManager().

```java
import com.hypixel.hytale.server.core.entity.entities.Player;
import com.hypixel.hytale.server.core.entity.entities.player.hud.HudManager;


Player playerComponent = store.getComponent(entityRef, Player.getComponentType());
HudManager hudManager = playerComponent.getHudManager();
```

--------------------------------

### Install Java 25 on Fedora/RHEL

Source: https://hytale-docs.pages.dev/getting-started/installation

Installs OpenJDK 25 using dnf. Requires sudo privileges.

```bash
sudo dnf install java-25-openjdk
```

--------------------------------

### BeaconNPCSpawn configuration example

Source: https://hytale-docs.pages.dev/modding/spawning

Configuration for beacon-based spawning. Defines a spawn entry with an ID, NPC type, count range, spawn radius, and respawn time.

```json
{
  "id": "forest_wolf_spawn",
  "npcType": "wolf",
  "minCount": 2,
  "maxCount": 5,
  "spawnRadius": 20.0,
  "respawnTime": 300.0
}
```

--------------------------------

### Verify Java installation

Source: https://hytale-docs.pages.dev/getting-started/installation

Checks the installed Java version. Expect output indicating Java 25 or higher.

```bash
java -version
```

--------------------------------

### Medium Server Configuration (20-50 players)

Source: https://hytale-docs.pages.dev/server/performance

Example configuration for a medium server (20-50 players) with 8GB RAM allocation.

```bash
java -Xms8G -Xmx8G -jar HytaleServer.jar --assets ../HytaleAssets
```

--------------------------------

### Windows Start Script (start.bat)

Source: https://hytale-docs.pages.dev/getting-started/installation

Batch script to launch the server on Windows with the same basic arguments, pausing after execution.

```batch
@echo off
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets ../HytaleAssets
pause
```
Tokens:
Raw