Hytale Java Developer Docs

Scope & Accuracy

These docs combine official Hytale policy pages with runtime API signatures extracted from the current server build. Use this as the practical implementation guide for plugin/mod Java development on Hytale Depot.

Validation

This section documents how Dev Docs examples are checked against the current runtime jar.

Verification Command

python3 tools/generate_hytale_api_index.py ../HytaleServer.jar apps/web/lib/hytale-api-index.json && npm test

Development Tracks

Use these tracks as your build order: start with lifecycle/events, then gameplay domains, then premium licensing.

Quick Start Plugin (Java)

import com.hypixel.hytale.server.core.Message;
import com.hypixel.hytale.server.core.command.system.AbstractCommand;
import com.hypixel.hytale.server.core.command.system.CommandContext;
import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;

public final class StarterPlugin extends JavaPlugin {
  private final ScheduledExecutorService scheduler =
      Executors.newSingleThreadScheduledExecutor(r -> new Thread(r, "starter-heartbeat"));

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

  @Override
  public CompletableFuture<Void> preLoad() {
    getLogger().atInfo().log("preLoad -> %s", getIdentifier());
    return CompletableFuture.completedFuture(null);
  }

  @Override
  protected void setup() {
    getCommandRegistry().registerCommand(new StarterStatusCommand());
  }

  @Override
  protected void start() {
    scheduler.scheduleAtFixedRate(
        () -> getLogger().atInfo().log("starter heartbeat"),
        0,
        1,
        TimeUnit.SECONDS);
    getTaskRegistry().registerTask(CompletableFuture.completedFuture(null));
  }

  @Override
  protected void shutdown() {
    scheduler.shutdownNow();
  }

  private final class StarterStatusCommand extends AbstractCommand {
    private StarterStatusCommand() { super("hdstarter", "Starter plugin status command"); }

    @Override
    protected CompletableFuture<Void> execute(CommandContext ctx) {
      ctx.sendMessage(Message.raw("[Starter] plugin is active."));
      return CompletableFuture.completedFuture(null);
    }
  }
}

Event Handler Pattern

getEventRegistry().registerGlobal(PluginSetupEvent.class, event -> {
  // Register runtime handlers after plugin startup to avoid lifecycle issues.
  getLogger().atInfo().log("Plugin setup event: %s", event.getPlugin().getName());
  // Keep handler work small and move slow tasks to an async executor.
});

Server Operations

Practical dedicated-server operations validated against the current jar manifest, option strings, config classes, and shipped runtime artifacts in this workspace.

Launch Commands

Authentication + Network Checklist

/auth login device
Visit https://accounts.hytale.com/device
Enter the shown code and wait for "Authentication successful".

Windows: New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort <server-port> -Action Allow
Linux ufw: sudo ufw allow <server-port>/udp
Linux iptables: sudo iptables -A INPUT -p udp --dport <server-port> -j ACCEPT

Server File Layout

Observed from the current runtime artifacts plus the update/bootstrap expectations exposed by the jar. Use this as the baseline structure to keep updates, backups, and saves stable.

Server Config JSON (config.json)

Field-level behavior reference mapped to the generated config structure used by current server builds.

Example shape for the current server config model

{
  "Version": 4,
  "ServerName": "My Hytale Server",
  "MOTD": "Private test shard",
  "Password": "",
  "Host": "0.0.0.0",
  "Port": 5520,
  "MaxPlayers": 128,
  "MaxViewRadius": 8,
  "Defaults": { "World": "default", "GameMode": "Adventure" },
  "ConnectionTimeouts": {},
  "RateLimit": {},
  "Modules": {},
  "LogLevels": {},
  "Plugins": {},
  "Mods": {},
  "ModLoadOrder": [],
  "DefaultModsEnabled": true,
  "DisplayTmpTagsInStrings": false,
  "PlayerStorage": { "Type": "Hytale" },
  "AuthCredentialStore": { "Type": "Encrypted", "Path": "auth.enc" },
  "Update": {},
  "Backup": {},
  "WorldMap": {}
}

