### Quick Start Hytale Server (Bash)

Source: https://hytale-docs.com/docs/servers/setup/installation

A minimal script to get the Hytale server running. It creates a directory, downloads the server files using curl, and then starts the server with basic memory allocation and asset path configuration. It binds the server to all network interfaces on port 5520.

```bash
# Create directory
mkdir hytale-server
cd hytale-server

# Download server files
curl -L -o HytaleServer.jar https://cdn.hytale.com/HytaleServer.jar
curl -L -o Assets.zip https://cdn.hytale.com/Assets.zip

# Start server (minimal)
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip -b 0.0.0.0:5520

```

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

### Local Development Setup for Hytale Wiki

Source: https://hytale-docs.com/docs/community/contributing

Steps to set up the Hytale Wiki for local development. This involves cloning the repository, installing dependencies using npm, and starting the development server. Assumes Node.js 20+ and Git are installed.

```bash
# Clone the repository
git clone https://github.com/hytale-community/hytale-wiki.git
cd hytale-wiki

# Install dependencies
npm install

# Start development server
npm start

```

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

### Example Hytale Server Configurations

Source: https://hytale-docs.com/docs/servers/setup/configuration

Provides example server configurations for different player counts, including recommended JVM arguments and server properties. These examples demonstrate how to set memory allocation, choose garbage collectors, and tune performance for small, medium, and large servers.

```Properties
server-name=My Private Server
port=5520
max-players=10
view-distance=12
```

```Bash
java -Xms4G -Xmx4G -XX:+UseG1GC -XX:+UseCompactObjectHeaders \
    -jar HytaleServer.jar --assets Assets.zip -b 0.0.0.0:5520
```

```Properties
server-name=Community Server
port=5520
max-players=50
view-distance=10
```

```Bash
java -Xms8G -Xmx8G -XX:+UseShenandoahGC -XX:ShenandoahGCMode=generational \
    -XX:+AlwaysPreTouch -XX:+UseCompactObjectHeaders \
    -jar HytaleServer.jar --assets Assets.zip -b 0.0.0.0:5520
```

```Properties
server-name=Public Server
port=5520
max-players=100
view-distance=8
```

```Bash
java -Xms16G -Xmx16G -XX:+UseZGC -XX:SoftMaxHeapSize=12G \
    -XX:+AlwaysPreTouch -XX:+UseCompactObjectHeaders \
    -jar HytaleServer.jar --assets Assets.zip -b 0.0.0.0:5520
```

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

### Listen for Specific Plugin Setup Event (Java)

Source: https://hytale-docs.com/docs/modding/plugins/events/server/plugin-setup-event

An example demonstrating how to listen for the setup event of a specific plugin, MyDependencyPlugin, using its class as the key for registration.

```java
import com.hypixel.hytale.server.core.plugin.event.PluginSetupEvent;
import com.hypixel.hytale.event.EventBus;

public class MyDependentPlugin extends PluginBase {

    @Override
    public void onEnable(EventBus eventBus) {
        // Listen for a specific plugin's setup event using the key
        eventBus.register(
            PluginSetupEvent.class,
            MyDependencyPlugin.class,  // Key: the specific plugin class
            this::onDependencySetup
        );
    }

    private void onDependencySetup(PluginSetupEvent event) {
        // This only fires when MyDependencyPlugin is being set up
        MyDependencyPlugin dependency = (MyDependencyPlugin) event.getPlugin();
        getLogger().info("Dependency plugin is ready: " + dependency.getName());
    }
}
```

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

### Install Blockbench via Package Manager

Source: https://hytale-docs.com/docs/getting-started/environment-setup

Installs the Blockbench application using the Windows Package Manager (winget). This is a quick way to get the necessary modeling tool for Hytale assets.

```bash
# Download from blockbench.net or use package manager
winget install JannisX11.Blockbench
```

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

### Install Java 25 on Windows

Source: https://hytale-docs.com/docs/servers/hosting/self-hosting

Provides instructions for installing Java 25 from Adoptium on Windows systems. This involves downloading and running the installer, followed by a verification step. Essential for running Hytale.

```PowerShell
# Download and install Java 25 from Adoptium
# https://adoptium.net/

# Verify installation
java -version

```

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

### Recommended Linux Server Start Script (Bash)

Source: https://hytale-docs.com/docs/servers/setup/installation

A detailed bash script for starting the Hytale dedicated server on Linux. It configures minimum and maximum memory allocation (8GB), and includes optimized JVM arguments for the G1 Garbage Collector, suitable for servers with 4-12GB of RAM. It also sets essential server parameters like asset path, bind address, authentication mode, and operator privileges.

```bash
#!/bin/bash

# Memory configuration
MEMORY_MIN="8G"
MEMORY_MAX="8G"

# JVM arguments for Java 25 (G1GC optimized - recommended for 4-12GB)
java -Xms${MEMORY_MIN} -Xmx${MEMORY_MAX} \
    -XX:+UseG1GC \
    -XX:+ParallelRefProcEnabled \
    -XX:MaxGCPauseMillis=200 \
    -XX:+DisableExplicitGC \
    -XX:+AlwaysPreTouch \
    -XX:G1NewSizePercent=30 \
    -XX:G1MaxNewSizePercent=40 \
    -XX:G1HeapRegionSize=8M \
    -XX:G1ReservePercent=20 \
    -XX:InitiatingHeapOccupancyPercent=15 \
    -XX:SurvivorRatio=32 \
    -XX:+PerfDisableSharedMem \
    -XX:MaxTenuringThreshold=1 \
    -XX:+UseCompactObjectHeaders \
    -Djava.net.preferIPv4Stack=true \
    -Dfile.encoding=UTF-8 \
    -jar HytaleServer.jar \
    --assets Assets.zip \
    -b 0.0.0.0:5520 \
    --auth-mode authenticated \
    --allow-op

```

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

