@bobschlowinskii/clicraft 0.4.0

package/docs/commands/launch.md

@@ -0,0 +1,427 @@
+---
+layout: default
+title: launch
+parent: Commands
+nav_order: 5
+description: "Launch your Minecraft instance"
+permalink: /commands/launch
+---
+
+# launch Command
+
+Launch your Minecraft instance directly from the command line.
+
+## 📝 Synopsis
+
+```bash
+clicraft launch [options]
+```
+
+## 📖 Description
+
+The `launch` command starts your Minecraft instance with all the correct Java arguments, libraries, and configurations. It handles:
+
+- Java classpath setup
+- Native library extraction
+- JVM arguments configuration
+- Game arguments setup
+- Authentication (online mode)
+- Offline mode support
+
+## 🎯 Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-i, --instance <path>` | Path to instance directory | Current directory |
+| `--offline` | Launch in offline mode (no authentication) | false |
+| `--verbose` | Show detailed launch information | false |
+
+## 📋 Examples
+
+### Launch from instance directory
+```bash
+cd my-instance
+clicraft launch
+```
+
+### Launch with instance path
+```bash
+clicraft launch --instance ./my-instance
+```
+
+### Launch in offline mode
+```bash
+clicraft launch --offline
+```
+No authentication required - useful for testing or single-player.
+
+### Verbose launch
+```bash
+clicraft launch --verbose
+```
+See detailed Java command and debugging information.
+
+### Launch specific instance
+```bash
+clicraft launch --instance ~/minecraft/modded-fabric
+```
+
+## 🎮 Example Session
+
+### Online Mode (Default)
+```bash
+$ cd my-instance
+$ clicraft launch
+
+Preparing to launch Minecraft...
+✓ Instance detected: my-modded-world
+✓ Minecraft version: 1.21.1
+✓ Mod loader: Fabric 0.16.5
+✓ Authentication: Player123
+✓ Mods found: 5
+
+Launching Minecraft...
+[Minecraft window opens]
+```
+
+### Offline Mode
+```bash
+$ clicraft launch --offline
+
+Preparing to launch Minecraft...
+✓ Instance detected: my-instance
+✓ Minecraft version: 1.21.1
+✓ Mod loader: Fabric 0.16.5
+✓ Mode: Offline
+✓ Username: Player
+
+Launching Minecraft...
+[Minecraft window opens]
+```
+
+## 🔍 Launch Process
+
+### What Happens
+
+1. **Instance Detection**: Finds and validates `mcconfig.json`
+2. **Authentication Check**: Verifies login status (unless `--offline`)
+3. **Library Preparation**: Prepares Java libraries and native files
+4. **JVM Setup**: Configures Java Virtual Machine arguments
+5. **Game Launch**: Executes Java with Minecraft
+6. **Monitor**: Keeps running to show game output
+
+### Verbose Output
+
+With `--verbose`, you'll see:
+```bash
+$ clicraft launch --verbose
+
+Instance: ./my-instance
+Minecraft Version: 1.21.1
+Loader: fabric-loader-0.16.5-1.21.1
+Authentication: Player123 (uuid: 123e...)
+
+Java Command:
+java -Xmx2G -Xms2G \
+  -Djava.library.path=./natives \
+  -cp ./libraries/*.jar:./versions/1.21.1.jar \
+  net.fabricmc.loader.impl.launch.knot.KnotClient \
+  --username Player123 \
+  --uuid 123e4567... \
+  --accessToken xxx \
+  --version 1.21.1
+
+[Game output follows]
+```
+
+## 🎯 Use Cases
+
+### Regular Gameplay
+```bash
+# Login first (one-time)
+clicraft login
+
+# Launch whenever you want to play
+cd my-instance
+clicraft launch
+```
+
+### Testing Mods Offline
+```bash
+# Install mods
+clicraft install sodium
+clicraft install lithium
+
+# Test in offline mode
+clicraft launch --offline
+```
+
+### Multiple Instances
+```bash
+# Launch different instances
+clicraft launch --instance ./vanilla
+clicraft launch --instance ./modded
+clicraft launch --instance ./testing
+```
+
+### Server Launch
+```bash
+cd my-server-instance
+clicraft launch
+
+# Server starts and runs in the terminal
+```
+
+### Development Testing
+```bash
+# Quick offline testing
+clicraft install my-mod --force
+clicraft launch --offline --verbose
+```
+
+## 🖥️ System Requirements
+
+### Java
+- **Required**: Java 21 or higher
+- **Recommended**: Latest Java version
+- **Memory**: At least 4GB RAM available
+
+Verify Java:
+```bash
+java --version
+```
+
+### Display (Client Only)
+- Graphics drivers installed
+- Display server running (X11/Wayland on Linux)
+- Monitor connected
+
+## ⚙️ Configuration
+
+Launch behavior is configured in `mcconfig.json`:
+
+```json
+{
+  "name": "my-instance",
+  "type": "client",
+  "minecraftVersion": "1.21.1",
+  "loader": "fabric",
+  "loaderVersion": "0.16.5",
+  "javaPath": "java",
+  "jvmArgs": ["-Xmx2G", "-Xms2G"]
+}
+```
+
+### Customizing JVM Arguments
+
+Edit `mcconfig.json` to customize Java settings:
+
+```json
+{
+  "jvmArgs": [
+    "-Xmx4G",           // Maximum memory (4GB)
+    "-Xms4G",           // Initial memory (4GB)
+    "-XX:+UseG1GC",     // Use G1 garbage collector
+    "-XX:+UnlockExperimentalVMOptions",
+    "-XX:G1NewSizePercent=20",
+    "-XX:G1ReservePercent=20",
+    "-XX:MaxGCPauseMillis=50",
+    "-XX:G1HeapRegionSize=32M"
+  ]
+}
+```
+
+### Memory Recommendations
+
+| Instance Type | Recommended Memory |
+|---------------|-------------------|
+| Vanilla | 2GB (`-Xmx2G`) |
+| Light mods | 3GB (`-Xmx3G`) |
+| Heavy mods | 4-6GB (`-Xmx4G`) |
+| Modpacks | 6-8GB (`-Xmx6G`) |
+| Servers | 4-8GB+ depending on players |
+
+## 🌐 Online vs Offline
+
+### Online Mode (Default)
+Requires `clicraft login`:
+- ✅ Multiplayer servers
+- ✅ Realms
+- ✅ Custom skins
+- ✅ Official servers
+- ✅ Account verification
+
+### Offline Mode (`--offline`)
+No login required:
+- ✅ Single-player
+- ✅ LAN play
+- ✅ Mod testing
+- ❌ Online multiplayer
+- ❌ Custom skins
+- ❌ Realms
+
+## 📊 Game Output
+
+The command shows Minecraft's output:
+
+```
+[00:00:01] [main/INFO]: Loading Minecraft 1.21.1 with Fabric Loader 0.16.5
+[00:00:02] [main/INFO]: Loading 5 mods
+[00:00:02] [main/INFO]:   - sodium 0.6.0
+[00:00:02] [main/INFO]:   - lithium 0.12.0
+[00:00:03] [main/INFO]: Minecraft loaded successfully
+```
+
+Exit codes:
+- `0` - Normal exit
+- `1` - Crash or error
+- `130` - Terminated by user (Ctrl+C)
+
+## ⚠️ Common Issues
+
+### "Instance not found"
+Make sure you're in an instance directory or using `--instance`:
+```bash
+# Check for mcconfig.json
+ls mcconfig.json
+
+# Or specify instance
+clicraft launch --instance ./my-instance
+```
+
+### "Not logged in"
+Login required for online mode:
+```bash
+clicraft login
+clicraft launch
+```
+
+Or use offline mode:
+```bash
+clicraft launch --offline
+```
+
+### "Java not found"
+Install Java 21 or higher:
+```bash
+# Verify Java installation
+java --version
+
+# If not installed, download from:
+# https://adoptium.net/
+```
+
+### "Out of memory"
+Increase memory allocation in `mcconfig.json`:
+```json
+{
+  "jvmArgs": ["-Xmx4G", "-Xms4G"]
+}
+```
+
+### "Native library error"
+On Linux, you may need:
+```bash
+sudo apt-get install libglfw3 libglfw3-dev
+```
+
+### Game Crashes
+Check the logs:
+```bash
+cd my-instance
+ls logs/
+cat logs/latest.log
+```
+
+## 🎮 Server Hosting
+
+### Starting a Server
+```bash
+cd my-server-instance
+clicraft launch
+
+# Server starts and shows:
+[Server] Starting Minecraft server on *:25565
+[Server] Done! Server is running
+```
+
+### Server Commands
+Type commands in the terminal:
+```
+> stop          # Stop the server
+> list          # List players
+> op username   # Make someone an operator
+```
+
+### Background Server
+Run server in background:
+```bash
+nohup clicraft launch > server.log 2>&1 &
+```
+
+View logs:
+```bash
+tail -f server.log
+```
+
+Stop server:
+```bash
+# Type 'stop' in server console or:
+kill $(pgrep -f "minecraft.*server")
+```
+
+## 💡 Pro Tips
+
+1. **Login Once**: Authentication persists, no need to login every launch
+2. **Check Status**: Use `clicraft status` before launching
+3. **Test Offline**: Use `--offline` for quick mod testing
+4. **Allocate Memory**: Give Minecraft enough RAM for smooth gameplay
+5. **Close Other Apps**: Close memory-heavy apps before launching
+6. **Use Verbose**: Use `--verbose` for troubleshooting launch issues
+7. **Multiple Instances**: Launch different instances for different play styles
+
+## 🔧 Performance Tips
+
+### Optimize JVM Arguments
+```json
+{
+  "jvmArgs": [
+    "-Xmx4G",
+    "-Xms4G",
+    "-XX:+UseG1GC",
+    "-XX:+UnlockExperimentalVMOptions",
+    "-XX:G1NewSizePercent=20",
+    "-XX:G1ReservePercent=20",
+    "-XX:MaxGCPauseMillis=50"
+  ]
+}
+```
+
+### Install Performance Mods
+```bash
+clicraft install sodium      # Rendering
+clicraft install lithium     # General
+clicraft install starlight   # Lighting
+clicraft install ferritecore # Memory
+```
+
+### Monitor Performance
+Use `--verbose` to see Java command and diagnose issues.
+
+## 📚 Related Commands
+
+- [`clicraft create`](create.md) - Create an instance to launch
+- [`clicraft login`](login.md) - Login for online play
+- [`clicraft install`](install.md) - Install mods before launching
+- [`clicraft info`](info.md) - View instance information
+
+## 🔗 See Also
+
+- [Commands Overview](../commands.md)
+- [Configuration Guide](../configuration.md)
+- [Login Command](login.md)
+- [Info Command](info.md)
+
+---
+
+[← Back to Commands](../commands.md) | [Next: info →](info.md)

