Documentatie Dezvoltator Hytale Java

Domeniu de aplicare și acuratețe

Aceste documente combină paginile oficiale de politică Hytale cu semnăturile API de rulare extrase din versiunea curentă a serverului. Utilizați acesta ca ghid practic de implementare pentru dezvoltarea plugin/mod Java pe Hytale Depot.

Validare

Această secțiune documentează modul în care exemplele Dev Docs sunt verificate în raport cu jarul de rulare curent.

Comanda de verificare

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

Piste de dezvoltare

Folosiți aceste piese ca ordine de construcție: începeți cu ciclul de viață/evenimente, apoi domeniile de joc, apoi licențele premium.

Plugin de pornire rapidă (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);
    }
  }
}

Model de gestionare a evenimentelor

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
}

Manuale de configurare a serverului

Linii de bază orientate spre producție pentru stiluri comune de server. Folosiți-le ca puncte de plecare și profilați-vă propria sarcină de lucru.

Server Config Reference (Runtime Domains)

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

Indicatori de pornire JVM

Profiluri de pornire Java recomandate pentru operatorii de servere Hytale. Alegeți un profil și un punct de referință sub sarcina reală a jucătorului.

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

Domeniile API de bază

Organizat pe zone practice de dezvoltare, astfel încât dezvoltatorii de pluginuri/moduri să poată localiza rapid API-urile de rulare potrivite.

Șabloane de pornire (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.

Topul pachetelor Runtime

Spații de nume de pachete de mare densitate din indexul jar extras, utile pentru explorarea rapidă a subsistemelor.

Integrare API de licențiere (Plugin-uri/Mod-uri)

Resursele premium ar trebui să valideze cheile la pornirea serverului și periodic în timpul execuției, folosind jetoane de integrare a creatorului și răspunsuri semnate.

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

Exemplu de aplicare a pornirii

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

Exemplu de solicitare de validare

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

Validare exemplu de răspuns

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

Referințe

Folosiți referințe oficiale Hytale pentru îndrumări privind politicile/execuția și depozitele comunității pentru modelele de implementare.