### Start Hytale Server (Windows Batch)

Source: https://hytale-docs.com/docs/servers/setup/installation

This script starts the Hytale server with specific Java Virtual Machine (JVM) arguments for performance and network configuration. It requires Java 25 and the HytaleServer.jar file, along with Assets.zip in the same directory.

```batch
@echo off
java -Xms8G -Xmx8G \
    -XX:+UseG1GC \
    -XX:+ParallelRefProcEnabled \
    -XX:MaxGCPauseMillis=200 \
    -XX:+DisableExplicitGC \
    -XX:+AlwaysPreTouch \
    -XX:+UseCompactObjectHeaders \
    -Djava.net.preferIPv4Stack=true \
    -jar HytaleServer.jar \
    --assets Assets.zip \
    -b 0.0.0.0:5520 \
    --auth-mode authenticated \
    --allow-op
pause

```

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

### Set Up Local Hytale Server

Source: https://hytale-docs.com/docs/getting-started/environment-setup

Commands to create a directory and download/start a local Hytale server. This is useful for testing mods and plugins in a controlled environment. Requires Java and the server JAR file.

```bash
# Create server directory
mkdir hytale-dev-server
cd hytale-dev-server

# Download and start server
java -Xms2G -Xmx4G -jar hytale-server.jar
```

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

### Hytale Java Plugin Main Class Setup

Source: https://hytale-docs.com/docs/modding/plugins/project-setup

This Java code demonstrates the basic structure of a Hytale server plugin. It extends the JavaPlugin class and overrides essential methods like setup(), start(), and shutdown() for plugin lifecycle management. It also shows how to register event listeners and commands.

```java
package com.example.myplugin;

import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import com.example.myplugin.commands.MyCommand;
import com.example.myplugin.listeners.PlayerListener;

import javax.annotation.Nonnull;

public class MyPlugin extends JavaPlugin {

    private static MyPlugin instance;

    // Required constructor - must take JavaPluginInit parameter
    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);
        instance = this;
    }

    @Override
    protected void setup() {
        // Called during plugin initialization
        // Register commands, events, assets, and components here
        getLogger().info("MyPlugin is setting up...");

        // Register event listeners
        // Tip: Use 'hyevent' template in IntelliJ to create event handlers quickly
        getEventRegistry().register(
            com.hypixel.hytale.server.core.event.events.player.PlayerConnectEvent.class,
            event -> {
                getLogger().info("Player connected: " + event.getPlayer().getName());
            }
        );

        // Register commands
        // Tip: Use 'hycmd' template in IntelliJ to create commands quickly
        getCommandRegistry().registerCommand(new MyCommand(this));

        getLogger().info("MyPlugin setup complete!");
    }

    @Override
    protected void start() {
        // Called after all plugins are set up
        // Perform any start-up logic that depends on other plugins
        getLogger().info("MyPlugin has started!");
    }

    @Override
    protected void shutdown() {
        // Called when plugin is shutting down
        // Perform cleanup before registries are cleaned up
        getLogger().info("MyPlugin is shutting down...");
    }

    public static MyPlugin getInstance() {
        return instance;
    }
}
```

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

### Listen for All Plugin Setup Events (Java)

Source: https://hytale-docs.com/docs/modding/plugins/events/server/plugin-setup-event

An example of how to listen for all PluginSetupEvent occurrences globally within a PluginManagerPlugin. It registers a callback to the event bus for PluginSetupEvent.

```java
import com.hypixel.hytale.server.core.plugin.event.PluginSetupEvent;
import com.hypixel.hytale.event.EventBus;

public class PluginManagerPlugin extends PluginBase {

    @Override
    public void onEnable(EventBus eventBus) {
        // Listen for all plugin setup events (global registration)
        eventBus.registerGlobal(PluginSetupEvent.class, this::onPluginSetup);
    }

    private void onPluginSetup(PluginSetupEvent event) {
        PluginBase plugin = event.getPlugin();
        getLogger().info("Plugin being set up: " + plugin.getClass().getName());
    }
}
```

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

### Start Hytale Server

Source: https://hytale-docs.com/docs/servers/hosting/self-hosting

Launches the Hytale server using the Java runtime. It specifies minimum and maximum heap sizes (-Xms and -Xmx) and the server JAR file. Adjust memory allocation as needed.

```Bash
java -Xms4G -Xmx8G -jar hytale-server.jar

```

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

### Complete Hytale Plugin Example in Java

Source: https://hytale-docs.com/docs/modding/plugins/plugin-lifecycle

A full example of a Hytale plugin demonstrating all lifecycle methods and common patterns. It includes setup for commands, event listeners, ECS systems, and integration with other plugins. This example requires the Hytale server core library.