World Config JSON (universe/worlds/*/config.json)

World-level toggles directly control simulation, persistence, PvP behavior, and client-facing environment effects.

Update Config Reference (config.json -> Update)

Example shape for the current world config model

{
  "Version": 4,
  "DisplayName": "default",
  "Seed": 1768426248534,
  "WorldGen": { "Type": "Hytale", "Name": "Default", "Version": "0.0.0" },
  "WorldMap": {},
  "IsTicking": true,
  "IsBlockTicking": false,
  "IsPvpEnabled": false,
  "IsFallDamageEnabled": false,
  "IsGameTimePaused": true,
  "GameMode": "Adventure",
  "ClientEffects": {
    "SunHeightPercent": 100.0,
    "BloomIntensity": 0.30000001192092896
  },
  "IsSpawningNPC": false,
  "IsAllNPCFrozen": true,
  "IsSavingPlayers": true,
  "IsSavingChunks": true,
  "SaveNewChunks": false,
  "IsUnloadingChunks": false
}

Server Configuration Playbooks

Production-oriented baselines for common server styles. Use these as starting points and profile your own workload.

Server Config Reference (Runtime Domains)

This table maps high-value configuration domains from the current HytaleServer.jar runtime packages to practical option-level guidance.

JVM Startup Flags

Recommended Java startup profiles for Hytale server operators. Choose one profile and benchmark under real player load.

-Xms4G -Xmx4G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=80 -XX:+AlwaysPreTouch -XX:+DisableExplicitGC -XX:+PerfDisableSharedMem

-Xms6G -Xmx6G -XX:+UseZGC -XX:+ZGenerational -XX:+AlwaysPreTouch -XX:+DisableExplicitGC

-Xms2G -Xmx2G -XX:+UseG1GC -XX:MaxGCPauseMillis=120 -XX:+HeapDumpOnOutOfMemoryError

Assets Runtime Reference & Workflow

The current runtime treats assets as an immutable payload/cache input. Keep custom content in mod/plugin packs and avoid patching the shipped base assets directly.

Plugin/Mod Manifest Reference

Manifest fields used by starter resources and expected by the loader during startup.

{
  "Group": "HytaleDepot",
  "Name": "UiPluginTemplate",
  "Version": "1.0.0",
  "Description": "Hytale Depot plugin template for ui.",
  "Authors": [{ "Name": "Hytale Depot" }],
  "Website": "https://github.com/VgamerV3/hytale-plugin-template-ui",
  "ServerVersion": "2026.03.26-89796e57b",
  "Dependencies": {},
  "OptionalDependencies": {},
  "DisabledByDefault": false,
  "Main": "net.hytaledepot.templates.plugin.ui.UiPluginTemplate",
  "IncludesAssetPack": false
}

Core API Domains

Organized by practical development areas so plugin/mod developers can quickly locate the right runtime APIs.

Starter Templates (Plugin + Mod)

Starter repository references for core systems, UI, events, entities, networking, inventory, messages, permissions, commands, config, economy, persistence, advanced utilities, and smoke tests.

Treat these repositories as scaffolding references. Regenerate the runtime index against the latest jar before relying on any older starter code unchanged.

Top Runtime Packages

High-density package namespaces from the extracted jar index, useful for exploring subsystems quickly.

Licensing API Integration (Plugins/Mods)

Premium resources should validate keys at server startup and periodically at runtime, using creator integration tokens and signed responses.

Managed Injection Config Example

# HytaleDepot Integration Config - auto-injected at upload
plugin-secret: "build_scoped_hmac"
asset-id: "asset_uuid"
build-hash: "published_build_sha256"
secret-version: "4"
validate-endpoint: "https://hytaledepot.net/api/licenses/validate"
deployment-secret-env: "HD_DEPLOYMENT_SECRET"
asset-name: "Example Plugin"
asset-type: "plugin"

Managed Injection Runtime

Injected runtime behavior
1. Adds net.hytaledepot.runtime.HdLicenseBootstrap.class
2. Adds net.hytaledepot.runtime.HdLicenseCommand.class
3. Rewrites manifest.json Main -> net.hytaledepot.runtime.HdBootstrapWrapper
4. Wrapper calls HdLicenseBootstrap.validate(this) before the original setup path
5. First-run license entry uses /hdlicense <assetId> <licenseKey> or hd-licenses/<assetId>.pending
6. Verified buyer keys are cached in hd-licenses/<assetId>.key
7. If /api/status is in maintenance or unreachable, startup fail-opens for that boot only

Injected Validate Request Example

POST /api/licenses/validate
X-Plugin-Secret: <build_scoped_derived_secret>
Content-Type: application/json

{
  "asset_id": "asset_uuid",
  "license_key": "HD-XXXX-XXXX",
  "server_ip": "x.x.x.x",
  "build_hash": "published_build_sha256",
  "secret_version": "4",
  "deployment_secret": "server_only_secret",
  "timestamp": "1739553549000",
  "nonce": "abc12345",
  "signature": "HMAC_SHA256(pluginSecret, licenseKey|assetId|serverIp|timestamp|nonce)"
}

Startup Enforcement Example

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.UUID;

String API_VALIDATE = "https://hytaledepot.net/api/licenses/validate";
String API_STATUS = "https://hytaledepot.net/api/status";
String API_RUNTIME_TOKEN = "https://hytaledepot.net/api/licenses/runtime-token";
String ASSET_ID = "asset_uuid";
String LICENSE_KEY = readBuyerLicenseKey();
String BUILD_HASH = "build_sha256_here";
String DEPLOYMENT_SECRET = System.getenv("HD_DEPLOYMENT_SECRET");
String RUNTIME_TOKEN = requestRuntimeTokenFromCreatorRelay(API_RUNTIME_TOKEN, ASSET_ID, BUILD_HASH);
String SERVER_IP = detectServerIp();

if (isApiTemporarilyUnavailable(API_STATUS)) {
  System.err.println("[HD License] Licensing API is in maintenance or unreachable.");
  System.err.println("[HD License] Loading this startup without license activation; next restart will require validation again.");
  return;
}

String timestamp = String.valueOf(System.currentTimeMillis());
String nonce = UUID.randomUUID().toString();

String payload = "{"
    + "\"asset_id\":\"" + ASSET_ID + "\","
    + "\"license_key\":\"" + LICENSE_KEY + "\","
    + "\"server_ip\":\"" + SERVER_IP + "\","
    + "\"build_hash\":\"" + BUILD_HASH + "\","
    + "\"deployment_secret\":\"" + DEPLOYMENT_SECRET + "\","
    + "\"timestamp\":\"" + timestamp + "\","
    + "\"nonce\":\"" + nonce + "\""
    + "}";

HttpRequest request = HttpRequest.newBuilder(URI.create(API_VALIDATE))
    .header("Content-Type", "application/json")
    .header("X-License-Token", RUNTIME_TOKEN)
    .POST(HttpRequest.BodyPublishers.ofString(payload, StandardCharsets.UTF_8))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
boolean allowed = response.statusCode() == 200
    && (response.body().contains("\"allowed\":true") || response.body().contains("\"allowed\": true"));

if (!allowed) {
  String reason = extractJsonField(response.body(), "reason_code");
  System.err.println("[HD License] Validation denied: " + reason);
  Thread.sleep(5000);
  System.exit(1);
}

static boolean isApiTemporarilyUnavailable(String statusUrl) {
  try {
    HttpResponse<String> status = HttpClient.newHttpClient().send(
      HttpRequest.newBuilder(URI.create(statusUrl)).GET().build(),
      HttpResponse.BodyHandlers.ofString()
    );
    return status.statusCode() >= 500
        || status.body().contains("\"enabled\":true")
        || status.body().contains("\"enabled\": true");
  } catch (Exception ignored) {
    return true;
  }
}

Validate Request Example

{
  "asset_id": "asset_uuid",
  "license_key": "HD-XXXX-XXXX",
  "server_ip": "x.x.x.x",
  "build_hash": "build_sha256_here",
  "deployment_secret": "server_only_secret",
  "timestamp": "1739553549000",
  "nonce": "abc12345"
}

Validate Response Example

{
  "status": "invalid",
  "allowed": false,
  "reason_code": "ip_slots_exhausted",
  "expires_at": "2027-01-01T00:00:00.000Z",
  "offline_grace_seconds": 3600,
  "max_ip_slots": 2,
  "bindings": [{ "ip": "x.x.x.x", "lastSeenAt": "2026-04-02T10:21:00.000Z" }],
  "issued_at": "2026-02-15T09:12:21.000Z",
  "nonce": "r7FmK1ab",
  "signature": "hex_hmac_signature"
}

References

Use official Hytale references for policy/runtime guidance and community repositories for implementation patterns.