Hytale Pterodactyl Egg Enterprise v3.0.0

# Changelog — GlassDev Ops Hytale Egg v3.0.0

Release: 3.0.0 — "Early Access Alignment"
Date: 2026-07-07
File: egg-hytale-glassdevops-enterprise-v3_0_0.json
Supersedes: 2.0.1

Target platform: Hytale Early Access (Server Manual, Jun 2026).
Runtime: Java 25, QUIC over UDP. Auth: per-customer device login.

---

## Summary

A full correctness rewrite. The uploaded 2.0.1 egg was built against a
pre-Early-Access assumption of the Hytale server and no longer matched the
shipped game: it offered a Java version that won't start, invented flags that
don't exist, and — most seriously — its crash-recovery loop broke Hytale's
built-in self-updater. 3.0.0 brings the egg in line with the official server
manual and adds the hardening a hosting deployment expects.

Breaking release. Java 25 is now mandatory, the on-disk layout changed, and
the entrypoint was renamed. See Migration below before upgrading existing
servers.

Click to expand...

---

## Added

- Allow Operators toggle (ALLOW_OP, default off) — omits --allow-op
so players cannot self-promote via /op self. Closes a server-takeover hole
that is open by default on a vanilla Hytale server.
- Built-in world backups — --backup --backup-dir backups --backup-frequency,
exposed via ENABLE_BACKUPS and BACKUP_FREQUENCY. Independent of Pterodactyl
backups.
- AOT cache support (-XX:AOTCache=HytaleServer.aot when present) for faster
JVM startup.
- HYTALE_DISABLE_UPDATES toggle for Hytale's built-in auto-updater (with a
warning that a stale server can become unjoinable due to protocol lockstep).
- DISABLE_SENTRY toggle (--disable-sentry) to stop crash reports to
Hypixel — recommended during plugin/mod development.
- EXTRA_JAVA_ARGS variable plus support for a jvm.options file in the
server root.
- SERVER_NAME / SERVER_MOTD propagated into Server/config.json via the
panel (applied on restart; created after first boot).
- Device-auth reminder — a clear "run /auth login device" banner is printed
when Server/auth.enc is missing in authenticated mode.
- Readiness detection via a /proc/net/udp port-binding probe, so Pterodactyl
flips to "running" on a real listening socket rather than a faked log line.

## Changed

- Java 25 is now required. The Docker image list is reduced to Java 25
(Temurin), and a startup guard hard-fails on Java < 25 with a clear message.
- Adopted the official Server/ + Assets.zip layout. The server is launched
with cwd=Server/ and --assets ../Assets.zip. Hytale's built-in updater
requires this layout; without it the update checker is disabled. Runtime files
(config.json, universe/, logs/, mods/) now live under Server/.
- Downloader flags corrected to single-dash (-patchline, -download-path)
to match the actual Hytale Downloader CLI.
- Downloader binary located dynamically — handles both
hytale-downloader-linux-<arch> and bin/hytale-downloader archive layouts.
- Non-destructive updates — forced re-downloads extract selectively (jar, AOT
cache, assets, licenses only), preserving config, worlds and mods.
- FORCE_CLEAN is now safe — it removes only the server binaries and
Assets.zip, never worlds or config.
- Entrypoint renamed start.sh → gdops-start.sh, so the official
start.sh that ships inside the server download can coexist without clobbering
the Pterodactyl entrypoint. Startup command is now bash ./gdops-start.sh.
- Stop signal changed to ^C (SIGINT) — Hytale's documented graceful stop,
which flushes saves. The wrapper traps INT/TERM and forwards to the server with
a 30s grace period before SIGKILL.

## Fixed

- Exit code 8 is now handled as a staged self-update, not a crash. On exit 8
the wrapper applies updater/staging/ (jar/AOT/assets, preserving config and
worlds), resets the crash counter, and restarts. Under 2.0.1 this counted as a
crash and prevented Hytale from ever applying an update.
- Crash-recovery could never fire. With set -e, a non-zero wait exited the
script before the exit code was read, so the recovery branch was unreachable.
Switched to set -uo pipefail with explicit exit-code handling; clean exits
(0/130/143) stop, real crashes recover within the retry window.

## Removed

• Java 21 Docker image — Hytale will not start on it.
• --transport QUIC/TCP variable and flag — Hytale is QUIC-over-UDP only;