```java
package com.example.myplugin;

import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import com.hypixel.hytale.server.core.plugin.Config;
import com.hypixel.hytale.server.core.logging.HytaleLogger;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.concurrent.CompletableFuture;

public class MyPlugin extends JavaPlugin {
    private static final HytaleLogger LOGGER = HytaleLogger.forEnclosingClass();
    private static MyPlugin instance;

    private Config<MyConfig> config;
    private PlayerDataManager playerDataManager;

    // Singleton access for other plugins
    public static MyPlugin getInstance() {
        return instance;
    }

    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);
        instance = this;

        // Register config for async loading
        config = withConfig(MyConfig.CODEC);
    }

    @Override
    @Nullable
    public CompletableFuture<Void> preLoad() {
        LOGGER.info("PreLoading configuration...");
        // Config files are loaded automatically
        return super.preLoad();
    }

    @Override
    protected void setup() {
        LOGGER.info("Setting up plugin...");

        // Initialize managers
        playerDataManager = new PlayerDataManager(getDataDirectory());

        // Register commands
        getCommandRegistry().registerCommand(new SpawnCommand());
        getCommandRegistry().registerCommand(new HomeCommand());

        // Register event listeners
        getEventRegistry().register(PlayerJoinEvent.class, this::onPlayerJoin);
        getEventRegistry().register(PlayerQuitEvent.class, this::onPlayerQuit);
        getEventRegistry().register(EventPriority.EARLY, PlayerChatEvent.class, this::onChat);

        // Register ECS systems
        getEntityStoreRegistry().registerSystem(new PlayerTrackingSystem());
        getChunkStoreRegistry().registerSystem(new CustomBlockSystem());

        LOGGER.info("Setup complete!");
    }

    @Override
    protected void start() {
        LOGGER.info("Starting plugin...");

        // Safe to interact with other plugins now
        EconomyPlugin economy = EconomyPlugin.getInstance();
        if (economy != null) {
            economy.registerCurrency("tokens", 0);
            LOGGER.info("Integrated with EconomyPlugin");
        }

        // Start scheduled tasks
        getTaskRegistry().scheduleRepeating(this::autoSave, 6000, 6000); // Every 5 minutes

        LOGGER.info("Plugin started! Welcome: " + config.get().getWelcomeMessage());
    }

    @Override
    protected void shutdown() {
        LOGGER.info("Shutting down...");

        // Save all player data
        if (playerDataManager != null) {
            playerDataManager.saveAll();
        }

        // Cleanup
        instance = null;

        LOGGER.info("Shutdown complete!");
    }

    // Event handlers
    private void onPlayerJoin(PlayerJoinEvent event) {
        Player player = event.getPlayer();
        playerDataManager.load(player);
        player.sendMessage(config.get().getWelcomeMessage());
    }

    private void onPlayerQuit(PlayerQuitEvent event) {
        playerDataManager.save(event.getPlayer());
    }

    private void onChat(PlayerChatEvent event) {
        // Early priority - can modify or cancel
        if (event.getMessage().contains("badword")) {
            event.setCancelled(true);
        }
    }

    private void autoSave() {
        playerDataManager.saveAll();
        LOGGER.debug("Auto-save complete");
    }

    // Public API for other plugins
    public MyConfig getConfiguration() {
        return config.get();
    }
}

```

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

### Hytale Plugin Logging Examples

Source: https://hytale-docs.com/docs/modding/plugins/project-setup

This Java code snippet shows how to use the plugin's logger to output different levels of messages. It includes examples for informational, warning, severe (error), and fine (debug) messages, demonstrating how to provide feedback during plugin execution.

```java
getLogger().info("Information message");
getLogger().warning("Warning message");
getLogger().severe("Error message");
getLogger().fine("Debug message"); // Only shown with verbose logging
```

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

### Plugin Start Lifecycle Method in Java

Source: https://hytale-docs.com/docs/modding/plugins/plugin-lifecycle

The start() method is invoked after all plugins have completed their setup phase, making it the appropriate place for cross-plugin interactions. It's also used for initializing scheduled tasks and logging a startup message.

```java
@Override
protected void start() {
    // Safe to interact with other plugins here
    OtherPlugin other = OtherPlugin.getInstance();
    if (other != null) {
        other.registerIntegration(this);
    }

    // Start any scheduled tasks
    getTaskRegistry().scheduleRepeating(this::tick, 20, 20); // Every second

    getLogger().info("Plugin started and ready!");
}

```

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

### Logging and Monitoring with StartWorldEvent in Java

Source: https://hytale-docs.com/docs/modding/plugins/events/world/start-world-event

Illustrates how to use StartWorldEvent for logging and monitoring world startup. This example demonstrates recording world start metrics and logging the event with timestamps.

```java
eventBus.register(EventPriority.FIRST, StartWorldEvent.class, event -> {
    World world = event.getWorld();

    // Track world startup metrics
    long startTime = System.currentTimeMillis();
    metrics.recordWorldStart(world.getName(), startTime);

    // Log for monitoring
    logger.info("World '{}' has started at {}", world.getName(), startTime);
});
```

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

### Complete Player Orientation Example (Java)

Source: https://hytale-docs.com/docs/api/server-internals/player-orientation

A comprehensive example demonstrating how to retrieve and display a player's orientation. It fetches rotation, converts to degrees, determines cardinal direction, and gets the precise look vector.

