# Polymerium

![Polymerium](https://socialify.git.ci/d3ara1n/Polymerium/image?description=1&font=Jost&forks=1&issues=1&language=1&name=1&owner=1&pattern=Overlapping%20Hexagons&pulls=1&stargazers=1&theme=Auto)

<div align="center">

**A next-generation Minecraft instance manager that thinks differently about game management.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![.NET 10.0](https://img.shields.io/badge/.NET-10-5C2D91?style=for-the-badge&logoColor=white)](https://dotnet.microsoft.com/)
[![Avalonia](https://img.shields.io/badge/Avalonia-12-3355FF?style=for-the-badge&logoColor=white)](https://avaloniaui.net/)
[![C#](https://img.shields.io/badge/C%23-14-239120?style=for-the-badge&logoColor=white)](https://learn.microsoft.com/en-us/dotnet/csharp/)
[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=for-the-badge&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/d3ara1n/Polymerium)

[![Codacy Badge](https://app.codacy.com/project/badge/Grade/8516e3e1a3994d138a1adc537d7c6ecd)](https://app.codacy.com/gh/d3ara1n/Polymerium/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[![CodeFactor](https://www.codefactor.io/repository/github/d3ara1n/polymerium/badge)](https://www.codefactor.io/repository/github/d3ara1n/polymerium)

[🌐 中文介绍](https://github.com/d3ara1n/Polymerium/blob/main/README.zh.md) • [📥 Download](https://github.com/d3ara1n/Polymerium/releases) • [📖 Documentation](https://polymerium.dearain.dev) • [🐛 Report Bug](https://github.com/d3ara1n/Polymerium/issues) • [💡 Request Feature](https://github.com/d3ara1n/Polymerium/issues)

</div>

---

## 🎮 Experience Polymerium in Action

<div align="center">

[![Screenshot](assets/screenshots/overview.avif)](#-experience-polymerium-in-action)

*From launch to gameplay in seconds* ⚡

</div>

---

## 🌟 What Makes Polymerium Different

> **Traditional Minecraft launchers manage files. Polymerium manages experiences.**

### 🚀 The Evolution of Minecraft Launchers

| Generation  | Management Focus | Representative Approach                             |
|-------------|------------------|-----------------------------------------------------|
| **1st Gen** | 📁 Versions      | "Version Isolation" mechanism                       |
| **2nd Gen** | 📦 Instances     | Isolated game environments with copied resources    |
| **3rd Gen** | 🧬 Metadata      | Declarative configuration with on-demand deployment |

**Polymerium is a third-generation launcher.** Instead of copying and storing thousands of mod files for each instance,
Polymerium describes your game setup as lightweight metadata and builds the actual game files on-demand. This
revolutionary approach brings several game-changing benefits:

### 🎯 **Smart Resource Management**

- **Zero Duplication**: Multiple instances sharing the same mods? Only one copy exists on disk
- **Symlink Magic**: Files are intelligently linked, not copied, saving gigabytes of storage
- **Instant Switching**: Change between completely different modpacks in seconds

### 📦 **Portable Game Experiences**

- **Metadata-Driven**: Your entire game setup fits in a tiny configuration file
- **Version Control Ready**: Use Git to collaborate on modpack development
- **True Portability**: Share your exact game experience with a simple file transfer

### 🔧 **Effortless Maintenance**

- **Integrity Guaranteed**: Every deployment validates file completeness and correctness
- **Dependency Resolution**: Automatically handles mod dependencies and conflicts
- **One-Click Updates**: Upgrade individual mods or entire modpacks seamlessly

### 🎮 **Player-Focused Design**

- **No Java Hunting**: Configure Java once, works everywhere
- **Account Flexibility**: Multiple accounts, each linked to specific instances
- **Clean Uninstall**: Remove Polymerium completely by deleting two folders

---

## ✨ Key Features

### 🏗️ Modern Architecture

- 🎨 **Avalonia UI**: Beautiful, responsive interface that works across platforms
- 📋 **Metadata Engine**: Lightweight instance descriptions that rebuild perfectly every time
- 🚀 **Deployment System**: Intelligent file management with integrity checking
- 🔗 **Resource Pooling**: Shared file storage with symlink distribution

### 🌐 Platform Integration

- 🎟️ **CurseForge & Modrinth**: Native integration with major mod repositories
- 📦 **Modpack Publishing**: Export your instances as distributable modpacks
- 📝 **Automatic Changelogs**: Generated documentation for your modpack versions

### 👨‍💻 Developer Experience

- 📸 **Instance Snapshots**: Save and restore complete game states
- 📜 **Layered Configuration**: Separate user settings from core game data
- 🔄 **Build Reproducibility**: Identical deployments from the same metadata

---

## Getting Started

### 📥 Installation

> [!NOTE]
> Polymerium is currently in active development. Features and UI may change between releases.

Before downloading, check the note for your platform:

<details>
<summary>🪟 <strong>Windows</strong> — enable Developer Mode (required for symlinks)</summary>

Polymerium uses [symbolic links](https://www.wikiwand.com/en/Symbolic_link) for efficient file management. Enable Developer Mode to allow symlink creation without administrator privileges.

**Windows 11**

```
Settings → System → For developers → Developer Mode
```

**Windows 10**

```
Settings → Update & Security → For developers → Developer Mode
```

**Windows 7/8**

```
Upgrade to Windows 10+ first 💥
```

</details>

<details>
<summary>🍎 <strong>macOS</strong> — "Installer is damaged" workaround</summary>

The PKG installer is not signed with an Apple Developer certificate, so macOS Gatekeeper may block it with a "damaged" message.

1. Right-click the `.pkg` file and choose **Open**.
2. If that doesn't work, remove the quarantine flag from Terminal:

   ```bash
   xattr -d com.apple.quarantine Polymerium-osx-arm64-Setup.pkg
   ```

3. Open the `.pkg` file again and follow the installer.

</details>

| Platform | Package | Direct Download |
| --- | --- | --- |
| Windows x64 | Installer | [Download](https://github.com/d3ara1n/Polymerium/releases/latest/download/Polymerium-win-Setup.exe) |
| Linux x64 | AppImage | [Download](https://github.com/d3ara1n/Polymerium/releases/latest/download/Polymerium.AvaloniaImage) |
| macOS Apple Silicon | PKG installer | [Download](https://github.com/d3ara1n/Polymerium/releases/latest/download/Polymerium-osx-Setup.pkg) |

[已有 Mirror酱 CDK？前往 Mirror酱 高速下载](https://mirrorchyan.com/zh/projects?rid=Polymerium&channel=Polymerium_setup&source=github-readme)

**📥 Download** -> **🚀 Run** -> **⚙️ Setup**

1. **Download** the package for your platform
2. **Run** the installer or executable
3. **Follow** the setup wizard to configure your first instance

### 🚀 Quick Start

**🎮 Create** → **📦 Add Content** → **🔧 Deploy** → **▶️ Play**

1. **Create Instance**: Define your Minecraft version and mod loader
2. **Add Content**: Browse and install mods from CurseForge or Modrinth
3. **Deploy**: Let Polymerium build your game files
4. **Play**: Launch directly or export as a modpack

---

## 🏗️ Architecture Overview

| 🛠️ Technology           | 📋 Purpose                              | 🔗 Integration       |
|--------------------------|-----------------------------------------|----------------------|
| **.NET 10.0**            | Latest runtime with C# preview features | Core platform        |
| **Avalonia 12**          | Cross-platform XAML UI framework        | Presentation layer   |
| **MVVM Pattern**         | Clean separation of concerns            | Architecture pattern |
| **Dependency Injection** | Modular, testable architecture          | Service management   |
| **Reactive Extensions**  | Responsive data handling                | Data flow            |

### 📁 Project Structure

```sh
Polymerium/
├── 📖 website/                # Documentation & project site
├── 🎨 src/                    # Application source code
├── 🔗 submodules/             # Embedded third-party project sources
├── 📝 notes/                  # Internal notes
├── 📜 changelogs/             # Version changelogs
├── 🛠️ scripts/                # Build & publish scripts
├── 🖼️ assets/                 # Screenshots and media
└── 📋 plans/                  # Planning documents
```

---

## 🖥️ Platform Support

| Platform                                                                                                   | Status         |
|------------------------------------------------------------------------------------------------------------|----------------|
| ![Windows](https://img.shields.io/badge/Windows-10+-0078D6?style=flat-square&logo=windows&logoColor=white) | ✅ **Stable**   |
| ![Linux](https://img.shields.io/badge/Linux-AppImage-FCC624?style=flat-square&logo=linux&logoColor=black)  | ✅ **Stable**   |
| ![macOS](https://img.shields.io/badge/macOS-ARM64-000000?style=flat-square&logo=apple&logoColor=white)     | ✅ **Stable**   |

---

## Privacy & Security

Polymerium respects your privacy:

- **Minor Telemetry**: Collect least necessary data for debugging
- **Local Storage**: All data stays on your machine
- **Minimal Footprint**: Clean uninstall leaves no traces
- **Open Source**: Transparent, auditable codebase

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 📊 Project Statistics

[![Star History Chart](https://api.star-history.com/svg?repos=d3ara1n/Polymerium&type=Date)](https://www.star-history.com/#d3ara1n/Polymerium&Date)

![Repobeats Analytics](https://repobeats.axiom.co/api/embed/594b206d199e6aae83226e6b7b834f6896322858.svg "Repobeats analytics image")

## 📚 References & Acknowledgments

### 🔗 Technical References

- [Inside a Minecraft Launcher](https://ryanccn.dev/posts/inside-a-minecraft-launcher) - Game launch process and
  Fabric/Quilt deployment
- [Tutorial: Writing a Launcher](https://minecraft.fandom.com/zh/wiki/%E6%95%99%E7%A8%8B/%E7%BC%96%E5%86%99%E5%90%AF%E5%8A%A8%E5%99%A8) -
  Game launch process guide
- [ForgeWrapper](https://github.com/ZekerZhayard/ForgeWrapper) - Forge integration reference
- [Microsoft Authentication Scheme](https://wiki.vg/Microsoft_Authentication_Scheme) - Authentication implementation

### 🙏 Special Thanks

- **Minecraft Community** - For the incredible modding ecosystem
- **Avalonia Team** - For the excellent cross-platform UI framework
- **API Providers** - CurseForge and Modrinth for their public APIs
- **Contributors** - Everyone who helps make Polymerium better

## 📄 License

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fd3ara1n%2FPolymerium.svg?type=large&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fd3ara1n%2FPolymerium?ref=badge_large&issueType=license)

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE.txt) file for details.

---

<div align="center">

**Polymerium: Rethinking Minecraft instance management for the modern era** ✨

Made with ❤️ by the Polymerium team

</div>
