Документація розробника Hytale Java

Обсяг і точність

Ці документи поєднують офіційні сторінки політики Hytale із сигнатурами API часу виконання, отриманими з поточної збірки сервера. Використовуйте це як практичний посібник із впровадження плагінів/модів для розробки Java на Hytale Depot.

Перевірка

У цьому розділі описано, як приклади Dev Docs перевіряються на поточний jar.

Команда перевірки

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

Треки розвитку

Використовуйте ці доріжки як порядок збирання: починайте з життєвого циклу/подій, потім домени ігрового процесу, потім преміум-ліцензування.

Плагін швидкого запуску (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);
    }
  }
}

Шаблон обробника подій

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 Config Reference (Runtime Domains)

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

Прапори запуску JVM

Рекомендовані профілі запуску Java для операторів серверів Hytale. Виберіть один профіль і бенчмарк при реальному навантаженні гравця.

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

Основні домени API

Упорядковано за практичними областями розробки, щоб розробники плагінів/модів могли швидко знайти потрібні API для виконання.

Стартові шаблони (плагін + мод)

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.

Найкращі пакети середовища виконання

Простори імен пакетів високої щільності з вилученого індексу jar, корисні для швидкого вивчення підсистем.

Інтеграція API ліцензування (плагіни/моди)

Ресурси преміум-класу повинні перевіряти ключі під час запуску сервера та періодично під час виконання, використовуючи маркери інтеграції творця та підписані відповіді.

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

Приклад примусового виконання запуску

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

Приклад запиту перевірки

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

Приклад перевірки відповіді

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

Список літератури

Використовуйте офіційні посилання Hytale для вказівок щодо політики/виконання та репозиторії спільноти для шаблонів впровадження.