```Java
public void displayPlayerOrientation(Store<EntityStore> store, Ref<EntityStore> playerRef) {
    // Get components
    HeadRotation headRotation = store.getComponent(playerRef, HeadRotation.getComponentType());
    TransformComponent transform = store.getComponent(playerRef, TransformComponent.getComponentType());

    // Get rotation values
    Vector3f rotation = headRotation.getRotation();
    float yaw = rotation.getYaw();
    float pitch = rotation.getPitch();

    // Convert to degrees
    double yawDegrees = Math.toDegrees(yaw);
    double pitchDegrees = Math.toDegrees(pitch);

    // Normalize yaw to 0-360
    yawDegrees = (yawDegrees % 360 + 360) % 360;

    // Get cardinal direction
    Vector3i cardinalDir = headRotation.getAxisDirection();
    String cardinal = getCardinalDirection(yaw);

    // Get precise look direction
    Vector3d lookDir = headRotation.getDirection();

    // Display results
    System.out.println("Yaw: " + yawDegrees + "°");
    System.out.println("Pitch: " + pitchDegrees + "°");
    System.out.println("Cardinal: " + cardinal);
    System.out.println("Looking at: " + lookDir);
}

// Helper function to get cardinal direction (assuming it's defined elsewhere or within this class)
public static String getCardinalDirection(float yawRadians) {
    double yawDegrees = Math.toDegrees(yawRadians);
    yawDegrees = (yawDegrees % 360 + 360) % 360; // Normalize to 0-360

    if (yawDegrees >= 315 || yawDegrees < 45) {
        return "NORTH";
    } else if (yawDegrees >= 45 && yawDegrees < 135) {
        return "WEST";
    } else if (yawDegrees >= 135 && yawDegrees < 225) {
        return "SOUTH";
    } else {
        return "EAST";
    }
}
```

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

### Basic Usage of Hytale API PHP SDK

Source: https://hytale-docs.com/docs/api/sdks/php

This PHP code example demonstrates how to initialize the Hytale API client and fetch blog posts. It requires the SDK to be installed via Composer and uses the `HytaleAPI\Client` class.

```php
use HytaleAPI\Client;

$client = new Client();
$posts = $client->blog()->getPosts();

```

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

### Hytale Server Manual Debugging Startup

Source: https://hytale-docs.com/docs/modding/plugins/project-setup

This Bash command starts the Hytale server with specific Java debug flags enabled. It allows remote debugging by opening a socket on port 5005, enabling tools like IntelliJ IDEA to attach to the running process.

```bash
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 -jar hytale-server.jar
```

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

### Handle Plugin Lifecycle Events in Java

Source: https://hytale-docs.com/docs/api/server-internals/plugins

Override setup(), start(), and shutdown() methods to manage plugin initialization, resource allocation, and cleanup during different lifecycle phases. Dependencies are guaranteed to be in the appropriate state for each method.

```Java
public class MyPlugin extends JavaPlugin {

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

    /**
     * Called during the setup phase.
     * Use this method to register commands, events, and initialise resources.
     * Dependencies are guaranteed to be in the SETUP state or later.
     */
    @Override
    protected void setup() {
        // Register commands
        getCommandRegistry().registerCommand(new MyCommand());

        // Register event handlers
        getEventRegistry().register(PlayerJoinEvent.class, this::onPlayerJoin);

        // Register tasks
        getTaskRegistry().registerTask(myAsyncTask());
    }

    /**
     * Called during the start phase.
     * Dependencies are guaranteed to be in the ENABLED state.
     * Asset packs should be registered here.
     */
    @Override
    protected void start() {
        getLogger().info("Plugin started successfully!");
    }

    /**
     * Called when the plugin is shutting down.
     * Use this method to clean up resources, save data, and perform other teardown operations.
     */
    @Override
    protected void shutdown() {
        getLogger().info("Cleaning up resources...");
    }
}
```

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

### Initialize Hytale API and Fetch Blog Posts (JavaScript)

Source: https://hytale-docs.com/docs/api/sdks/javascript

This JavaScript code snippet demonstrates how to import and initialize the HytaleAPI class from the SDK. It then shows an example of fetching blog posts using the `getPosts` method. Ensure the SDK is installed before running this code.

```javascript
import { HytaleAPI } from '@hytale-api/sdk';

const api = new HytaleAPI();
const posts = await api.blog.getPosts();
```

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

### Plugin setup() Method for Registration

Source: https://hytale-docs.com/docs/modding/plugins/plugin-lifecycle

Illustrates the `setup()` method for Hytale plugins, the primary place for registering commands, event listeners, ECS systems, and assets. It uses various registry methods provided by the plugin framework.

```Java
@Override
protected void setup() {
    // Register commands
    getCommandRegistry().registerCommand(new MyCommand());

    // Register event listeners
    getEventRegistry().register(PlayerJoinEvent.class, this::onPlayerJoin);

    // Register ECS systems
    getEntityStoreRegistry().registerSystem(new MyEntitySystem());
    getChunkStoreRegistry().registerSystem(new MyChunkSystem());

    // Register assets
    getAssetRegistry().register(MyAsset.class, MyAsset.CODEC);

    // Log completion
    getLogger().info("Setup complete!");
}
```

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

### PlayerSettings Usage Examples in Java

Source: https://hytale-docs.com/docs/api/server-internals/ecs

Demonstrates how to obtain default PlayerSettings and create custom settings instances in Java. It also shows how to add these settings to a player entity using a command buffer.

```Java
// Get default settings
PlayerSettings settings = PlayerSettings.defaults();

// Create custom settings
PlayerSettings customSettings = new PlayerSettings(
    true,                       // showEntityMarkers
    PickupLocation.Inventory,   // armor -> inventory
    PickupLocation.Hotbar,      // weapons -> hotbar
    PickupLocation.Inventory,   // usables -> inventory
    PickupLocation.Inventory,   // blocks -> inventory
    PickupLocation.Inventory,   // misc -> inventory
    new PlayerCreativeSettings(true, false)  // creative settings
);
commandBuffer.addComponent(playerRef, PlayerSettings.getComponentType(), customSettings);
```

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

