diff options
Diffstat (limited to 'packages/docs/content/en/manual')
| -rw-r--r-- | packages/docs/content/en/manual/features/authentication.mdx | 131 | ||||
| -rw-r--r-- | packages/docs/content/en/manual/features/index.mdx | 176 | ||||
| -rw-r--r-- | packages/docs/content/en/manual/features/java.mdx | 394 | ||||
| -rw-r--r-- | packages/docs/content/en/manual/features/meta.json | 9 | ||||
| -rw-r--r-- | packages/docs/content/en/manual/features/mod-loaders.mdx | 318 | ||||
| -rw-r--r-- | packages/docs/content/en/manual/getting-started.mdx | 164 | ||||
| -rw-r--r-- | packages/docs/content/en/manual/index.mdx | 95 | ||||
| -rw-r--r-- | packages/docs/content/en/manual/meta.json | 9 | ||||
| -rw-r--r-- | packages/docs/content/en/manual/troubleshooting.mdx | 525 |
9 files changed, 1821 insertions, 0 deletions
diff --git a/packages/docs/content/en/manual/features/authentication.mdx b/packages/docs/content/en/manual/features/authentication.mdx new file mode 100644 index 0000000..f7a1f69 --- /dev/null +++ b/packages/docs/content/en/manual/features/authentication.mdx @@ -0,0 +1,131 @@ +--- +title: Authentication +description: Microsoft OAuth and offline authentication in DropOut +--- + +# Authentication + +DropOut supports two authentication methods: Microsoft Account (for official Minecraft) and Offline Mode (for testing and offline play). + +## Microsoft Authentication + +### Overview + +DropOut uses the **Device Code Flow** for Microsoft authentication, featuring: +- No redirect URL required (no browser integration needed) +- Works on any device with a browser +- Provides simple code-based authentication +- Fully compliant with Microsoft OAuth 2.0 standards + +### Authentication Process + +The authentication chain consists of multiple steps. DropOut automatically handles these complex exchange processes, including interactions with Microsoft, Xbox Live, and Minecraft services. If you are interested in detailed API implementation, please refer to [Internal Implementation](/docs/development/implementation#1-authentication-system). + +### Token Management + +**Access Token:** +- Short-lived (typically 1 hour) +- Used for game authentication +- Automatically refreshed when expired + +**Refresh Token:** +- Long-lived (typically 90 days) +- Stored securely in `accounts.json` +- Used to obtain new access tokens + +**Auto-refresh:** +When the token expires, DropOut attempts to automatically update your login status using the refresh token when you launch the game, ensuring a seamless start. + +### Security Considerations + +- Tokens are stored in the platform-specific application data directory +- All API calls use HTTPS only +- No credentials stored (only tokens) +- User-Agent header required (bypasses MS WAF) + +### Troubleshooting Microsoft Login + +**"Device code expired"** +- The code expires after 15 minutes +- Restart the login process + +**"Authorization pending"** +- Normal during the waiting phase +- Complete authorization in your browser + +**"Invalid token"** +- The token may have expired +- Log out and log back in (use "Switch Account" to clear token) + +**"You don't own Minecraft"** +- Verify your Microsoft account owns Minecraft: Java Edition +- Check at https://www.minecraft.net/profile + +## Offline Authentication + +### Overview + +Offline mode creates a local account that does not require an internet connection or a Microsoft account. This is useful for: +- Testing and development +- Playing without internet +- LAN multiplayer +- Mod development + +### Creating an Offline Account + +1. Click "Offline Mode" on the login screen +2. Enter a username (3-16 characters) +3. Click "Create Account" + +### How It Works + +**UUID Generation:** +Offline mode uses a deterministic UUID generation algorithm based on the username (UUID v3). This means the same username will always get the same UUID in the same launcher instance, maintaining single-player save consistency. + +- Deterministic: Same username = Same UUID +- No network requests needed + +**Authentication:** +- Returns `"null"` as the access token +- Minecraft accepts empty tokens in offline mode +- Username and UUID are stored locally + +### Limitations + +- Cannot join online servers (online-mode=true) +- No custom skins support +- No capes support +- Cannot use Microsoft account features + +## Account Management + +### Switching Accounts + +Currently, DropOut supports only one active account at a time. Multi-account support is planned. + +**Steps to switch accounts:** +1. Log out of the current account +2. Log in with the new account + +### Account Storage + +Account data is stored in `accounts.json` within the application folder. This file contains encrypted tokens, expiration times, and basic profile information for logged-in accounts. + +### Deleting an Account + +Steps to delete an account: +1. Open Settings +2. Navigate to Account +3. Click "Log out" +4. Or manually delete `accounts.json` + +## API Reference + +For low-level implementation of authentication, OAuth 2.0 flow details, and related Tauri command interfaces, please refer to the development documentation: [Implementation Details: Authentication](/docs/development/implementation#1-authentication-system). + +## Best Practices + +1. **Use Microsoft Account for Official Servers**: To join official servers and use official skins, always use a Microsoft account. +2. **Keep Tokens Secure**: Do not share the `accounts.json` file or its contents with others, as it contains your login credentials. +3. **Refresh Tokens Regularly**: Long-unused offline accounts or expired Microsoft tokens can be refreshed by re-logging in or launching the game. +4. **Use Offline Mode Only for Testing**: Offline mode does not support skins and some multiplayer features. diff --git a/packages/docs/content/en/manual/features/index.mdx b/packages/docs/content/en/manual/features/index.mdx new file mode 100644 index 0000000..3a463d0 --- /dev/null +++ b/packages/docs/content/en/manual/features/index.mdx @@ -0,0 +1,176 @@ +--- +title: Features Overview +description: Comprehensive guide to all DropOut features +--- + +# Features Overview + +DropOut is packed with features designed for both casual players and power users. This guide covers all major capabilities. + +## Core Features + +<Cards> + <Card + title="Authentication" + href="authentication" + description="Microsoft OAuth and offline authentication" + /> + <Card + title="Java Management" + href="java" + description="Auto-detection and installation of Java runtimes" + /> + <Card + title="Mod Loaders" + href="mod-loaders" + description="Fabric and Forge support with easy installation" + /> + <Card + title="Instances" + href="instances" + description="Isolated game environments with independent configs" + /> + <Card + title="Downloads" + href="downloads" + description="Fast concurrent downloads with resume support" + /> + <Card + title="AI Assistant" + href="assistant" + description="Built-in AI helper for troubleshooting and guidance" + /> +</Cards> + +## Quick Feature Matrix + +| Feature | Status | Description | +|---------|--------|-------------| +| Microsoft Authentication | Complete | OAuth 2.0 with device code flow | +| Offline Authentication | Complete | Local accounts for offline play | +| Token Auto-refresh | Complete | Automatic refresh of expired tokens | +| Java Auto-detection | Complete | Scans system for Java installations | +| Java Download | Complete | Download Adoptium JDK/JRE versions | +| Fabric Support | Complete | Install and launch Fabric loader | +| Forge Support | Complete | Install and launch Forge loader | +| Instance System | Complete | Isolated game environments | +| GitHub Integration | Complete | View releases and changelogs | +| Concurrent Downloads | Complete | Multi-threaded asset downloads | +| Resume Downloads | Complete | Resume interrupted downloads | +| AI Assistant | Complete | Built-in troubleshooting helper | +| Config Editor | Complete | JSON/TOML configuration editor | +| Custom Resolution | Complete | Set game window dimensions | +| Memory Allocation | Complete | Customize JVM memory settings | +| Multi-account | In Progress | Switch between multiple accounts | +| Mods Manager | Planned | Enable/disable mods in launcher | +| Launcher Auto-update | Planned | Self-updating mechanism | +| Custom Game Directory | Planned | Choose game files location | +| Import Profiles | Planned | Import from MultiMC/Prism | + +## Performance Features + +### Concurrent Downloads +- Configurable thread count (default: 10) +- Parallel asset and library downloads +- Progress tracking per file +- ETA calculation + +### Resume Support +- Interrupted downloads auto-resume +- `.part` files track progress +- Multi-segment downloads for large files +- Metadata files for state tracking + +### Caching +- Java catalog cached for 24 hours +- Version manifests cached locally +- Asset index caching +- Library deduplication + +## User Interface Features + +### Modern Design +- Dark mode enforced for eye comfort +- Particle background effects +- Clean, distraction-free layout +- Responsive design + +### Real-time Feedback +- Live download progress +- Game console output +- Log streaming +- Toast notifications + +### Settings Management +- Memory allocation slider +- Resolution customization +- Java path selection +- Thread count configuration +- Custom JVM arguments + +## Advanced Features + +### Version Inheritance +Modded versions (Fabric/Forge) automatically inherit from parent vanilla versions: +- Libraries merged from parent + mod loader +- Arguments combined and deduplicated +- Assets inherited from vanilla version + +### Native Library Extraction +- Platform-specific native extraction +- Automatic cleanup +- Proper library path configuration + +### Rules Engine +- OS-specific library filtering +- Feature flag support +- Architecture detection + +### Download Queue Persistence +- Save incomplete downloads +- Resume after launcher restart +- Queue priority management + +## Developer Features + +### Config Editor +Built-in JSON/TOML editor with: +- Syntax highlighting +- Validation +- Quick access to all configs + +### Log Access +- Real-time game logs +- Launcher debug logs +- Copy/export functionality + +### AI Assistant +- Troubleshooting guidance +- Error analysis +- Configuration help +- Documentation search + +## Coming Soon + +### Multi-account Management +- Switch between accounts easily +- Account profiles +- Quick switching + +### Mods Manager +- Browse and install mods +- Enable/disable mods +- Mod compatibility checking +- Version management + +### Profile Import +- Import from MultiMC +- Import from Prism Launcher +- Import from other launchers +- Preserve settings and saves + +### Launcher Auto-update +- Background update checks +- One-click updates +- Version history +- Rollback support diff --git a/packages/docs/content/en/manual/features/java.mdx b/packages/docs/content/en/manual/features/java.mdx new file mode 100644 index 0000000..21b95a9 --- /dev/null +++ b/packages/docs/content/en/manual/features/java.mdx @@ -0,0 +1,394 @@ +--- +title: Java Management +description: Automatic Java detection, download, and installation +--- + +# Java Management + +DropOut provides comprehensive Java management, automatically detecting installed versions and downloading new ones as needed. + +## Auto-detection + +### System Scan + +DropOut scans multiple locations for Java installations: + +**Linux:** +- `/usr/lib/jvm/` +- `/usr/java/` +- `$JAVA_HOME` +- `PATH` environment variable + +**macOS:** +- `/Library/Java/JavaVirtualMachines/` +- `/System/Library/Java/JavaVirtualMachines/` +- `$JAVA_HOME` +- `PATH` environment variable + +**Windows:** +- `C:\Program Files\Java\` +- `C:\Program Files (x86)\Java\` +- `%JAVA_HOME%` +- `PATH` environment variable +- Windows Registry + +### Version Detection + +For each Java installation found, DropOut: +1. Runs `java -version` to get version info +2. Parses major version (8, 11, 17, 21, etc.) +3. Detects architecture (x64, ARM64) +4. Identifies vendor (Oracle, Adoptium, etc.) + +### Results + +All detected Java installations appear in Settings → Java: +- Version number +- Installation path +- Architecture +- Current selection status + +## Java Download + +### Adoptium Integration + +DropOut integrates with the Eclipse Adoptium API to download high-quality, free JDK/JRE builds. + +**Supported Versions:** +- Java 8 (LTS) +- Java 11 (LTS) +- Java 17 (LTS) +- Java 21 (LTS) +- Java 23+ (Latest) + +**Features:** +- Automatic platform detection +- Architecture-specific builds +- JDK or JRE selection +- Checksum verification + +### Download Process + +1. Navigate to Settings → Java +2. Click "Download Java" +3. Select version (e.g., Java 17) +4. Choose JDK or JRE +5. Click Download +6. Wait for download and extraction + +**Progress Tracking:** +- Real-time download speed +- ETA calculation +- Extraction progress +- Installation confirmation + +### Catalog Management + +The Java catalog is cached for 24 hours to improve performance: + +```rust +// Catalog structure +{ + "versions": [ + { + "version": "17.0.9+9", + "major": 17, + "url": "https://api.adoptium.net/...", + "sha256": "...", + "size": 123456789 + } + ], + "last_updated": 1234567890 +} +``` + +**Refresh:** +- Automatic after 24 hours +- Manual refresh in settings +- Forced refresh on download failure + +## Installation + +### Download Directory + +Downloaded Java runtimes are installed to: + +``` +~/.local/share/com.dropout.launcher/java/ (Linux) +~/Library/Application Support/com.dropout.launcher/java/ (macOS) +%APPDATA%/com.dropout.launcher/java/ (Windows) +``` + +### Directory Structure + +``` +java/ +├── jdk-17.0.9+9/ +│ ├── bin/ +│ │ └── java (or java.exe) +│ └── lib/ +├── jdk-21.0.1+12/ +│ ├── bin/ +│ └── lib/ +└── download_queue.json +``` + +### Extraction + +1. Download to `.part` file +2. Verify checksum +3. Extract archive: + - `.tar.gz` on Linux/macOS + - `.zip` on Windows +4. Move to `java/<version>/` directory +5. Set executable permissions (Unix) + +## Configuration + +### Memory Allocation + +Configure JVM memory in Settings: + +**Minimum Memory:** +- Default: 1024 MB +- Recommended: 2048 MB for vanilla +- Recommended: 4096+ MB for modded + +**Maximum Memory:** +- Default: 4096 MB +- Adjust based on your system RAM +- Leave 4GB for OS and other apps + +**Format:** +```bash +-Xms1024M -Xmx4096M +``` + +### Custom JVM Arguments + +Add custom JVM arguments for advanced configuration: + +**Common Arguments:** +```bash +# Garbage collection +-XX:+UseG1GC +-XX:+UnlockExperimentalVMOptions + +# Performance +-XX:G1NewSizePercent=20 +-XX:G1ReservePercent=20 +-XX:MaxGCPauseMillis=50 + +# Memory +-XX:G1HeapRegionSize=32M +``` + +### Java Path Selection + +**Auto-select:** +- DropOut recommends the best Java version for each Minecraft version +- Java 8 for Minecraft 1.12.2 and older +- Java 17 for Minecraft 1.18-1.20.4 +- Java 21 for Minecraft 1.20.5+ + +**Manual selection:** +1. Go to Settings → Java +2. Choose from detected installations +3. Or specify custom path + +## Version Recommendations + +### Minecraft Version → Java Version + +| Minecraft Version | Recommended Java | Minimum Java | +|-------------------|------------------|--------------| +| 1.7.10 and older | Java 8 | Java 8 | +| 1.8 - 1.12.2 | Java 8 | Java 8 | +| 1.13 - 1.16.5 | Java 8 or 11 | Java 8 | +| 1.17 - 1.17.1 | Java 16 | Java 16 | +| 1.18 - 1.20.4 | Java 17 | Java 17 | +| 1.20.5+ | Java 21 | Java 21 | + +### Modded Minecraft + +**Fabric:** +- Usually matches vanilla requirements +- Some mods may require newer Java + +**Forge:** +- May require specific Java versions +- Check mod loader documentation +- Often requires exact version match + +## Troubleshooting + +### Java Not Detected + +**Issue:** Installed Java not showing up + +**Solutions:** +1. Verify Java is in standard location +2. Check `JAVA_HOME` environment variable +3. Add Java `bin` directory to `PATH` +4. Restart DropOut +5. Manual path selection + +### Download Fails + +**Issue:** Java download doesn't complete + +**Solutions:** +1. Check internet connection +2. Verify disk space +3. Try different version +4. Clear download queue +5. Manual download from Adoptium + +### Wrong Java Version + +**Issue:** Game crashes due to Java version + +**Solutions:** +1. Check Minecraft version requirements +2. Download correct Java version +3. Select appropriate Java in settings +4. Verify Java path is correct + +### OutOfMemoryError + +**Issue:** Game crashes with memory error + +**Solutions:** +1. Increase maximum memory allocation +2. Close other applications +3. Upgrade system RAM +4. Use 64-bit Java +5. Optimize JVM arguments + +### Performance Issues + +**Issue:** Low FPS or stuttering + +**Solutions:** +1. Adjust memory allocation (not too high!) +2. Enable G1GC garbage collector +3. Add performance JVM arguments +4. Use newer Java version if compatible +5. Allocate 4-8GB for modpacks + +## API Reference + +### Tauri Commands + +**Detect Java Installations:** +```typescript +const javas = await invoke('detect_java_installations'); +// Returns: Array<{ path: string, version: string, major: number }> +``` + +**Get Java Catalog:** +```typescript +const catalog = await invoke('get_java_catalog'); +// Returns: { versions: Array<JavaVersion>, last_updated: number } +``` + +**Download Java:** +```typescript +await invoke('download_java', { + version: '17.0.9+9', + variant: 'jdk' // or 'jre' +}); +``` + +**Cancel Java Download:** +```typescript +await invoke('cancel_java_download'); +``` + +**Set Java Path:** +```typescript +await invoke('set_java_path', { path: '/path/to/java' }); +``` + +### Events + +**Download Progress:** +```typescript +listen('java-download-progress', (event) => { + const { percent, speed, eta } = event.payload; +}); +``` + +**Download Complete:** +```typescript +listen('java-download-complete', (event) => { + const { path, version } = event.payload; +}); +``` + +## Best Practices + +### For Players + +1. **Use Adoptium builds** - Free, high-quality, maintained +2. **Match Java to Minecraft** - Check version requirements +3. **Don't over-allocate memory** - Leave RAM for OS +4. **Keep Java updated** - Security and performance +5. **Use 64-bit Java** - Required for large memory + +### For Developers + +1. **Test multiple Java versions** - Ensure compatibility +2. **Document Java requirements** - Help users +3. **Handle missing Java** - Graceful fallbacks +4. **Validate Java path** - Before launching +5. **Provide clear errors** - When Java is wrong + +## Advanced Topics + +### Custom Java Installation + +To use a custom Java installation: + +1. Install Java manually +2. Note the installation path +3. In DropOut Settings → Java +4. Click "Custom Path" +5. Browse to Java executable +6. Verify version is correct + +### Java for Servers + +When running a Minecraft server: + +```bash +# Recommended server JVM arguments +-Xms4G -Xmx4G \ +-XX:+UseG1GC \ +-XX:+ParallelRefProcEnabled \ +-XX:MaxGCPauseMillis=200 \ +-XX:+UnlockExperimentalVMOptions \ +-XX:+DisableExplicitGC \ +-XX:G1NewSizePercent=30 \ +-XX:G1MaxNewSizePercent=40 \ +-XX:G1HeapRegionSize=8M \ +-XX:G1ReservePercent=20 \ +-XX:G1HeapWastePercent=5 \ +-XX:G1MixedGCCountTarget=4 \ +-XX:InitiatingHeapOccupancyPercent=15 \ +-XX:G1MixedGCLiveThresholdPercent=90 \ +-XX:G1RSetUpdatingPauseTimePercent=5 \ +-XX:SurvivorRatio=32 \ +-XX:+PerfDisableSharedMem \ +-XX:MaxTenuringThreshold=1 +``` + +### GraalVM + +GraalVM is supported for advanced users: + +1. Download GraalVM from graalvm.org +2. Install manually +3. Add to DropOut as custom Java +4. May improve performance +5. Test thoroughly before use diff --git a/packages/docs/content/en/manual/features/meta.json b/packages/docs/content/en/manual/features/meta.json new file mode 100644 index 0000000..4725321 --- /dev/null +++ b/packages/docs/content/en/manual/features/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Features", + "pages": [ + "index", + "authentication", + "java", + "mod-loaders" + ] +} diff --git a/packages/docs/content/en/manual/features/mod-loaders.mdx b/packages/docs/content/en/manual/features/mod-loaders.mdx new file mode 100644 index 0000000..8fdf019 --- /dev/null +++ b/packages/docs/content/en/manual/features/mod-loaders.mdx @@ -0,0 +1,318 @@ +--- +title: Mod Loaders +description: Fabric and Forge installation and management +--- + +# Mod Loaders + +DropOut supports the two most popular Minecraft mod loaders: Fabric and Forge. Both can be easily installed and managed directly from the launcher. + +## Fabric Support + +### Overview + +Fabric is a lightweight, modular modding toolchain focused on: +- Fast updates to new Minecraft versions +- Clean, minimal API +- Strong developer community +- Excellent performance + +### Installation + +1. Navigate to **Versions** tab +2. Click **"Install Fabric"** +3. Select Minecraft version +4. Choose Fabric loader version +5. Click **"Install"** +6. Wait for installation to complete + +### How It Works + +DropOut integrates with the Fabric Meta API to automatically fetch compatible loader versions. In the background, it generates the version JSON, handles library dependencies, and utilizes the inheritance system to ensure perfect compatibility with vanilla Minecraft. Detailed JSON structure can be found in [Technical Details](/docs/development/implementation#fabric-integration). + +### Fabric Versions + +**Loader Versions:** +- Latest stable (recommended) +- Specific versions for compatibility +- Beta/snapshot versions + +**Game Versions:** +- All Minecraft versions from 1.14+ +- Snapshots supported +- Combat Test versions + +### Library Management + +Fabric's dependencies are typically hosted on its official Maven repository. DropOut automatically resolves and downloads all required library files. + +### Fabric API + +Fabric Loader ≠ Fabric API: +- **Fabric Loader**: Mod loader (installed by DropOut) +- **Fabric API**: Library mod (download separately) + +Many mods require Fabric API: +1. Download from [Modrinth](https://modrinth.com/mod/fabric-api) or [CurseForge](https://www.curseforge.com/minecraft/mc-mods/fabric-api) +2. Place in instance's `mods/` folder + +## Forge Support + +### Overview + +Forge is the original and most popular Minecraft mod loader: +- Extensive mod ecosystem +- Mature API +- Wide version support +- Large community + +### Installation + +1. Navigate to **Versions** tab +2. Click **"Install Forge"** +3. Select Minecraft version +4. Choose Forge version +5. Click **"Install"** +6. Wait for installer to run +7. Installation complete + +### How It Works + +**Forge Installer:** +```rust +// Download Forge installer +let installer_url = format!( + "https://maven.minecraftforge.net/net/minecraftforge/forge/{}/forge-{}-installer.jar", + full_version, full_version +); + +// Run installer +java -jar forge-installer.jar --installClient +``` + +**Profile Parsing:** +1. Forge installer creates version JSON +2. DropOut parses install profile +3. Extracts library dependencies +4. Processes processors (if any) +5. Generates launcher profile + +**Version Format:** +```json +{ + "id": "1.20.4-forge-49.0.26", + "inheritsFrom": "1.20.4", + "mainClass": "cpw.mods.bootstraplauncher.BootstrapLauncher", + "libraries": [...] +} +``` + +### Forge Versions + +**Release Types:** +- **Latest**: Most recent stable +- **Recommended**: Most stable for production +- **Specific**: Version-locked for compatibility + +**Minecraft Version Support:** +- Legacy versions (1.6.4+) +- Modern versions (1.13+) +- Latest versions (1.20+) + +### Library Management + +Forge's runtime depends on a significant number of library files, including its underlying `fmlloader` and bytecode manipulation libraries. DropOut automatically resolves the complex dependency tree and retrieves these files from both the official Forge Maven repository and Minecraft's official libraries. + +For detailed analysis logic of Forge libraries, refer to [Implementation Details: Forge Core Library Resolution](../development/implementation.mdx#core-library-resolution). + +### Forge Processors + +Some Forge versions run "processors" during installation: +- Bytecode manipulation +- Library patching +- Mapping generation + +DropOut handles these automatically. + +## Version Inheritance + +Both Fabric and Forge utilize Minecraft's version inheritance mechanism. In this model, the mod loader's version JSON only contains incremental changes relative to the vanilla version, addressed recursively upwards via the `inheritsFrom` field. + +DropOut's launch engine automatically handles this complex merging of libraries, arguments, and assets. Detailed merging logic and code implementation can be viewed in [Implementation Details: Version Merging](../development/implementation.mdx#version-merging-mechanism). + +## Comparison + +| Feature | Fabric | Forge | +|---------|--------|-------| +| **Performance** | Excellent | Good | +| **Update Speed** | Very Fast | Moderate | +| **Mod Selection** | Growing | Extensive | +| **API Simplicity** | Simple | Complex | +| **Version Support** | 1.14+ | 1.6.4+ | +| **Developer Friendly** | Very | Moderate | +| **Stability** | Excellent | Excellent | + +## Installing Mods + +### Fabric Mods + +1. Create/select instance +2. Ensure Fabric is installed +3. Download mods from: + - [Modrinth](https://modrinth.com/) + - [CurseForge](https://www.curseforge.com/) + - [GitHub Releases](https://github.com/) +4. Place `.jar` files in `instances/<name>/mods/` +5. Launch game + +**Compatibility:** +- Check Minecraft version +- Check Fabric Loader version +- Check for Fabric API requirement +- Read mod dependencies + +### Forge Mods + +1. Create/select instance +2. Ensure Forge is installed +3. Download mods from: + - [CurseForge](https://www.curseforge.com/) + - [Modrinth](https://modrinth.com/) +4. Place `.jar` files in `instances/<name>/mods/` +5. Launch game + +**Compatibility:** +- Check Minecraft version exactly +- Check Forge version range +- Read mod dependencies +- Check for conflicts + +## Troubleshooting + +### Fabric Issues + +**"Fabric Loader not found"** +- Reinstall Fabric +- Check version JSON exists +- Verify libraries downloaded + +**"Mixin apply failed"** +- Mod incompatibility +- Remove conflicting mods +- Update Fabric Loader + +**"Fabric API required"** +- Download Fabric API +- Match Minecraft version +- Place in mods folder + +### Forge Issues + +**"Forge installer failed"** +- Verify Java installation +- Check disk space +- Try older Forge version +- Check logs for details + +**"Missing dependencies"** +- Install required mods +- Check mod version compatibility +- Read error message carefully + +**"Class not found"** +- Forge version mismatch +- Reinstall Forge +- Verify libraries downloaded + +### General Mod Issues + +**Crash on Launch:** +1. Check crash report +2. Identify problematic mod +3. Remove or update mod +4. Test with minimal mods +5. Add mods back incrementally + +**Performance Problems:** +1. Too many mods installed +2. Increase memory allocation +3. Install performance mods: + - Fabric: Sodium, Lithium + - Forge: OptiFine, Magnesium +4. Remove resource-heavy mods + +## API Reference + +### Tauri Commands + +**Install Fabric:** +```typescript +await invoke('install_fabric', { + minecraftVersion: '1.20.4', + loaderVersion: '0.15.0' +}); +``` + +**Install Forge:** +```typescript +await invoke('install_forge', { + minecraftVersion: '1.20.4', + forgeVersion: '49.0.26' +}); +``` + +**List Fabric Versions:** +```typescript +const versions = await invoke('get_fabric_versions', { + minecraftVersion: '1.20.4' +}); +``` + +**List Forge Versions:** +```typescript +const versions = await invoke('get_forge_versions', { + minecraftVersion: '1.20.4' +}); +``` + +### Events + +**Installation Progress:** +```typescript +listen('mod-loader-progress', (event) => { + const { stage, percent } = event.payload; + // Stages: "downloading", "installing", "processing", "complete" +}); +``` + +## Best Practices + +### For Players + +1. **Choose one mod loader** per instance +2. **Match versions exactly** - Minecraft and loader +3. **Read mod requirements** before installing +4. **Start small** - Add mods incrementally +5. **Backup worlds** before adding mods +6. **Check compatibility** lists +7. **Update cautiously** - Test in separate instance + +### For Modpack Creators + +1. **Document versions** - MC, loader, all mods +2. **Test thoroughly** - All features +3. **List dependencies** - Including API +4. **Provide changelog** - For updates +5. **Version lock** - For stability +6. **Include configs** - Pre-configured +7. **Test updates** - Before release + +## Future Features + +- **Mod browser** - Install mods from launcher +- **Automatic updates** - Keep mods current +- **Dependency resolution** - Auto-install requirements +- **Conflict detection** - Warn about incompatibilities +- **Profile export** - Share modpack configurations +- **CurseForge integration** - Direct modpack import +- **Modrinth integration** - Mod search and install diff --git a/packages/docs/content/en/manual/getting-started.mdx b/packages/docs/content/en/manual/getting-started.mdx new file mode 100644 index 0000000..c172289 --- /dev/null +++ b/packages/docs/content/en/manual/getting-started.mdx @@ -0,0 +1,164 @@ +--- +title: Getting Started +description: Quick start guide to using DropOut Minecraft Launcher +--- + +# Getting Started + +DropOut is a modern, reproducible, and developer-grade Minecraft launcher built with Tauri v2 and Rust. This guide will help you get started with installing and using DropOut. + +## Installation + +### Download Pre-built Binaries + +Download the latest release for your platform from the [Releases](https://github.com/HsiangNianian/DropOut/releases) page. + +| Platform | Files | +| -------------- | ------------------- | +| Linux x86_64 | `.deb`, `.AppImage` | +| Linux ARM64 | `.deb`, `.AppImage` | +| macOS ARM64 | `.dmg` | +| Windows x86_64 | `.msi`, `.exe` | +| Windows ARM64 | `.msi`, `.exe` | + +### Linux Installation + +#### Using .deb Package + +```bash +sudo dpkg -i dropout_*.deb +# Fix dependencies if needed +sudo apt-get install -f +``` + +#### Using AppImage + +```bash +chmod +x dropout_*.AppImage +./dropout_*.AppImage +``` + +### macOS Installation + +1. Open the downloaded `.dmg` file +2. Drag DropOut to your Applications folder +3. If you see a security warning, go to System Preferences → Security & Privacy and allow the app + +### Windows Installation + +#### Using .msi Installer + +1. Double-click the `.msi` file +2. Follow the installation wizard +3. Launch DropOut from the Start Menu + +#### Using .exe Portable + +1. Double-click the `.exe` file +2. DropOut will run directly without installation + +## First Launch + +When you first launch DropOut, you'll need to: + +1. **Choose Authentication Method** + - **Microsoft Account**: Recommended for official Minecraft + - **Offline Mode**: For testing or offline play + +2. **Configure Java Runtime** + - DropOut will automatically detect installed Java versions + - You can download Java directly from the launcher if needed + +3. **Select Minecraft Version** + - Browse available Minecraft versions + - Choose vanilla or modded versions (Fabric/Forge) + +## Quick Start Tutorial + +### 1. Login + +<Cards> + <Card title="Microsoft Account" description="Login with your official Minecraft account" /> + <Card title="Offline Mode" description="Create a local profile for offline play" /> +</Cards> + +**Microsoft Login:** + +1. Click "Login with Microsoft" +2. A device code will be displayed +3. Visit the URL shown and enter the code +4. Authorize the application +5. Return to DropOut - you'll be logged in automatically + +**Offline Login:** + +1. Click "Offline Mode" +2. Enter a username +3. Click "Create Account" + +### 2. Install Minecraft + +1. Navigate to the **Versions** tab +2. Browse available Minecraft versions +3. Click on a version to install it +4. Wait for the download to complete + +### 3. Launch the Game + +1. Go to the **Home** tab +2. Select your desired version from the dropdown +3. Adjust settings if needed: + - Memory allocation (RAM) + - Window resolution + - Java path +4. Click **"Launch Game"** +5. Monitor the launch process in the console + +## Next Steps + +<Cards> + <Card + title="Features" + href="/docs/manual/features" + description="Learn about all the features DropOut offers" + /> + <Card + title="Instances" + href="/docs/manual/features/instances" + description="Create isolated game environments" + /> + <Card + title="Mod Loaders" + href="/docs/manual/features/mod-loaders" + description="Install and manage Fabric and Forge" + /> + <Card + title="Troubleshooting" + href="/docs/troubleshooting" + description="Common issues and solutions" + /> +</Cards> + +## System Requirements + +### Minimum Requirements + +- **OS**: Windows 10+, macOS 11+, or Linux (Debian-based) +- **RAM**: 4GB (8GB recommended for modded Minecraft) +- **Storage**: 2GB for launcher + game files +- **Java**: Auto-installed by DropOut if not found + +### Recommended Requirements + +- **OS**: Latest stable version of your OS +- **RAM**: 16GB for optimal performance with mods +- **Storage**: 10GB+ for multiple versions and mods +- **Java**: Java 17 or 21 (managed by DropOut) + +## Getting Help + +If you encounter issues: + +- Check the [Troubleshooting Guide](/docs/troubleshooting) +- Report bugs on [GitHub Issues](https://github.com/HsiangNianian/DropOut/issues) +- Join our community discussions diff --git a/packages/docs/content/en/manual/index.mdx b/packages/docs/content/en/manual/index.mdx new file mode 100644 index 0000000..9dee19f --- /dev/null +++ b/packages/docs/content/en/manual/index.mdx @@ -0,0 +1,95 @@ +--- +title: Welcome to DropOut +description: Modern, reproducible, and developer-grade Minecraft launcher +--- + +# Welcome to DropOut + +DropOut is a modern Minecraft launcher built with Tauri v2 and Rust, designed for players who value control, transparency, and long-term stability. + +<div style={{ textAlign: 'center', margin: '2rem 0' }}> + <img src="/image.png" alt="DropOut Launcher" style={{ maxWidth: '700px', borderRadius: '8px' }} /> +</div> + +## Why DropOut? + +Most Minecraft launchers focus on getting you into the game. DropOut focuses on keeping your game **stable**, **debuggable**, and **reproducible**. + +- Your instance worked yesterday but broke today? → **DropOut makes it traceable.** +- Sharing a modpack means zipping gigabytes? → **DropOut shares exact dependency manifests.** +- Java, loader, mods, configs drift out of sync? → **DropOut locks them together.** + +This launcher is built for players who value control, transparency, and long-term stability. + +## Quick Links + +<Cards> + <Card + title="Getting Started" + href="getting-started" + description="Install and set up DropOut in minutes" + /> + <Card + title="Features" + href="features" + description="Explore all the capabilities of DropOut" + /> + <Card + title="Architecture" + href="architecture" + description="Learn about the technical design" + /> + <Card + title="Development" + href="development" + description="Build and contribute to DropOut" + /> +</Cards> + +## Key Features + +### High Performance +Built with Rust and Tauri for minimal resource usage and fast startup times. + +### Modern UI +Clean, distraction-free interface with Svelte 5, Tailwind CSS 4, and particle effects. + +### Secure Authentication +Microsoft OAuth 2.0 with device code flow and offline authentication support. + +### Mod Loader Support +Built-in installation for Fabric and Forge with automatic version management. + +### Java Management +Automatic detection of installed Java versions and integrated downloader for Adoptium JDK/JRE. + +### Instance System +Isolated game environments with independent configurations, mods, and saves. + +### AI Assistant +Built-in AI helper for troubleshooting, configuration, and guidance. + +### Fast Downloads +Concurrent asset and library downloads with resume support and progress tracking. + +## Technology Stack + +- **Backend**: Rust with Tauri v2 +- **Frontend**: Svelte 5 with runes +- **Styling**: Tailwind CSS 4 +- **Build Tool**: Vite with Rolldown +- **Documentation**: Fumadocs with React Router + +## Community + +- **GitHub**: [HydroRoll-Team/DropOut](https://github.com/HydroRoll-Team/DropOut) +- **Issues**: [Report bugs](https://github.com/HydroRoll-Team/DropOut/issues) +- **Roadmap**: [View development roadmap](https://roadmap.sh/r/minecraft-launcher-dev) + +## License + +DropOut is open source software licensed under the MIT License. + +--- + +Ready to get started? Check out the [Getting Started Guide](getting-started)! diff --git a/packages/docs/content/en/manual/meta.json b/packages/docs/content/en/manual/meta.json new file mode 100644 index 0000000..38506c1 --- /dev/null +++ b/packages/docs/content/en/manual/meta.json @@ -0,0 +1,9 @@ +{ + "title": "User Manual", + "pages": [ + "index", + "getting-started", + "features", + "troubleshooting" + ] +} diff --git a/packages/docs/content/en/manual/troubleshooting.mdx b/packages/docs/content/en/manual/troubleshooting.mdx new file mode 100644 index 0000000..6d97819 --- /dev/null +++ b/packages/docs/content/en/manual/troubleshooting.mdx @@ -0,0 +1,525 @@ +--- +title: Troubleshooting +description: Common issues and solutions for DropOut launcher +--- + +# Troubleshooting + +This guide covers common issues and their solutions. If you don't find your issue here, please [open an issue](https://github.com/HydroRoll-Team/DropOut/issues) on GitHub. + +## Installation Issues + +### Linux: Missing Dependencies + +**Issue:** Error about missing libraries during installation + +**Solution:** +```bash +# Ubuntu/Debian +sudo apt update +sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 + +# Fedora +sudo dnf install webkit2gtk4.1 gtk3 + +# Arch +sudo pacman -S webkit2gtk gtk3 +``` + +### macOS: "App is damaged" + +**Issue:** macOS says DropOut is damaged and can't be opened + +**Solution:** +1. Open Terminal +2. Run: `xattr -cr /Applications/DropOut.app` +3. Try opening again +4. Or: System Preferences → Security → Allow anyway + +### Windows: SmartScreen Warning + +**Issue:** Windows SmartScreen blocks the installer + +**Solution:** +1. Click "More info" +2. Click "Run anyway" +3. This is normal for new apps without extended validation certificates + +## Authentication Issues + +### Microsoft Login Fails + +**Issue:** Can't complete Microsoft login + +**Possible causes and solutions:** + +**1. Device code expired:** +- Codes expire after 15 minutes +- Start the login process again +- Complete authorization faster + +**2. Network issues:** +- Check internet connection +- Disable VPN temporarily +- Check firewall settings +- Try different network + +**3. Microsoft account issues:** +- Verify account owns Minecraft Java Edition +- Check at https://www.minecraft.net/profile +- Ensure account is not suspended + +**4. Browser problems:** +- Try different browser +- Clear browser cache +- Disable ad blockers +- Use incognito/private mode + +### Token Refresh Fails + +**Issue:** Token refresh fails, must re-login frequently + +**Solution:** +1. Log out completely +2. Delete `accounts.json` from app data directory +3. Log in again +4. If persists, check Microsoft account status + +### Offline Login Not Working + +**Issue:** Can't create offline account + +**Solution:** +- Username must be 3-16 characters +- Use only letters, numbers, underscore +- No special characters +- No spaces + +## Game Launch Issues + +### Java Not Found + +**Issue:** "No Java installation found" + +**Solutions:** + +**1. Auto-detect existing Java:** +- Settings → Java → Detect Installations +- If found, select it +- If not found, proceed to step 2 + +**2. Download Java via DropOut:** +- Settings → Java → Download Java +- Select appropriate version: + - Java 8 for Minecraft 1.12.2 and older + - Java 17 for Minecraft 1.18-1.20.4 + - Java 21 for Minecraft 1.20.5+ + +**3. Manual Java installation:** +- Download from [Adoptium](https://adoptium.net/) +- Install to system +- Restart DropOut +- Detect again + +### Wrong Java Version + +**Issue:** Game crashes with "Unsupported class file version" + +**Solution:** +Match Java version to Minecraft version: + +| Minecraft Version | Java Version | +|-------------------|--------------| +| 1.7.10 and older | Java 8 | +| 1.8 - 1.12.2 | Java 8 | +| 1.13 - 1.16.5 | Java 8 or 11 | +| 1.17 - 1.17.1 | Java 16 | +| 1.18 - 1.20.4 | Java 17 | +| 1.20.5+ | Java 21 | + +### OutOfMemoryError + +**Issue:** Game crashes with `java.lang.OutOfMemoryError` + +**Solutions:** + +**1. Increase memory allocation:** +- Settings → Memory +- Increase Maximum Memory: + - Vanilla: 4GB minimum + - Light mods: 6GB + - Heavy modpacks: 8-12GB +- Don't exceed 80% of system RAM + +**2. Use 64-bit Java:** +- Check current Java architecture +- Download 64-bit Java if needed +- 32-bit Java limited to ~2GB + +**3. Reduce render distance:** +- In-game Video Settings +- Lower render distance to 8-12 chunks + +**4. Optimize JVM arguments:** +```bash +-Xms4G -Xmx8G -XX:+UseG1GC -XX:+UnlockExperimentalVMOptions +``` + +### Game Won't Start + +**Issue:** Game doesn't launch, no error message + +**Check:** + +**1. Log output:** +- Check game console in DropOut +- Look for error messages +- Common issues: + - Missing files + - Corrupted downloads + - Mod conflicts + +**2. Verify files:** +- Delete version folder +- Re-download version +- Try vanilla first before modded + +**3. Check permissions:** +- Ensure DropOut can write to game directory +- Check folder permissions +- On Linux: ensure the launcher directory is only accessible by your user, e.g. `chmod 700 ~/.local/share/com.dropout.launcher` + +## Download Issues + +### Downloads Fail + +**Issue:** Asset or library downloads fail + +**Solutions:** + +**1. Network issues:** +- Check internet connection +- Disable VPN +- Try different network +- Check firewall/antivirus + +**2. Resume downloads:** +- DropOut auto-resumes interrupted downloads +- Close and reopen DropOut +- Downloads should continue + +**3. Clear download cache:** +- Delete `.part` files in libraries/assets +- Restart download + +**4. Manually download:** +- Check logs for failing URL +- Download file manually +- Place in correct location + +### Slow Downloads + +**Issue:** Downloads are very slow + +**Solutions:** + +**1. Adjust thread count:** +- Settings → Downloads +- Try different thread counts: + - Too low: slow overall + - Too high: connection throttling + - Recommended: 5-10 threads + +**2. Network optimization:** +- Close bandwidth-heavy apps +- Use wired connection if possible +- Check for ISP throttling + +**3. Alternative CDN:** +- Mojang mirrors may be slow +- Try at different time of day + +## Mod Loader Issues + +### Fabric Installation Fails + +**Issue:** Can't install Fabric loader + +**Solutions:** + +**1. Check Minecraft version:** +- Fabric supports 1.14+ +- Older versions not supported +- Try newer Minecraft version + +**2. Network issues:** +- Check internet connection +- Fabric Meta API may be down +- Try again later + +**3. Manual installation:** +- Download Fabric from [fabricmc.net](https://fabricmc.net/) +- Use official installer +- Import profile to DropOut + +### Forge Installation Fails + +**Issue:** Forge installer fails or hangs + +**Solutions:** + +**1. Java version:** +- Ensure correct Java version +- Forge 1.17+ requires Java 16+ +- Older Forge may need Java 8 + +**2. Installer timeout:** +- Forge installer can be slow +- Wait up to 10 minutes +- Check logs for progress + +**3. Disk space:** +- Ensure sufficient free space +- Forge needs ~1GB temporarily +- Check `/tmp` on Linux + +**4. Manual installation:** +- Download Forge installer from [minecraftforge.net](https://files.minecraftforge.net/) +- Run installer manually +- Select install client +- Import profile + +### Mod Crashes + +**Issue:** Game crashes with mods installed + +**Solutions:** + +**1. Check compatibility:** +- Verify mod is for correct Minecraft version +- Check mod loader version requirements +- Read mod description for dependencies + +**2. Install dependencies:** +- Fabric mods often need Fabric API +- Some mods require libraries +- Check crash log for "missing" errors + +**3. Remove conflicting mods:** +- Disable mods one by one +- Identify problematic mod +- Check for known conflicts +- Update or replace mod + +**4. Update mods:** +- Use latest mod versions +- Check mod update notes +- Some updates fix crashes + +## Performance Issues + +### Low FPS + +**Issue:** Game runs slowly or stutters + +**Solutions:** + +**1. Allocate more memory:** +- Increase max memory to 6-8GB +- Don't over-allocate (causes GC pauses) + +**2. Install performance mods:** +- **Fabric**: Sodium, Lithium, Phosphor +- **Forge**: OptiFine, Magnesium, Rubidium + +**3. Optimize settings:** +- Lower render distance +- Disable fancy graphics +- Turn off particles +- Disable VSync if fps < 60 + +**4. Update graphics drivers:** +- Download latest from manufacturer +- NVIDIA: GeForce Experience +- AMD: Adrenalin +- Intel: Graphics Command Center + +**5. Close background apps:** +- Free up system resources +- Disable overlays (Discord, etc.) +- Check Task Manager for CPU/RAM hogs + +### Launcher Slow to Start + +**Issue:** DropOut takes long time to launch + +**Solutions:** + +**1. Check system resources:** +- Close unnecessary programs +- Ensure sufficient RAM available +- Check CPU usage + +**2. Antivirus interference:** +- Add DropOut to exceptions +- Temporarily disable to test +- Some AVs slow down significantly + +**3. Corrupted data:** +- Delete `cache` folder in app data +- Restart DropOut +- Will rebuild cache + +## UI Issues + +### Window Won't Open + +**Issue:** DropOut window doesn't appear + +**Solutions:** + +**1. Check if running:** +```bash +# Linux/macOS +ps aux | grep dropout + +# Windows +tasklist | findstr dropout +``` + +**2. Kill and restart:** +```bash +# Linux/macOS +pkill dropout + +# Windows +taskkill /F /IM dropout.exe +``` + +**3. Reset window position:** +- Delete window state config +- Restart DropOut + +### Graphics Glitches + +**Issue:** UI looks wrong or has visual artifacts + +**Solutions:** + +**1. Update graphics drivers:** +- Install latest drivers +- Restart system + +**2. Disable hardware acceleration:** +- Check if option exists in settings +- May reduce performance but fix glitches + +**3. Try different monitor:** +- Multi-monitor setups can cause issues +- Try on different display + +## File System Issues + +### Can't Access Game Directory + +**Issue:** Errors accessing game files + +**Solutions:** + +**1. Check permissions:** +```bash +# Linux (set secure owner-only permissions) +sudo chown -R "$USER":"$USER" ~/.local/share/com.dropout.launcher +chmod -R u+rwX,go-rwx ~/.local/share/com.dropout.launcher + +# macOS (set secure owner-only permissions) +sudo chown -R "$USER":"$USER" ~/Library/Application\ Support/com.dropout.launcher +chmod -R u+rwX,go-rwx ~/Library/Application\ Support/com.dropout.launcher +``` + +**2. Check disk space:** +- Ensure sufficient free space +- Minecraft needs 2-10GB depending on mods +- Clean up old versions + +**3. Antivirus blocking:** +- Add game directory to exceptions +- Some AVs block file access + +### Corrupted Files + +**Issue:** Files appear corrupted or invalid + +**Solutions:** + +**1. Verify checksums:** +- DropOut verifies SHA1/SHA256 +- Failed verification triggers re-download + +**2. Re-download:** +- Delete corrupted file +- Launch version again +- DropOut will re-download + +**3. Clear cache:** +- Delete version folder entirely +- Re-install from scratch + +## Getting More Help + +### Collect Debug Information + +When reporting issues, include: + +**1. System information:** +- OS and version +- DropOut version +- Java version + +**2. Logs:** +- Launcher logs from console +- Game logs if applicable +- Error messages (full text) + +**3. Steps to reproduce:** +- What you did +- What you expected +- What actually happened + +**4. Screenshots:** +- Error messages +- UI issues +- Settings screens + +### Report Issues + +1. Search [existing issues](https://github.com/HydroRoll-Team/DropOut/issues) +2. If not found, [create new issue](https://github.com/HydroRoll-Team/DropOut/issues/new) +3. Use issue template +4. Provide all requested information +5. Be patient and responsive + +### Community Support + +- **GitHub Discussions**: Ask questions +- **Discord**: Real-time help (if available) +- **Documentation**: Check all guides + +## Known Issues + +### Currently Being Worked On + +- Multi-account switching (in progress) +- Custom game directory selection (planned) +- Launcher auto-update (planned) + +### Workarounds Available + +**Issue**: Can't switch between accounts easily +**Workaround**: Log out and log in with different account + +**Issue**: No built-in mod manager +**Workaround**: Manually manage mods in instance folder + +**Issue**: Can't import from other launchers +**Workaround**: Manually copy instance files |