there is no TCP transport. Passing it risked the server rejecting the argument.
- "Auth persistence via machine-id" logic — not how Hytale works. Real
persistence is the Server/auth.enc + Server/auth.key files, which survive in
the volume on their own.

## Security

- file_denylist corrected to the real sensitive files (Server/auth.enc,
Server/auth.key, hytale-downloader/*.json) instead of the non-existent paths
denied in 2.0.1 — prevents subusers from exfiltrating the server's identity
tokens.
- --auth-mode value corrected to offline (2.0.1 used the invalid
unauthenticated, which the server would reject).
- Operators locked down by default — see ALLOW_OP above.

---

## Migration from 2.0.1

1. Switch the Docker image to Java 25 (Temurin). Anything older will not boot.
2. Back up first. Because the runtime layout moves under Server/, take a
Pterodactyl backup before upgrading a populated server.
3. Re-authenticate if needed. Auth now persists via Server/auth.enc /
Server/auth.key. If those files aren't present after upgrade, run
/auth login device once in the console.
4. Reset FORCE_CLEAN to 0 after any use — its behavior changed (binaries
only), but leaving it on still forces an unnecessary re-download each boot.
5. --transport is gone. If your provisioning set HYTALE_TRANSPORT, drop
it; it no longer exists.
6. Entrypoint changed. The startup command is bash ./gdops-start.sh. If you
pinned bash ./start.sh anywhere in automation, update it.

## Requirements

• Java 25 (Temurin) — enforced at startup.
• ≥ 4 GB RAM recommended (6 GB for small multiplayer); assets need ~2 GB free.
• One UDP port (SERVER_PORT); QUIC only — TCP is not used.

Fixed​

• Critical download failure – Removed the overly strict file command zip validation that was causing "Downloaded file is not a valid zip archive" errors on some hosts.
• Installer now uses a tolerant size-based check + clear logging for much higher reliability.
• Version numbering and description updated for clarity.

Improvements​

• Updated installer to v2.0.1 with consistent versioning across name, script, and logs.
• Better error messages and logging throughout the installation process.
• Minor cleanup in start.sh (set -euo pipefail for safer variable handling).

Features (Carried over from v2.0.0)​

• Multi-arch downloader support (amd64 + arm64) with architecture detection and preservation
• Crash loop recovery with configurable retries and delay
• Graceful SIGTERM shutdown with timeout and fallback to SIGKILL
• Pre-start validation (disk space, Java availability, RAM percentage, port check)
• Automatic backup before auto-update + old backup pruning
• Lock file protection to prevent multiple instances
• Persistent machine-id generation for auth cache
• Version tracking (.hytale-version with SHA256)
• Optional JVM diagnostics (GC logging + heap dumps)
• Percentage-based JVM RAM allocation (Max/Initial %)
• QUIC/TCP transport toggle + custom bind address
• Force clean and auto-download/auto-update options

Notes​

• This version maintains full feature parity with v2.0.0 while resolving the installation issue that affected some Pterodactyl hosts.
• Recommended upgrade for all users. Existing servers will continue to work after re-install or manual update of the egg.

This release focuses on stability, authentication persistence, runtime resilience, and production-grade lifecycle handling.

Major Improvements​

Fixed Authentication Persistence (Encrypted Credential Stability)​

• Resolved hardware UUID issues inside containers.
• Added automatic /etc/machine-id generation if missing.
• Prevents OAuth device login from reverting to memory-only credentials.
• Eliminates repeated re-authentication after restart.

Result: Stable persistent login across restarts.

Runtime Auto-Download Logic Hardened​

• Smart detection of missing Server/HytaleServer.jar or assets.
• Conditional download via AUTO_DOWNLOAD.
• Forced redownload via AUTO_UPDATE.
• Safe file validation before server launch.

Result: No more silent startup failures.

Java Fallback Extraction (Self-Healing Unzip)​

• Native unzip used when available.
• Automatic Java-based fallback extractor if unzip is missing.
• Prevents container image dependency issues.
• Works on minimal or stripped-down Docker yolks.

Result: Extraction always succeeds, even without native unzip.

Downloader & Credential Preservation​

• Installer no longer wipes the Hytale downloader.
• Preserves cached OAuth credentials.
• Prevents forced re-authentication on reinstall.

Result: Cleaner lifecycle behavior for hosting providers.

Panel Import Stability​

• Fixed malformed JSON structure.
• Removed syntax errors causing 500 import failures.
• Updated stop command handling (stop instead of ^C).
• Fully PTDL_v2 compliant.

Result: Clean import on all supported Pterodactyl versions.

🛠 Architecture Refinement​

• Reduced redundant logic.
• Removed duplicate download pathways.
• Simplified lifecycle control.
• Clear separation between install phase and runtime phase.
• Runtime-driven environment variable model.

This version is leaner, but more stable and more intentional.

Configuration Controls​

Supports:

• HYTALE_PATCHLINE (release / pre-release)
• AUTO_DOWNLOAD
• AUTO_UPDATE
• FORCE_CLEAN
• HYTALE_AUTH_MODE
• HYTALE_TRANSPORT
• JVM memory tuning variables

All variables are handled natively through runtime environment injection.

Version Classification​

This is the Enterprise Runtime Model.


Includes:

• Auth persistence stabilization
• Self-healing extraction
• Runtime lifecycle automation
• Production-safe failure handling

Recommended Use Case​

Designed for:

• Hosting providers
• Multi-node deployments
• Production Hytale networks
• Managed service environments

We’ve rolled out a significant update to the Hytale (GlassMC Enterprise) Pterodactyl egg. This release focuses on correctness, automation, and long-term maintainability, bringing the egg in line with GlassMC operational standards and modern Hytale deployment expectations.

What Changed​

1. Official Hytale Downloader Integration

• The egg now uses the official Hytale Downloader directly.
• Supports OAuth device login flows as designed by Hytale.
• Eliminates manual jar management and third-party mirrors.

2. Deterministic Startup via start.sh

• Server startup logic has been moved into a generated start.sh script.
• This ensures predictable execution order, cleaner logging, and easier debugging.
• Java is now invoked only after assets, patchline, and configuration checks pass.

3. Patchline Support (Release / Pre-release)

• Added a first-class HYTALE_PATCHLINE variable.
• Operators can switch between release and pre-release without rebuilding servers.

4. Automated Download & Update Controls
New operator toggles:

• Auto-download – fetch server files automatically if missing.
• Auto-update – refresh server files on startup.
• Force clean – wipe server assets and re-pull from source.

These controls reduce drift and eliminate manual recovery steps.


5. Transport & Auth Mode Configuration

• Explicit support for QUIC vs TCP transport.
• Configurable authenticated vs offline auth modes.
• All exposed cleanly through startup variables—no file edits required.

6. Modern JVM Resource Management

• Migrated to Java 25 (Temurin).
• Memory is now governed by percentage-based RAM allocation, not hard limits.
• Tuned defaults for containerized environments (G1GC, OOM exit handling).

7. Cleaner Container & Install Flow

• Alpine-based installer for fast, minimal provisioning.
• Only required packages are installed.
• No legacy Java/Minecraft variables or assumptions remain.

Result​

• More reliable first boot
• Safer updates
• Cleaner restarts
• Fewer “mystery failures”
• Enterprise-ready behavior without sacrificing flexibility

As always, report any edge cases or feedback so we can continue tightening the loop.


GlassMC Operations

What Changed​

• Corrected the uploaded egg file to the intended GlassMC Interactive Auth version
• Fixed packaging mismatch caused by an incorrect initial upload
• No functional regressions introduced

Why This Update Was Made​

An incorrect file variant was accidentally uploaded during the initial listing.
This update ensures the download matches the documented behavior and installation instructions described in the listing.

Impact to Existing Buyers​

• No action required if you have already re-downloaded the updated file
• Please re-download the egg to ensure you are using the corrected version
• Authentication flow and setup steps remain the same

New Requirement (Critical)​

To ensure authentication persists across restarts:

• Pterodactyl Wings v1.12.1 or newer is required

Without this update:

• Hytale cannot generate a stable encryption key
• /auth persistence encrypted will fail
• Re-authentication will be required on every restart

With this update:

• Encrypted auth persistence works correctly
• Tokens survive restarts
• No repeated /auth login device required

Correct Authentication Flow (Updated)​

1. Start the server in offline mode
2. Run:
   
   /auth login device
3. Complete device authentication
4. Run:
   
   /auth persistence encrypted
5. Stop the server
6. Set HYTALE_AUTH_MODE=authenticated
7. Start the server normally

Notes​

Encrypted authentication persistence requires Pterodactyl Wings v1.12.1 or newer. Older Wings versions may require re-authentication on restart due to missing machine identifiers.
This update does not change licensing, authentication requirements, or supported workflows.
It is a corrective release to align the download with the advertised configuration.