shironeko/Hytale-F2P-2
1
0
Fork 0
mirror of https://gitea.shironeko-all.duckdns.org/shironeko/Hytale-F2P-2.git synced 2026-02-26 02:31:46 -03:00
Code Issues Packages Projects Releases Wiki Activity

Remove outdated documentation files related to auto-updates, build instructions, and testing updates. Update dev-app-update.yml and package.json to reflect the correct GitHub owner. This cleanup streamlines the project and ensures accurate configuration for future updates.

Browse Source
This commit is contained in:
chasem-dev
2026-01-22 13:05:34 -05:00
parent a1c74e4175
commit b54eb4e834
6 changed files with 2 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

284
docs/AUTO-UPDATES.md Normal file
View File

@@ -0,0 +1,284 @@
# Auto-Updates System
This document explains how the automatic update system works in the Hytale F2P Launcher.
## Overview
The launcher uses [electron-updater](https://www.electron.build/auto-update) to automatically check for, download, and install updates. When a new version is available, users are notified and the update is downloaded in the background.
## How It Works
### 1. Update Checking
- **Automatic Check**: The app automatically checks for updates 3 seconds after startup
- **Manual Check**: Users can manually check for updates through the UI
- **Update Source**: Updates are fetched from GitHub Releases
### 2. Update Process
1. **Check for Updates**: The app queries GitHub Releases for a newer version
2. **Notify User**: If an update is available, the user is notified via the UI
3. **Download**: The update is automatically downloaded in the background
4. **Progress Tracking**: Download progress is shown to the user
5. **Install**: When the download completes, the user can choose to install immediately or wait until the app restarts
### 3. Installation
- Updates are installed when the app quits (if `autoInstallOnAppQuit` is enabled)
- Users can also manually trigger installation through the UI
- The app will restart automatically after installation
## Version Detection & Comparison
### Current Version Source
The app's current version is read from `package.json`:
```json
{
"version": "2.0.2b"
}
```
This version is embedded into the built application and is accessible via `app.getVersion()` in Electron. When the app is built, electron-builder also creates an internal `app-update.yml` file in the app's resources that contains this version information.
### How Version Detection Works
1. **Current Version**: The app knows its own version from `package.json`, which is:
- Read at build time
- Embedded in the application binary
- Stored in the app's metadata
2. **Fetching Latest Version**: When checking for updates, electron-updater:
- Queries the GitHub Releases API: `https://api.github.com/repos/amiayweb/Hytale-F2P/releases/latest`
- Or reads the update metadata file: `https://github.com/amiayweb/Hytale-F2P/releases/download/latest/latest.yml` (or `latest-mac.yml` for macOS)
- The metadata file contains:
```yaml
version: 2.0.3
releaseDate: '2024-01-15T10:30:00.000Z'
path: Hytale-F2P-Launcher-2.0.3-x64.exe
sha512: ...
```
3. **Version Comparison**: electron-updater uses semantic versioning comparison:
- Compares the **current version** (from `package.json`) with the **latest version** (from GitHub Releases)
- Uses semantic versioning rules: `major.minor.patch` (e.g., `2.0.2` vs `2.0.3`)
- An update is available if the remote version is **greater than** the current version
- Examples:
- Current: `2.0.2` → Remote: `2.0.3` ✅ Update available
- Current: `2.0.2` → Remote: `2.0.2` ❌ No update (same version)
- Current: `2.0.3` → Remote: `2.0.2` ❌ No update (current is newer)
- Current: `2.0.2b` → Remote: `2.0.3` ✅ Update available (prerelease tags are handled)
4. **Version Format Handling**:
- **Semantic versions** (e.g., `1.0.0`, `2.1.3`) are compared numerically
- **Prerelease versions** (e.g., `2.0.2b`, `2.0.2-beta`) are compared with special handling
- **Non-semantic versions** may cause issues - it's recommended to use semantic versioning
### Update Metadata Files
When you build and publish a release, electron-builder generates platform-specific metadata files:
**Windows/Linux** (`latest.yml`):
```yaml
version: 2.0.3
files:
- url: Hytale-F2P-Launcher-2.0.3-x64.exe
sha512: abc123...
size: 12345678
path: Hytale-F2P-Launcher-2.0.3-x64.exe
sha512: abc123...
releaseDate: '2024-01-15T10:30:00.000Z'
```
**macOS** (`latest-mac.yml`):
```yaml
version: 2.0.3
files:
- url: Hytale-F2P-Launcher-2.0.3-arm64-mac.zip
sha512: def456...
size: 23456789
path: Hytale-F2P-Launcher-2.0.3-arm64-mac.zip
sha512: def456...
releaseDate: '2024-01-15T10:30:00.000Z'
```
These files are:
- Automatically generated during build
- Uploaded to GitHub Releases
- Fetched by electron-updater to check for updates
- Used to determine if an update is available and what to download
### The Check Process in Detail
When `appUpdater.checkForUpdatesAndNotify()` is called:
1. **Read Current Version**: Gets version from `app.getVersion()` (which reads from `package.json`)
2. **Fetch Update Info**:
- Makes HTTP request to GitHub Releases API or reads `latest.yml`
- Gets the version number from the metadata
3. **Compare Versions**:
- Uses semantic versioning comparison (e.g., `semver.gt(remoteVersion, currentVersion)`)
- If remote > current: update available
- If remote <= current: no update
4. **Emit Events**:
- `update-available` if newer version found
- `update-not-available` if already up to date
5. **Download if Available**: If `autoDownload` is enabled, starts downloading automatically
### Example Flow
```
App Version: 2.0.2 (from package.json)
↓
Check GitHub Releases API
↓
Latest Release: 2.0.3
↓
Compare: 2.0.3 > 2.0.2? YES
↓
Emit: 'update-available' event
↓
Download update automatically
↓
Emit: 'update-downloaded' event
↓
User can install on next restart
```
## Components
### AppUpdater Class (`backend/appUpdater.js`)
The main class that handles all update operations:
- **`checkForUpdatesAndNotify()`**: Checks for updates and shows a system notification if available
- **`checkForUpdates()`**: Manually checks for updates (returns a promise)
- **`quitAndInstall()`**: Quits the app and installs the downloaded update
### Events
The AppUpdater emits the following events that the UI can listen to:
- `update-checking`: Update check has started
- `update-available`: A new update is available
- `update-not-available`: App is up to date
- `update-download-progress`: Download progress updates
- `update-downloaded`: Update has finished downloading
- `update-error`: An error occurred during the update process
## Configuration
### Package.json
The publish configuration in `package.json` tells electron-builder where to publish updates:
```json
"publish": {
"provider": "github",
"owner": "amiayweb",
"repo": "Hytale-F2P"
}
```
This means updates will be fetched from GitHub Releases for the `amiayweb/Hytale-F2P` repository.
## Publishing Updates
### For Developers
1. **Update Version**: Bump the version in `package.json` (e.g., `2.0.2b` → `2.0.3`)
2. **Build the App**: Run the build command for your platform:
```bash
npm run build:win # Windows
npm run build:mac # macOS
npm run build:linux # Linux
```
3. **Publish to GitHub**: When building with electron-builder, it will:
- Generate update metadata files (`latest.yml`, `latest-mac.yml`, etc.)
- Upload the built files to GitHub Releases (if configured with `GH_TOKEN`)
- Make them available for auto-update
4. **Release on GitHub**: Create a GitHub Release with the new version tag
### Important Notes
- **macOS Code Signing**: macOS apps **must** be code-signed for auto-updates to work
- **Version Format**: Use semantic versioning (e.g., `1.0.0`, `2.0.1`) for best compatibility
- **Update Files**: electron-builder automatically generates the required metadata files (`latest.yml`, etc.)
## Testing Updates
### Development Mode
To test updates during development, create a `dev-app-update.yml` file in the project root:
```yaml
owner: amiayweb
repo: Hytale-F2P
provider: github
```
Then enable dev mode in the code:
```javascript
autoUpdater.forceDevUpdateConfig = true;
```
### Local Testing
For local testing, you can use a local server (like Minio) or a generic HTTP server to host update files.
## User Experience
### What Users See
1. **On Startup**: The app silently checks for updates in the background
2. **Update Available**: A notification appears if an update is found
3. **Downloading**: Progress bar shows download status
4. **Ready to Install**: User is notified when the update is ready
5. **Installation**: Update installs on app restart or when user clicks "Install Now"
### User Actions
- Users can manually check for updates through the settings/update menu
- Users can choose to install immediately or wait until next app launch
- Users can continue using the app while updates download in the background
## Troubleshooting
### Updates Not Working
1. **Check GitHub Releases**: Ensure releases are published on GitHub
2. **Check Version**: Make sure the version in `package.json` is higher than the current release
3. **Check Logs**: Check the app logs for update-related errors
4. **Code Signing (macOS)**: Verify the app is properly code-signed
### Common Issues
- **"Update not available"**: Version in `package.json` may not be higher than the current release
- **"Download failed"**: Network issues or GitHub API rate limits
- **"Installation failed"**: Permissions issue or app is running from an unsupported location
## Technical Details
### Supported Platforms
- **Windows**: NSIS installer (auto-update supported)
- **macOS**: DMG + ZIP (auto-update supported, requires code signing)
- **Linux**: AppImage, DEB, RPM, Pacman (auto-update supported)
### Update Files Generated
When building, electron-builder generates:
- `latest.yml` (Windows/Linux)
- `latest-mac.yml` (macOS)
- `latest-linux.yml` (Linux)
These files contain metadata about the latest release and are automatically uploaded to GitHub Releases.
## References
- [electron-updater Documentation](https://www.electron.build/auto-update)
- [electron-builder Auto Update Guide](https://www.electron.build/auto-update)

39
docs/BUILD.md Normal file
View File

@@ -0,0 +1,39 @@
# Build Instructions
## Prerequisites
Install dependencies:
```bash
npm install
```
## Building
### Build for current platform:
```bash
npm run build
```
### Build for specific platform:
**Windows:**
```bash
npm run build:win
```
**Linux:**
```bash
npm run build:linux
```
**macOS:**
```bash
npm run build:mac
```
### Build for all platforms:
```bash
npm run build:all
```
Built executables will be in the `dist/` directory

78
docs/CLEAR-UPDATE-CACHE.md Normal file
View File

@@ -0,0 +1,78 @@
# Clearing Electron-Updater Cache
To force electron-updater to re-download an update file, you need to clear the cached download.
## Quick Method (Terminal)
### macOS
```bash
# Remove the entire cache directory
rm -rf ~/Library/Caches/hytale-f2p-launcher
# Or just remove pending downloads
rm -rf ~/Library/Caches/hytale-f2p-launcher/pending
```
### Windows
```bash
# Remove the entire cache directory
rmdir /s "%LOCALAPPDATA%\hytale-f2p-launcher-updater"
# Or just remove pending downloads
rmdir /s "%LOCALAPPDATA%\hytale-f2p-launcher-updater\pending"
```
### Linux
```bash
# Remove the entire cache directory
rm -rf ~/.cache/hytale-f2p-launcher-updater
# Or just remove pending downloads
rm -rf ~/.cache/hytale-f2p-launcher-updater/pending
```
## Cache Locations
electron-updater stores downloaded updates in:
- **macOS**: `~/Library/Caches/hytale-f2p-launcher/`
- **Windows**: `%LOCALAPPDATA%\hytale-f2p-launcher-updater\`
- **Linux**: `~/.cache/hytale-f2p-launcher-updater/`
The cache typically contains:
- `pending/` - Downloaded update files waiting to be installed
- Metadata files about available updates
## After Clearing
After clearing the cache:
1. Restart the launcher
2. It will check for updates again
3. The update will be re-downloaded from scratch
## Programmatic Method
You can also clear the cache programmatically by adding this to your code:
```javascript
const { autoUpdater } = require('electron-updater');
const path = require('path');
const fs = require('fs');
const os = require('os');
function clearUpdateCache() {
const cacheDir = path.join(
os.homedir(),
process.platform === 'win32'
? 'AppData/Local/hytale-f2p-launcher-updater'
: process.platform === 'darwin'
? 'Library/Caches/hytale-f2p-launcher'
: '.cache/hytale-f2p-launcher-updater'
);
if (fs.existsSync(cacheDir)) {
fs.rmSync(cacheDir, { recursive: true, force: true });
console.log('Update cache cleared');
}
}
```

196
docs/TESTING-UPDATES.md Normal file
View File

@@ -0,0 +1,196 @@
# Testing Auto-Updates
This guide explains how to test the auto-update system during development.
## Quick Start
### Option 1: Test with GitHub Releases (Easiest)
1. **Set up dev-app-update.yml** (already done):
```yaml
provider: github
owner: amiayweb
repo: Hytale-F2P
```
2. **Lower your current version** in `package.json`:
- Change version to something lower than what's on GitHub (e.g., `2.0.1` if GitHub has `2.0.3`)
3. **Run the app in dev mode**:
```bash
npm run dev
# or
npm start
```
4. **The app will check for updates** 3 seconds after startup
- If a newer version exists on GitHub, it will detect it
- Check the console logs for update messages
### Option 2: Test with Local HTTP Server
For more control, you can set up a local server:
1. **Create a test update server**:
```bash
# Create a test directory
mkdir -p test-updates
cd test-updates
```
2. **Build a test version** with a higher version number:
```bash
# In package.json, set version to 2.0.4
npm run build
```
3. **Copy the generated files** to your test server:
- Copy `dist/latest.yml` (or `latest-mac.yml` for macOS)
- Copy the built installer/package
4. **Start a simple HTTP server**:
```bash
# Using Python
python3 -m http.server 8080
# Or using Node.js http-server
npx http-server -p 8080
```
5. **Update dev-app-update.yml** to point to local server:
```yaml
provider: generic
url: http://localhost:8080
```
6. **Run the app** and it will check your local server
## Testing Steps
### 1. Prepare Test Environment
**Current version**: `2.0.3` (in package.json)
**Test version**: `2.0.4` (on GitHub or local server)
### 2. Run the App
```bash
npm run dev
```
### 3. Watch for Update Events
The app will automatically check for updates 3 seconds after startup. Watch the console for:
```
Checking for updates...
Update available: 2.0.4
```
### 4. Check Console Logs
Look for these messages:
- `Checking for updates...` - Update check started
- `Update available: 2.0.4` - New version found
- `Download speed: ...` - Download progress
- `Update downloaded: 2.0.4` - Download complete
### 5. Test UI Integration
The app sends these events to the renderer:
- `update-checking`
- `update-available` (with version info)
- `update-download-progress` (with progress data)
- `update-downloaded` (ready to install)
You can listen to these in your frontend code to show update notifications.
## Manual Testing
### Trigger Manual Update Check
You can also trigger a manual check via IPC:
```javascript
// In renderer process
const result = await window.electronAPI.invoke('check-for-updates');
console.log(result);
```
### Install Update
After an update is downloaded:
```javascript
// In renderer process
await window.electronAPI.invoke('quit-and-install-update');
```
## Testing Scenarios
### Scenario 1: Update Available
1. Set `package.json` version to `2.0.1`
2. Ensure GitHub has version `2.0.3` or higher
3. Run app → Should detect update
### Scenario 2: Already Up to Date
1. Set `package.json` version to `2.0.3`
2. Ensure GitHub has version `2.0.3` or lower
3. Run app → Should show "no update available"
### Scenario 3: Prerelease Version
1. Set `package.json` version to `2.0.2b`
2. Ensure GitHub has version `2.0.3`
3. Run app → Should detect update (prerelease < release)
## Troubleshooting
### Update Not Detected
1. **Check dev-app-update.yml exists** in project root
2. **Verify dev mode is enabled** - Check console for "Dev update mode enabled"
3. **Check version numbers** - Remote version must be higher than current
4. **Check network** - App needs internet to reach GitHub/local server
5. **Check logs** - Look for error messages in console
### Common Errors
- **"Cannot find module 'electron-updater'"**: Run `npm install`
- **"Update check failed"**: Check network connection or GitHub API access
- **"No update available"**: Version comparison issue - check versions
### Debug Mode
Enable more verbose logging by checking the console output. The logger will show:
- Update check requests
- Version comparisons
- Download progress
- Any errors
## Testing with Real GitHub Releases
For the most realistic test:
1. **Create a test release on GitHub**:
- Build the app with version `2.0.4`
- Create a GitHub release with tag `v2.0.4`
- Upload the built files
2. **Lower your local version**:
- Set `package.json` to `2.0.3`
3. **Run the app**:
- It will check GitHub and find `2.0.4`
- Download and install the update
## Notes
- **Dev mode only works when app is NOT packaged** (`!app.isPackaged`)
- **Production builds** ignore `dev-app-update.yml` and use the built-in `app-update.yml`
- **macOS**: Code signing is required for updates to work in production
- **Windows**: NSIS installer is required for auto-updates
## Next Steps
Once testing is complete:
1. Remove or comment out `forceDevUpdateConfig` for production
2. Ensure proper code signing for macOS
3. Set up CI/CD to automatically publish releases