### Install VS Code Extensions for Java Development

Source: https://hytale-docs.com/docs/getting-started/environment-setup

Installs essential VS Code extensions for Java development, including the Java Extension Pack and the Red Hat Java language support. These enhance the IDE for working with Java-based Hytale plugins.

```bash
# Install recommended extensions
code --install-extension redhat.java
code --install-extension vscjava.vscode-java-pack
```

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

### Running Early Plugins and Transformers (Bash)

Source: https://hytale-docs.com/docs/api/server-internals/plugins

Demonstrates how to launch the Hytale server with early plugins using command-line arguments. It includes options for specifying plugin paths and skipping the confirmation prompt for early plugins.

```Bash
java -jar server.jar --early-plugins=/path/to/plugins
java -jar server.jar --accept-early-plugins  # Skip the confirmation prompt

```

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

### Start Hytale Server on Personal PC (Bash)

Source: https://hytale-docs.com/docs/servers/budget-hosting

This command starts the Hytale server on a personal computer using Java. It requires Java 25 to be installed and the hytale-server.jar file to be present in the current directory. The -Xms and -Xmx flags allocate memory to the server.

```bash
# Start the server
java -Xms4G -Xmx4G -jar hytale-server.jar

```

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

### Minimal Hytale Java Plugin Example

Source: https://hytale-docs.com/docs/modding/plugins/overview

A basic Hytale plugin demonstrating the structure for setup, event handling, and lifecycle methods (start, shutdown). It requires extending the JavaPlugin class and implementing its abstract methods. This example logs messages to the console and registers a simple player join event listener.

```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 MyFirstPlugin extends JavaPlugin {

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

    @Override
    protected void setup() {
        getLogger().info("Hello, Hytale!");

        // Register a simple event listener
        getEventRegistry().register(PlayerJoinEvent.class, event -> {
            getLogger().info("Player joined: " + event.getPlayer().getName());
        });
    }

    @Override
    protected void start() {
        getLogger().info("Plugin is now running!");
    }

    @Override
    protected void shutdown() {
        getLogger().info("Plugin shutting down...");
    }
}

```

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

### Hytale Color Palette Examples

Source: https://hytale-docs.com/docs/modding/art-assets/textures

Provides example color palettes for common materials in Hytale, illustrating the use of base colors with variations for shadows and highlights. These examples guide texture creation to match Hytale's art style.

```text
Base Colors (examples):
├── Grass:    #7cb342, #8bc34a, #9ccc65
├── Stone:    #78909c, #90a4ae, #b0bec5
├── Wood:     #8d6e63, #a1887f, #bcaaa4
├── Sand:     #ffe082, #ffca28, #ffc107
└── Water:    #4fc3f7, #29b6f6, #03a9f4
```

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

### Setup Packets

Source: https://hytale-docs.com/docs/api/server-internals/packets

Packets for initial world and asset configuration.

```APIDOC
## GET /websites/hytale-docs/setup-packets

### Description
Details the packets used for initial world and asset configuration in the Hytale network protocol.

### Method
GET

### Endpoint
/websites/hytale-docs/setup-packets

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```json
{
  "example": "No request body for this documentation endpoint."
}
```

### Response
#### Success Response (200)
- **packet_details** (object) - Information about setup packets.

#### Response Example
```json
{
  "packet_details": {
    "WorldSettings (ID: 20)": {
      "direction": "Server -> Client",
      "compressed": true,
      "description": "World configuration.",
      "fields": [
        {"name": "worldHeight", "type": "int", "description": "Maximum world height"},
        {"name": "requiredAssets", "type": "Asset[]?", "description": "List of required assets"}
      ],
      "size": "5+ bytes (variable, compressed)"
    }
  }
}
```
```

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

### Download and Run Hytale Server with Docker Compose

Source: https://hytale-docs.com/docs/servers/hosting/docker

This Bash script outlines the steps to prepare your environment and launch the Hytale server using Docker Compose. It includes creating necessary directories, downloading server files using a CLI tool (or manually copying them), and starting/viewing logs of the Docker container. Ensure you have `wget`, `unzip`, and `docker-compose` installed.

```bash
# Create directories
mkdir -p data/{worlds,config,mods,plugins} server-files

# Download server files using Hytale Downloader CLI (recommended)
wget https://downloader.hytale.com/hytale-downloader.zip
unzip hytale-downloader.zip
./hytale-downloader-linux-amd64
# Extract the Server folder and Assets.zip to server-files/

# Or copy from your Hytale launcher installation:
# Windows: %appdata%\Hytale\install\release\package\game\latest
# Linux: $XDG_DATA_HOME/Hytale/install/release/package/game/latest
# macOS: ~/Application Support/Hytale/install/release/package/game/latest

# Start container
docker-compose up -d

# View logs
docker-compose logs -f

```

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

### Enable and Start Hytale Systemd Service

Source: https://hytale-docs.com/docs/servers/hosting/self-hosting

Enables the Hytale systemd service to start automatically on boot and then starts the service immediately. This ensures the server runs reliably in the background.

```Bash
sudo systemctl enable hytale
sudo systemctl start hytale

```

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

### Initialize Gradle Java Library Project (Command Line)

Source: https://hytale-docs.com/docs/modding/plugins/project-setup

Initializes a new Java library project using Gradle from the command line. Supports both Groovy and Kotlin DSLs for build scripts. This is a foundational step for manual project setup.

