Documentazione sviluppatore Hytale Java

Ambito e precisione

Questi documenti combinano le pagine delle policy ufficiali di Hytale con le firme API runtime estratte dalla build del server corrente. Usalo come guida pratica all'implementazione per lo sviluppo di plug-in/mod Java su Hytale Depot.

Validazione

Questa sezione documenta il modo in cui gli esempi di Dev Docs vengono confrontati con il jar di runtime corrente.

Comando di verifica

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

Tracce di sviluppo

Utilizza questi percorsi come ordine di creazione: inizia con il ciclo di vita/gli eventi, quindi i domini di gioco, quindi la licenza premium.

Plug-in di avvio rapido (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);
    }
  }
}

Modello del gestore eventi

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
}

Playbook di configurazione del server

Linee di base orientate alla produzione per stili di server comuni. Usali come punti di partenza e profila il tuo carico di lavoro.

Server Config Reference (Runtime Domains)

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

Flag di avvio JVM

Profili di avvio Java consigliati per gli operatori di server Hytale. Scegli un profilo e confrontalo con il carico del giocatore reale.

-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
}

Domini API principali

Organizzato per aree di sviluppo pratiche in modo che gli sviluppatori di plug-in/mod possano individuare rapidamente le API runtime corrette.

Modelli iniziali (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.

I migliori pacchetti runtime

Spazi dei nomi dei pacchetti ad alta densità dall'indice jar estratto, utili per esplorare rapidamente i sottosistemi.

Integrazione API di licenza (plugin/mod)

Le risorse Premium devono convalidare le chiavi all'avvio del server e periodicamente in fase di esecuzione, utilizzando token di integrazione del creatore e risposte firmate.

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)"
}

Esempio di applicazione all'avvio

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;
  }
}

Esempio di richiesta di convalida

{
  "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"
}

Esempio di risposta di convalida

{
  "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"
}

Riferimenti

Utilizzare i riferimenti ufficiali Hytale per indicazioni su policy/runtime e repository della comunità per i modelli di implementazione.