hytale-f2p-mirror/docs/UPDATE_SYSTEM_FIXES.md

Update System Fixes Summary

Overview

This document summarizes the fixes made to the launcher auto-update system to improve UX and fix macOS-specific issues.

Issues Fixed

1. Duplicate Update Popups

Problem: Two different update UI files (update.js and updater.js) were both listening for update events, causing duplicate popups to appear.

Solution:

• Disabled updater.js in index.html (commented out the script tag)
• Now only update.js handles all update UI with improved features

2. Missing Skip Button

Problem: Users were soft-locked on the update screen with no way to dismiss it, especially problematic on macOS where auto-install often fails.

Solution:

• Added "Skip for now (not recommended)" button to update popup
• Skip button appears:
  • After 30 seconds (timeout fallback)
  • Immediately on any update error
  • After install attempt fails (5 second timeout)
  • Always visible once download completes

3. macOS Auto-Install Failure

Problem: quitAndInstall() silently fails on unsigned macOS apps, leaving users stuck.

Solution:

• Detect macOS in main.js and send autoInstallSupported: false flag
• On macOS, show "Download Manually (Recommended)" as primary action
• "Try Install & Restart" shown as secondary option
• Added force quit fallback in install-update handler for macOS
• Clear messaging: "Update downloaded but auto-install may not work on macOS"

4. Missing IPC Handlers

Problem: open-download-page IPC handler was not registered, causing errors when clicking manual download.

Solution:

• Added open-download-page handler in main.js that opens GitHub releases page
• Added quitAndInstallUpdate alias in preload.js for compatibility

5. Interface Blocking Not Removed

Problem: unblockInterface() method was called but never defined, leaving the UI blurred after closing popup.

Solution:

• Added complete unblockInterface() method that:
  • Removes interface-blocked class from main content
  • Removes no-select class from body
  • Properly removes event listeners using stored bound function references

6. Breathing Animation on Downloaded State

Problem: The pulse/breathing animation continued after download completed, which felt inappropriate for a "ready to install" state.

Solution:

• Remove update-popup-pulse class in showUpdateDownloaded() method

7. Player Name Not Synced on First Install

Problem: Player name entered during installation wasn't synced to settings page input.

Solution:

• In install.js, sync player name to both playerName and settingsPlayerName inputs after installation completes

Files Modified

GUI/index.html

• Commented out updater.js script tag (duplicate update UI)

GUI/js/update.js

• Removed legacy onUpdatePopup listener
• Added closeUpdatePopup() method
• Added unblockInterface() method
• Added skip button to popup HTML
• Added skip button visibility logic (30s timeout, on error, after download)
• Added macOS detection and alternative UI (manual download as primary)
• Removed pulse animation when download completes
• Added console logging for debugging
• Added extra DOM check to prevent duplicate popups
• Fixed manual download button to show "Opened in browser" and close popup

main.js

• Changed autoUpdater.autoDownload from false to true
• Added macOS error handling with requiresManualDownload flag
• Added autoInstallSupported flag to update-downloaded event
• Added open-download-page IPC handler
• Enhanced install-update handler with macOS force quit fallback

preload.js

• Added quitAndInstallUpdate alias for install-update IPC

GUI/js/install.js

• Sync player name to settingsPlayerName input after installation

backend/utils/clientPatcher.js

• Removed server patching code (server uses pre-patched JAR from CDN)
• Simplified to client-only patching
• Removed unused imports: crypto, AdmZip, execSync, spawn, getJavaExec, getBundledJavaPath, JRE_DIR
• Removed unused methods: stringToUtf8(), findAndReplaceDomainUtf8()
• Cleaned up comments and documentation
• Localhost/local dev code moved to clientPatcher.localhost.js.bak for reference

Testing

To test the update popup manually, you can temporarily add this debug code to update.js init():

// DEBUG: Simulate update available popup after 2 seconds
setTimeout(() => {
    this.showUpdatePopup({
        currentVersion: '2.0.0',
        newVersion: '2.1.0',
        releaseNotes: 'Debug test update'
    });

    // Simulate download complete after 3 more seconds
    setTimeout(() => {
        this.showUpdateDownloaded({
            version: '2.1.0',
            platform: 'darwin',
            autoInstallSupported: false  // Simulate macOS
        });
    }, 3000);
}, 2000);

Platform-Specific Behavior

Windows/Linux

• Auto-download enabled
• "Install & Restart" as primary action
• Skip button available as fallback

macOS

• Auto-download enabled (download works, install doesn't)
• "Download Manually (Recommended)" as primary action
• "Try Install & Restart" as secondary option
• Skip button always visible after download
• Force quit fallback if quitAndInstall fails