docs: prepare Pakker documentation
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I03df3787081bde6ebf0366a24320307a6a6a6964
This commit is contained in:
parent
563ff2b187
commit
5a0a5cedeb
GPG key ID:
29D95B64378DB4BF
4 changed files with 2285 additions and 0 deletions
455
docs/README.md
Normal file
455
docs/README.md
Normal file
|
|
@ -0,0 +1,455 @@
|
|||
# Pakker
|
||||
|
||||
A fast, reliable multiplatform modpack manager for Minecraft, written in Rust.
|
||||
|
||||
## Overview
|
||||
|
||||
Pakker is a command-line tool for managing Minecraft modpacks across multiple
|
||||
platforms including CurseForge, Modrinth, and GitHub. It provides a streamlined
|
||||
workflow for creating, maintaining, and distributing modpacks with support for
|
||||
automated dependency resolution, version management, and multi-platform exports.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Multi-Platform Support
|
||||
|
||||
- **CurseForge**, **Modrinth**, and **GitHub** integration
|
||||
- Unified project management across all platforms
|
||||
- Platform-specific filtering and optimizations
|
||||
- Automatic platform-specific manifest generation
|
||||
|
||||
### Intelligent Project Management
|
||||
|
||||
- **Dependency Resolution** - Automatically resolve and manage project
|
||||
dependencies
|
||||
- **Version Management** - Update strategies (latest, specific version, pinned)
|
||||
- **Project Inspection** - Detailed project information with dependency trees
|
||||
- **Fuzzy Matching** - Typo-tolerant project searches with suggestions
|
||||
|
||||
### Flexible Export System
|
||||
|
||||
- **Profile-Based Exports** - Customize exports for different platforms and use
|
||||
cases
|
||||
- **Platform Filtering** - Automatically exclude projects not available on
|
||||
target platform
|
||||
- **Override Management** - Separate override directories for client/server
|
||||
configurations
|
||||
- **Non-Interactive Mode** - Full CI/CD support with scriptable commands
|
||||
|
||||
### Advanced Configuration
|
||||
|
||||
- **Profile-Specific Settings** - Override paths, filtering rules, and export
|
||||
behavior per profile
|
||||
- **Project-Level Customization** - Per-project export settings, aliases, and
|
||||
properties
|
||||
- **Side Detection** - Automatic client/server/both classification
|
||||
- **Redistributable Control** - Manage non-redistributable mod inclusion per
|
||||
profile
|
||||
|
||||
## Installation
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/pakker
|
||||
cd pakker
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
The binary will be available at `target/release/pakker`.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Rust 1.70 or later
|
||||
- Git (for remote repository features)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Initialize a New Modpack
|
||||
|
||||
```bash
|
||||
# Create a new modpack for Fabric 1.20.1
|
||||
pakker init -m 1.20.1 -l fabric
|
||||
|
||||
# Or for Forge
|
||||
pakker init -m 1.20.1 -l forge
|
||||
```
|
||||
|
||||
### Add Mods
|
||||
|
||||
```bash
|
||||
# Interactive mode - search and select
|
||||
pakker add sodium
|
||||
|
||||
# Non-interactive with platform specification
|
||||
pakker add-prj --mr sodium --yes
|
||||
|
||||
# Add with specific properties
|
||||
pakker add-prj --cf jei --side both --yes
|
||||
```
|
||||
|
||||
### Inspect Projects
|
||||
|
||||
```bash
|
||||
# View project details
|
||||
pakker inspect sodium
|
||||
|
||||
# Multiple projects with dependency trees
|
||||
pakker inspect sodium lithium phosphor
|
||||
|
||||
# View all projects
|
||||
pakker ls
|
||||
```
|
||||
|
||||
### Fetch Mod Files
|
||||
|
||||
```bash
|
||||
# Download all mod files
|
||||
pakker fetch
|
||||
|
||||
# Or use sync to update and fetch
|
||||
pakker sync
|
||||
```
|
||||
|
||||
### Export Modpack
|
||||
|
||||
```bash
|
||||
# Export for CurseForge
|
||||
pakker export --profile curseforge
|
||||
|
||||
# Export for Modrinth
|
||||
pakker export --profile modrinth
|
||||
|
||||
# Export server pack
|
||||
pakker export --profile serverpack
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
my-modpack/
|
||||
├── pakku.json # Modpack configuration
|
||||
├── pakku-lock.json # Lockfile with resolved versions
|
||||
├── mods/ # Downloaded mod files
|
||||
├── overrides/ # Files to include in all exports
|
||||
├── server-overrides/ # Server-specific files
|
||||
└── client-overrides/ # Client-specific files
|
||||
```
|
||||
|
||||
## Configuration Example
|
||||
|
||||
### Basic Configuration (`pakku.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Awesome Modpack",
|
||||
"version": "1.0.0",
|
||||
"description": "A performance-focused modpack",
|
||||
"author": "YourName",
|
||||
"overrides": ["overrides"],
|
||||
"serverOverrides": ["server-overrides"],
|
||||
"clientOverrides": ["client-overrides"]
|
||||
}
|
||||
```
|
||||
|
||||
### With Export Profiles
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Multi-Platform Pack",
|
||||
"version": "1.0.0",
|
||||
"overrides": ["overrides"],
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "curseforge-specific"]
|
||||
},
|
||||
"modrinth": {
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true
|
||||
},
|
||||
"serverpack": {
|
||||
"includeClientOnly": false,
|
||||
"serverOverrides": ["server-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# Initialize project
|
||||
pakker init -m 1.20.1 -l fabric
|
||||
|
||||
# Add core mods
|
||||
pakker add-prj --mr fabric-api --yes
|
||||
pakker add-prj --mr sodium --yes
|
||||
pakker add-prj --mr lithium --yes
|
||||
|
||||
# Configure and test
|
||||
pakker fetch
|
||||
# ... test in game ...
|
||||
|
||||
# Add more mods
|
||||
pakker add create
|
||||
|
||||
# Check status
|
||||
pakker status
|
||||
|
||||
# Export for testing
|
||||
pakker export --profile modrinth
|
||||
```
|
||||
|
||||
### CI/CD Pipeline
|
||||
|
||||
```bash
|
||||
# Non-interactive project addition
|
||||
pakker add-prj --mr fabric-api --yes --no-deps
|
||||
pakker add-prj --cf jei --yes
|
||||
|
||||
# Update to latest versions
|
||||
pakker update --yes
|
||||
|
||||
# Fetch all files
|
||||
pakker fetch
|
||||
|
||||
# Export for all platforms
|
||||
pakker export --profile curseforge -o dist/curseforge.zip
|
||||
pakker export --profile modrinth -o dist/modrinth.mrpack
|
||||
pakker export --profile serverpack -o dist/server.zip
|
||||
```
|
||||
|
||||
### Multi-Platform Release
|
||||
|
||||
```bash
|
||||
# Add projects from multiple platforms
|
||||
pakker add-prj --mr sodium --cf sodium --yes
|
||||
pakker add-prj --mr lithium --cf lithium --yes
|
||||
|
||||
# Configure CurseForge export (no non-redistributable)
|
||||
# Configure Modrinth export (allow all)
|
||||
# (in pakku.json - see Export Profiles documentation)
|
||||
|
||||
# Export for both
|
||||
pakker export --profile curseforge -o releases/curseforge-pack.zip
|
||||
pakker export --profile modrinth -o releases/modrinth-pack.mrpack
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Commands Reference](./COMMANDS.md)** - Complete command documentation
|
||||
- **[Export Profiles](./EXPORT_PROFILES.md)** - Profile configuration guide
|
||||
- **[Migration Guide](./MIGRATION.md)** - Migrating from Pakku
|
||||
- **[Examples](../examples/)** - Configuration examples
|
||||
|
||||
## Command Overview
|
||||
|
||||
| Command | Description |
|
||||
| ------------- | ------------------------------------------------------ |
|
||||
| `init` | Initialize a new modpack project |
|
||||
| `import` | Import an existing modpack |
|
||||
| `add` | Add projects interactively |
|
||||
| `add-prj` | Add projects non-interactively with explicit platforms |
|
||||
| `rm` | Remove projects |
|
||||
| `update` | Update projects to newer versions |
|
||||
| `ls` | List all projects in modpack |
|
||||
| `inspect` | View detailed project information |
|
||||
| `fetch` | Download all project files |
|
||||
| `sync` | Update and fetch in one command |
|
||||
| `export` | Export modpack for distribution |
|
||||
| `status` | Check for available updates |
|
||||
| `set` | Modify project properties |
|
||||
| `link` | Link related projects |
|
||||
| `diff` | Show differences with remote |
|
||||
| `credentials` | Manage API credentials |
|
||||
| `cfg` | Configure modpack properties |
|
||||
|
||||
See [COMMANDS.md](./COMMANDS.md) for detailed usage.
|
||||
|
||||
## Features in Detail
|
||||
|
||||
### Dependency Resolution
|
||||
|
||||
Pakker automatically resolves and manages dependencies:
|
||||
|
||||
```bash
|
||||
pakker add sodium
|
||||
# Automatically adds fabric-api as a dependency
|
||||
```
|
||||
|
||||
Dependencies are tracked in `pakku-lock.json` and can be inspected:
|
||||
|
||||
```bash
|
||||
pakker inspect sodium
|
||||
# Shows:
|
||||
# Dependencies: fabric-api
|
||||
```
|
||||
|
||||
### Project Side Detection
|
||||
|
||||
Projects are automatically classified as client-only, server-only, or both:
|
||||
|
||||
- **Client-only**: Shaders, client performance mods, minimap mods
|
||||
- **Server-only**: Server management mods, world generation mods
|
||||
- **Both**: Most gameplay mods, APIs, libraries
|
||||
|
||||
Override this with:
|
||||
|
||||
```bash
|
||||
pakker set sodium --side client
|
||||
```
|
||||
|
||||
### Version Management
|
||||
|
||||
Control how projects are updated:
|
||||
|
||||
```bash
|
||||
# Pin to specific version
|
||||
pakker set sodium --strategy specific --version 0.5.0
|
||||
|
||||
# Always use latest
|
||||
pakker set lithium --strategy latest
|
||||
|
||||
# Manual updates only
|
||||
pakker set fabric-api --strategy pinned
|
||||
```
|
||||
|
||||
### Export Profiles
|
||||
|
||||
Customize export behavior per platform:
|
||||
|
||||
- **Override directories** - Different overrides per export
|
||||
- **Platform filtering** - Exclude unavailable mods
|
||||
- **Redistributable control** - Manage non-redistributable content
|
||||
- **Client/server filtering** - Remove client-only mods from server packs
|
||||
|
||||
See [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for complete documentation.
|
||||
|
||||
### Remote Repositories
|
||||
|
||||
Sync modpack configuration with Git repositories:
|
||||
|
||||
```bash
|
||||
# Add remote
|
||||
pakker remote add origin https://github.com/user/modpack.git
|
||||
|
||||
# Pull updates
|
||||
pakker remote-update
|
||||
|
||||
# Configuration is automatically synced
|
||||
```
|
||||
|
||||
### Credentials Management
|
||||
|
||||
Store platform API credentials securely:
|
||||
|
||||
```bash
|
||||
# Set credentials
|
||||
pakker credentials set --curseforge YOUR_CF_KEY
|
||||
pakker credentials set --modrinth YOUR_MR_TOKEN
|
||||
|
||||
# Credentials are used automatically for:
|
||||
# - Private mods
|
||||
# - Rate limit increases
|
||||
# - Authenticated downloads
|
||||
```
|
||||
|
||||
## Platform Compatibility
|
||||
|
||||
### CurseForge
|
||||
|
||||
- Full project search and metadata
|
||||
- Automatic manifest generation
|
||||
- Non-redistributable mod detection
|
||||
- Curse modpack import support
|
||||
|
||||
### Modrinth
|
||||
|
||||
- Complete Modrinth API integration
|
||||
- .mrpack format import/export
|
||||
- Environment metadata support
|
||||
- Full modpack search
|
||||
|
||||
### GitHub
|
||||
|
||||
- GitHub Releases integration
|
||||
- Direct JAR downloads
|
||||
- Version tag support
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Fuzzy Project Search
|
||||
|
||||
Don't remember exact names? Pakker helps:
|
||||
|
||||
```bash
|
||||
pakker add sodum
|
||||
# Suggested: Did you mean "sodium"?
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
Add multiple projects efficiently:
|
||||
|
||||
```bash
|
||||
pakker add-prj --mr sodium --yes
|
||||
pakker add-prj --mr lithium --yes
|
||||
pakker add-prj --mr phosphor --yes
|
||||
```
|
||||
|
||||
Or use a script:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
mods=("sodium" "lithium" "phosphor" "iris")
|
||||
for mod in "${mods[@]}"; do
|
||||
pakker add-prj --mr "$mod" --yes
|
||||
done
|
||||
```
|
||||
|
||||
### Inspect Dependency Trees
|
||||
|
||||
Visualize complex dependency relationships:
|
||||
|
||||
```bash
|
||||
pakker inspect create
|
||||
# Shows:
|
||||
# create v0.5.1
|
||||
# ├── flywheel v0.6.10
|
||||
# │ └── forge-api v1.20.1
|
||||
# └── registrate v1.3.3
|
||||
```
|
||||
|
||||
### Custom Export Profiles
|
||||
|
||||
Create specialized export configurations:
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"production": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "prod-config"]
|
||||
},
|
||||
"development": {
|
||||
"includeNonRedistributable": true,
|
||||
"overrides": ["overrides", "dev-config"]
|
||||
},
|
||||
"client": {
|
||||
"includeClientOnly": true,
|
||||
"overrides": ["overrides", "client-extras"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Pakker is inspired by [Pakku](https://github.com/juraj-hrivnak/Pakku), bringing
|
||||
similar functionality with improved performance and additional features through
|
||||
Rust implementation.
|
||||
Loading…
Add table
Add a link
Reference in a new issue