package/docs/commands/search.md

@@ -0,0 +1,276 @@
+---
+layout: default
+title: search
+parent: Commands
+nav_order: 2
+description: "Search for mods on Modrinth"
+permalink: /commands/search
+---
+
+# search Command
+
+Search for Minecraft mods on Modrinth with powerful filtering options.
+
+## 📝 Synopsis
+
+```bash
+clicraft search <query> [options]
+```
+
+## 📖 Description
+
+The `search` command queries the Modrinth API to find mods matching your search criteria. You can filter results by Minecraft version, mod loader, and limit the number of results displayed.
+
+Modrinth is a popular open-source mod hosting platform with a large collection of high-quality Minecraft mods.
+
+## 🎯 Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<query>` | Search query text | Yes |
+
+## 🎯 Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-l, --limit <number>` | Number of results to show | 10 |
+| `-v, --version <version>` | Filter by Minecraft version | None |
+| `--loader <loader>` | Filter by mod loader | None |
+| `--verbose` | Enable verbose output | false |
+
+### Supported Loaders
+- `fabric` - Fabric mods
+- `forge` - Forge mods
+- `quilt` - Quilt mods
+- `neoforge` - NeoForge mods
+
+## 📋 Examples
+
+### Basic search
+```bash
+clicraft search sodium
+```
+Searches for mods matching "sodium" and displays up to 10 results.
+
+### Search with version filter
+```bash
+clicraft search shader --version 1.21.1
+```
+Find shader mods compatible with Minecraft 1.21.1.
+
+### Search with loader filter
+```bash
+clicraft search optimization --loader fabric
+```
+Find optimization mods for the Fabric mod loader.
+
+### Combined filters
+```bash
+clicraft search "performance" --version 1.20.1 --loader fabric --limit 20
+```
+Find up to 20 performance mods for Fabric on Minecraft 1.20.1.
+
+### Multi-word search
+```bash
+clicraft search "world generation"
+```
+Search for mods related to world generation (use quotes for multi-word queries).
+
+### Limit results
+```bash
+clicraft search minimap --limit 5
+```
+Show only the top 5 results for minimap mods.
+
+## 💡 Output Format
+
+The search results display:
+
+```
+Found 50 mods matching "sodium"
+
+1. Sodium
+   A modern rendering engine for Minecraft which greatly improves performance
+   Author: CaffeineMC
+   Downloads: 50.2M
+   Updated: 2024-01-15
+   ID: AANobbMI
+
+2. Sodium Extra
+   Extra features for Sodium
+   Author: FlashyReese
+   Downloads: 5.1M
+   Updated: 2024-01-12
+   ID: PtjYWJkn
+
+...
+```
+
+Each result shows:
+- **Name** - The mod's display name
+- **Description** - Short description of what the mod does
+- **Author** - The mod creator
+- **Downloads** - Total download count
+- **Updated** - Last update date
+- **ID** - Modrinth project ID (used for installation)
+
+## 🎮 Example Session
+
+```bash
+$ clicraft search sodium --version 1.21.1 --loader fabric
+
+Searching Modrinth for "sodium"...
+
+Found 3 mods matching "sodium"
+
+1. Sodium
+   A modern rendering engine for Minecraft
+   Author: CaffeineMC
+   Downloads: 50.2M
+   Updated: 2024-01-15
+   ID: AANobbMI
+
+2. Sodium Extra
+   Adds additional options to Sodium
+   Author: FlashyReese
+   Downloads: 5.1M
+   Updated: 2024-01-12
+   ID: PtjYWJkn
+
+3. Reese's Sodium Options
+   Alternative options menu for Sodium
+   Author: FlashyReese
+   Downloads: 3.2M
+   Updated: 2024-01-10
+   ID: Bh37bMuy
+
+To install a mod, use: clicraft install <mod-name-or-id>
+```
+
+## 🎯 Use Cases
+
+### Finding Popular Optimization Mods
+```bash
+clicraft search optimization --limit 10 --loader fabric
+```
+
+### Searching for Specific Mod
+```bash
+clicraft search "just enough items"
+```
+
+### Discovering New Mods
+```bash
+clicraft search decoration --version 1.20.1 --limit 25
+```
+
+### Checking Mod Availability
+```bash
+clicraft search "iris shaders" --version 1.21.1 --loader fabric
+```
+
+## 🔍 Search Tips
+
+### Use Specific Terms
+Instead of searching "better", try:
+- "performance"
+- "optimization"
+- "quality of life"
+- "world generation"
+
+### Filter by Version
+Always include `--version` when searching for mods for a specific Minecraft version:
+```bash
+clicraft search minimap --version 1.20.1
+```
+
+### Filter by Loader
+If you know your instance's mod loader, filter by it:
+```bash
+clicraft search sodium --loader fabric
+```
+
+### Adjust Result Limits
+- Use `--limit 5` for quick searches
+- Use `--limit 50` for comprehensive browsing
+
+### Exact Mod Names
+For well-known mods, use their exact name:
+```bash
+clicraft search "optifine"
+clicraft search "sodium"
+clicraft search "lithium"
+```
+
+## ⚠️ Common Issues
+
+### No Results Found
+If your search returns no results:
+- Check your spelling
+- Try broader search terms
+- Remove version/loader filters
+- Try searching on [Modrinth.com](https://modrinth.com) directly
+
+### Network Errors
+If you see "Failed to fetch from Modrinth":
+- Check your internet connection
+- Modrinth may be temporarily down
+- Try again in a few moments
+
+### Too Many Results
+If you get too many results:
+- Add more specific search terms
+- Use `--version` and `--loader` filters
+- Reduce `--limit` to see top results only
+
+## 💡 Pro Tips
+
+1. **Save Mod IDs**: Note down the mod ID from search results for easy installation
+2. **Version Compatibility**: Always filter by your Minecraft version when building a mod pack
+3. **Loader Consistency**: Stick to one mod loader (Fabric or Forge) for compatibility
+4. **Popular Mods First**: Search results are sorted by relevance and popularity
+5. **Dependencies**: Some mods require other mods - check descriptions carefully
+
+## 📚 Related Commands
+
+- [`clicraft install`](install.md) - Install a mod from search results
+- [`clicraft info`](info.md) - View installed mods in your instance
+- [`clicraft upgrade`](upgrade.md) - Update installed mods
+
+## 🔗 Installing from Search Results
+
+After finding a mod with `search`, install it using either:
+
+```bash
+# Using mod name
+clicraft install sodium
+
+# Using Modrinth ID
+clicraft install AANobbMI
+```
+
+## 📖 API Information
+
+The search command uses the [Modrinth API](https://docs.modrinth.com/api-spec) to fetch mod information. Results are fetched in real-time from Modrinth's servers.
+
+## 🆘 Troubleshooting
+
+### "API rate limit exceeded"
+Modrinth has rate limits. Wait a few minutes before searching again.
+
+### "Invalid loader specified"
+Valid loaders are: `fabric`, `forge`, `quilt`, `neoforge`. Check your spelling.
+
+### "Invalid version format"
+Minecraft versions should be in format like: `1.21.1`, `1.20.1`, `1.19.2`
+
+## 🔗 See Also
+
+- [Commands Overview](../commands.md)
+- [Install Command](install.md)
+- [Upgrade Command](upgrade.md)
+- [Modrinth Website](https://modrinth.com)
+
+---
+
+[← Back to Commands](../commands.md) | [Next: install →](install.md)