```bash
# Create project directory
mkdir my-hytale-plugin
cd my-hytale-plugin

# Initialize Gradle wrapper
gradle init --type java-library --dsl groovy

# Or with Kotlin DSL
gradle init --type java-library --dsl kotlin
```

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

### Complete Java Plugin Example for Hytale

Source: https://hytale-docs.com/docs/api/server-internals/plugins

This Java code defines a complete Hytale plugin named GreetingPlugin. It extends the JavaPlugin class and overrides setup, start, and shutdown methods for plugin lifecycle management. It also includes a GreetCommand for in-game command execution and registers a PlayerJoinEvent handler.

```java
package com.example.greeting;

import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import com.hypixel.hytale.server.core.command.system.basecommands.CommandBase;
import com.hypixel.hytale.server.core.command.system.CommandContext;
import com.hypixel.hytale.server.core.Message;
import javax.annotation.Nonnull;

public class GreetingPlugin extends JavaPlugin {

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

    @Override
    protected void setup() {
        getLogger().info("Setting up GreetingPlugin...");

        // Register the command
        getCommandRegistry().registerCommand(new GreetCommand());

        // Register the event handler
        getEventRegistry().register(PlayerJoinEvent.class, event -> {
            event.getPlayer().sendMessage(
                Message.raw("Welcome to the server!")
            );
        });
    }

    @Override
    protected void start() {
        getLogger().info("GreetingPlugin started!");
    }

    @Override
    protected void shutdown() {
        getLogger().info("GreetingPlugin shutting down...");
    }

    private class GreetCommand extends CommandBase {
        public GreetCommand() {
            super("greet", "greeting.command.desc");
        }

        @Override
        protected void executeSync(@Nonnull CommandContext context) {
            context.sendMessage(Message.raw("Hello from GreetingPlugin!"));
        }
    }
}
```

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

### Hytale Inventory Usage Examples (Java)

Source: https://hytale-docs.com/docs/api/server-internals/ecs

Provides practical examples of how to use the Hytale Inventory class methods. Demonstrates common actions like moving items between inventory sections, smart equipping of armor, retrieving the item the player is currently holding, and adding items to the inventory.

```java
// Get player inventory
Player player = store.getComponent(playerRef, Player.getComponentType());
Inventory inventory = player.getInventory();

// Move item from storage to hotbar
inventory.moveItem(
    Inventory.STORAGE_SECTION_ID, 5,   // From storage slot 5
    64,                                 // Move 64 items
    Inventory.HOTBAR_SECTION_ID, 0     // To hotbar slot 0
);

// Smart equip armor
inventory.smartMoveItem(
    Inventory.STORAGE_SECTION_ID, 10,
    1,
    SmartMoveType.EquipOrMergeStack
);

// Get item in hand
ItemStack heldItem = inventory.getItemInHand();
if (heldItem != null && heldItem.getItem().getWeapon() != null) {
    // Player is holding a weapon
}

// Add items to player inventory (respects pickup location preferences)
PlayerSettings settings = store.getComponent(playerRef, PlayerSettings.getComponentType());
ItemContainer targetContainer = inventory.getContainerForItemPickup(item, settings);
targetContainer.addItemStack(itemStack);

```

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

### Install Java 25 on Ubuntu/Debian (Bash)

Source: https://hytale-docs.com/docs/servers/setup/installation

This bash script installs Java 25 (OpenJDK Temurin) on Ubuntu/Debian systems. It adds the Adoptium repository, imports the GPG key, and then installs the temurin-25-jdk package. Finally, it verifies the installation by printing the Java version.

```bash
# Add Adoptium repository
sudo apt update
sudo apt install wget apt-transport-https gpg
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo gpg --dearmor -o /etc/apt/keyrings/adoptium.gpg
echo "deb [signed-by=/etc/apt/keyrings/adoptium.gpg] 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

# Verify
java -version
# Should show: openjdk 25.0.x

```

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

### Hytale Plugin Manual Deployment (Command Line)

Source: https://hytale-docs.com/docs/modding/plugins/project-setup

This Bash command provides a quick way to build the plugin JAR and copy it directly to the Hytale server's plugins directory in a single step. This is useful for rapid development cycles.

```bash
# Build and copy to server in one command
./gradlew build && cp build/libs/*.jar ../hytale-server/plugins/
```

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

### AddPlayerToWorldEvent Usage Example

Source: https://hytale-docs.com/docs/modding/plugins/events/player/add-player-to-world-event

Example Java code demonstrating how to register handlers for the AddPlayerToWorldEvent to customize join messages and perform world-specific setup.

```APIDOC
## Usage Example

Since `AddPlayerToWorldEvent` implements `IEvent<String>` (non-Void key type), you must use `registerGlobal()` to catch all events regardless of their key.

```java
// Register a global handler for when players are added to worlds
eventBus.registerGlobal(AddPlayerToWorldEvent.class, event -> {
    World world = event.getWorld();
    String worldName = world != null ? world.getName() : "Unknown";

    // Log the event
    logger.info("Player being added to world: " + worldName);

    // Conditionally suppress join message
    if ("minigame_lobby".equals(worldName)) {
        // Don't broadcast in minigame lobbies
        event.setBroadcastJoinMessage(false);
    }
});

// Silent joins for staff
eventBus.registerGlobal(EventPriority.EARLY, AddPlayerToWorldEvent.class, event -> {
    Holder<EntityStore> holder = event.getHolder();

    // Check if player is staff with vanish enabled
    if (isStaffWithVanish(holder)) {
        event.setBroadcastJoinMessage(false);
    }
});

