Документация разработчика 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 для руководства по политике и времени выполнения, а также репозитории сообщества для шаблонов реализации.