// Track world population
eventBus.registerGlobal(AddPlayerToWorldEvent.class, event -> {
    World world = event.getWorld();

    // Update world statistics
    incrementWorldPopulation(world);
});
```

**Important:** Using `register()` instead of `registerGlobal()` will not work for this event because it has a `String` key type.
```

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

### Handle Plugin Lifecycle Methods in Java

Source: https://hytale-docs.com/docs/api/server-internals/plugins

Properly manage the plugin lifecycle by implementing `setup` for initialization and `shutdown` for cleanup. The `setup` method is for resource initialization and registration, while `shutdown` handles resource deallocation and state saving.

```java
@Override
protected void setup() {
    // Initialise resources
    // Register commands, events, etc.
}

@Override
protected void shutdown() {
    // Clean up resources
    // Save data
    // Cancel tasks
}
```

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

### Install Java 25 on Debian

Source: https://hytale-docs.com/docs/servers/hosting/self-hosting

Installs Adoptium Temurin JDK 25 on Debian systems. Similar to Ubuntu, this requires adding the Adoptium repository and installing the JDK. This is necessary for the Hytale server.

```Bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install Java 25 (Adoptium)
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -
echo "deb https://packages.adoptium.net/artifactory/deb bookworm main" | sudo tee /etc/apt/sources.list.d/adoptium.list
sudo apt update
sudo apt install temurin-25-jdk -y

```

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

### Load Prefabs using PrefabStore (Java)

Source: https://hytale-docs.com/docs/api/server-internals/modules/prefab-system

Demonstrates various methods for loading prefabs using PrefabStore, including loading from server directories, asset packs, and searching across all asset packs. It also shows how to load an entire directory for weighted selection.

```java
// Load a prefab by relative path
BlockSelection prefab = PrefabStore.get().getServerPrefab("buildings/house.prefab.json");

// Load from asset packs
BlockSelection assetPrefab = PrefabStore.get().getAssetPrefab("structures/tower.prefab.json");

// Load a directory of prefabs (for weighted selection)
Map<Path, BlockSelection> prefabs = PrefabStore.get().getServerPrefabDir("buildings/houses");

// Find prefab across all asset packs
BlockSelection foundPrefab = PrefabStore.get().getAssetPrefabFromAnyPack("decorations/tree.prefab.json");

```

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

### Install Java 25 on Ubuntu

Source: https://hytale-docs.com/docs/servers/hosting/self-hosting

Installs Adoptium Temurin JDK 25 on Ubuntu systems. This involves adding the Adoptium repository and then installing the JDK package. It's a prerequisite for running the Hytale server.

```Bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install Java 25 (Adoptium)
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
sudo apt update
sudo apt install temurin-25-jdk -y

# Verify installation
java -version

```

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

### Plugin Lifecycle Management in Java

Source: https://hytale-docs.com/docs/modding/plugins/overview

Manages the lifecycle of a Hytale plugin by overriding methods for setup, start, and shutdown. The setup method is for initial registration of commands and events. The start method is called after all plugins are set up, allowing interaction with other plugins. The shutdown method is for cleaning up resources and saving data when the server stops.

```Java
@Override
protected void setup() {
    // Called first - register everything here
    getCommandRegistry().registerCommand(new MyCommand());
    getEventRegistry().register(PlayerJoinEvent.class, this::onJoin);
}

@Override
protected void start() {
    // Called after ALL plugins have completed setup()
    // Safe to interact with other plugins here
}

@Override
protected void shutdown() {
    // Called when server stops - clean up here
    savePlayerData();
}
```

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

### Hytale Server Startup Sequence

Source: https://hytale-docs.com/docs/servers/server-infrastructure

Outlines the sequential steps involved in booting the Hytale server, starting from argument parsing to server instantiation. This sequence ensures all necessary modules and configurations are initialized before the server becomes fully operational.

```text
1. Options.parse(args) -- Parse CLI arguments
2. HytaleLogger.init() -- Initialize logging
3. ConsoleModule.initializeTerminal() -- Create JLine terminal (singleplayer gets dumb mode)
4. HytaleFileHandler.INSTANCE.enable() -- Enable file logging
5. HytaleLogger.replaceStd() -- Redirect stdout/stderr
6. Configure log level loader (CLI levels take precedence over config levels)
7. new HytaleServer() -- Create and boot the server
```

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

### Full Plugin Manifest Example

Source: https://hytale-docs.com/docs/api/server-internals/plugins

Provides a comprehensive example of a plugin's manifest.json file, detailing all possible fields and their expected values. This includes metadata like Group, Name, Version, Description, Authors, as well as technical configurations such as Main class, ServerVersion, Dependencies, and asset pack inclusion.

```JSON
{
    "Group": "MyCompany",
    "Name": "MyPlugin",
    "Version": "1.0.0",
    "Description": "An example plugin for Hytale",
    "Authors": [
        {
            "Name": "Developer Name",
            "Email": "dev@example.com",
            "Url": "https://example.com"
        }
    ],
    "Website": "https://myplugin.example.com",
    "Main": "com.example.myplugin.MyPlugin",
    "ServerVersion": ">=0.1.0",
    "Dependencies": {
        "Hytale:CorePlugin": ">=1.0.0"
    },
    "OptionalDependencies": {
        "OtherCompany:OptionalPlugin": ">=2.0.0"
    },
    "LoadBefore": {
        "Hytale:SomePlugin": "*"
    },
    "DisabledByDefault": false,
    "IncludesAssetPack": true
}
```

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

### Example Update Configuration (JSON)

Source: https://hytale-docs.com/docs/servers/server-infrastructure

This JSON snippet provides an example configuration for the server's update settings. It demonstrates how to enable update checks, set the check interval, notify players about available updates, configure auto-apply modes, and manage backups before updates. This is a practical example for setting up the update system.

```JSON
{
  "Update": {
    "Enabled": true,
    "CheckIntervalSeconds": 3600,
    "NotifyPlayersOnAvailable": true,
    "AutoApplyMode": "WHEN_EMPTY",
    "AutoApplyDelayMinutes": 30,
    "RunBackupBeforeUpdate": true,
    "BackupConfigBeforeUpdate": true
  }
}
```

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

### Configuration Loading

Source: https://hytale-docs.com/docs/api/server-internals/plugins

Use `withConfig()` to define and load plugin configurations before the `setup()` method is called.

```APIDOC
## Configuration Loading

### Description
Use `withConfig()` to define plugin configurations that are loaded before `setup()` is called.

### Method
```java
protected <T> Config<T> withConfig(Codec<T> codec)
```

### Request Example
```java
public class MyPlugin extends JavaPlugin {
    private final Config<MyConfig> config;

    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);
        // This must be called before setup
        this.config = withConfig(MyConfig.CODEC);
    }

    @Override
    protected void setup() {
        MyConfig cfg = config.get();
        getLogger().info("Loaded config: " + cfg.getSomeSetting());
    }
}
```

### Response
#### Success Response (200)
N/A for configuration loading.

#### Response Example
N/A
```

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

### Install Hytale Server on Raspberry Pi 5 (Bash)

Source: https://hytale-docs.com/docs/servers/budget-hosting

This script installs Java 25 and sets up the directory structure for running a Hytale server on a Raspberry Pi 5. It assumes Raspberry Pi OS (64-bit) is already installed and updated.

```bash
# Install Raspberry Pi OS (64-bit)
# Update system
sudo apt update && sudo apt upgrade -y

# Install Java 25
sudo apt install -y openjdk-25-jdk

# Create server directory
mkdir ~/hytale-server
cd ~/hytale-server

```

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

### Getting an Entity's UI Components (Java)

Source: https://hytale-docs.com/docs/api/server-internals/modules/entity-ui

Example code demonstrating how to retrieve the UIComponentList for a given entity and access its component IDs. This involves obtaining the ComponentType and then using the store to get the component.

```java
// Get the component type
ComponentType<EntityStore, UIComponentList> componentType = UIComponentList.getComponentType();

// Get an entity's UI component list
UIComponentList uiList = store.getComponent(entityRef, componentType);

// Get the component IDs
int[] componentIds = uiList.getComponentIds();

```

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

### Start Hytale Server with Allocated RAM

Source: https://hytale-docs.com/docs/getting-started/known-issues

This command starts the Hytale server JAR file and allocates a specific amount of RAM. Adjust '-Xmx' for maximum RAM and '-Xms' for initial RAM. Example shown allocates 4GB.

```bash
java -Xmx4G -Xms4G -jar hytale-server.jar
```

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

### ChunkTracker Usage Examples (Java)

Source: https://hytale-docs.com/docs/api/server-internals/ecs

Demonstrates practical usage of the ChunkTracker component in Java, including retrieving the tracker, checking chunk status, configuring loading rates, and determining chunk visibility.

```Java
// Get chunk tracker for a player
ChunkTracker tracker = store.getComponent(playerRef, ChunkTracker.getComponentType());

// Check if a chunk is loaded for this player
long chunkIndex = ChunkUtil.indexChunk(chunkX, chunkZ);
if (tracker.isLoaded(chunkIndex)) {
    // Chunk is visible to player
}

// Configure chunk loading rate
tracker.setMaxChunksPerSecond(64);
tracker.setMaxChunksPerTick(8);

// Get chunk visibility
ChunkTracker.ChunkVisibility visibility = tracker.getChunkVisibility(chunkIndex);
if (visibility == ChunkTracker.ChunkVisibility.HOT) {
    // Chunk is actively ticking
}

// Clear all loaded chunks (for teleport/world change)
tracker.clear();

```

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

### Basic Java Plugin Structure

Source: https://hytale-docs.com/docs/api/server-internals/plugins

Demonstrates the fundamental structure of a Hytale plugin by extending the JavaPlugin class. It includes essential methods for setup, start, and shutdown phases, along with constructor requirements. This serves as a starting point for any plugin development.

```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 {

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

    @Override
    protected void setup() {
        // Called during the plugin setup phase
        getLogger().info("MyPlugin is setting up!");
    }

    @Override
    protected void start() {
        // Called when the plugin starts
        getLogger().info("MyPlugin has started!");
    }

    @Override
    protected void shutdown() {
        // Called when the plugin is being disabled
        getLogger().info("MyPlugin is shutting down!");
    }
}
```

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

### Example Server Log for PlayerSetupDisconnectEvent

Source: https://hytale-docs.com/docs/modding/plugins/events/player/player-setup-disconnect-event

This snippet shows example server log output when the `PlayerSetupDisconnectEvent` is fired. It includes messages from both a test logger and an event tracker, confirming the event and player details.

```log
[INFO] [TestLogger] [DocTest] Player Event: PlayerSetupDisconnectEvent | Player: Username
[INFO] [EventTracker] [DocTest] Event fired: PlayerSetupDisconnectEvent
```