Native Client Launcher, Server Browser & Unified Profile Engine

[Osiris-Team]

OUTDATED:
Importance: 8/10

Problem:
The current system tray UI is outdated looking and does not really have that many cool features.
Plus its mainly targeted towards server owners / less minecraft players.

Solution:
Fully integrate/reproduce the existing UI after merging an open source minecraft client/launcher (see existing outdated branch mc-client-hmcl-integration for reference/ideas) by using the existing capabilities of the newly merged mc-client-hmcl-integration code. The new/merged UI should get launched instead of the current system tray UI when clicking on the icon.

After doing this we also need a new server browser tab which is based on the actual minecraft client server browser/data and allows to launch the correct minecraft version directly when trying to join a server and automatically downloads or updates mods for that version to ensure a seamless minecraft experience accross different servers with different versions without the hassle of doing it manually. This also means we need to implement the idea of mod-packs or better profiles and also let the user easily configure / interact with these things via the UI and via the CLI.

Feel free to ask clarifying questions before starting the implementation and produce a detailled implementation plan first after deep analysis of the current state of the repo.

[murrayerickson123-cloud]

I'd like to work on #296 with disclosed Codex assistance. I reviewed current master (604c8ec) and the experimental mc-client-hmcl-integration branch (f70135d). Here is the proposed implementation plan before starting changes.

1. Restore the launcher build on current master. Integrate the experimental branch while preserving the 47 newer master commits, including the recent Steam Workshop fixes. Restore HMCL resources and the JavaFX dependency declarations through src/main/java/JPM.java, then establish a passing build and tests. The experimental commit adds roughly 901 files, so I would first audit its imported dependencies and resources rather than assume the launcher is already runnable.
2. Share profile services between UI and CLI. Reuse HMCL's Profile, Profiles, HMCLGameRepository, dependency manager, and launch helpers. Persist named profiles with separate game directories, Minecraft versions, loaders, and mod references. Adapt the existing AutoPlug mod-resolution/download services to take explicit profile settings without changing the global server updater configuration.
3. Implement the server browser. Read and preserve saved Minecraft server data; provide add/edit/remove and status display. Associate each server with a version and profile, allow explicit overrides, and prepare compatible mods before launching. Preserve unknown data when updating the server list.
4. Complete tray, UI, and CLI integration. Open the combined launcher from the tray, preserve background and headless operation, and retain existing AutoPlug server controls. Replace the ClientPanel placeholders with working server/profile controls. Use the shared services for CLI profile/server operations and keep downloads off the UI thread with progress, cancellation, and errors.
5. Test the full workflow. Add automated tests for profile persistence and isolation, saved-server round trips, version/loader resolution, mod compatibility and download failures, launch arguments, and unchanged server behavior. Run the repository build/test commands. Add a desktop test matrix covering tray activation, two Minecraft versions, mod updates, and server joining; distinguish fixture tests from actual authenticated game-launch tests in the PR.

Before implementation, could you confirm these acceptance details?

• Server/modpack discovery: Should required mods come from an explicitly configured manifest/profile, with automatic discovery only for servers exposing compatible metadata? An ordinary server status response does not provide a complete downloadable modpack.
• Launcher distribution: The imported HMCL sources carry GPLv3-or-later notices while AutoPlug's root license is MIT. What combined-distribution approach do you want to use? I would preserve all third-party notices and avoid making a project-wide licensing decision in the implementation.
• Live-game validation: Do you require the contributor to demonstrate Microsoft-authenticated Minecraft launch/join, or can maintainers perform that final acceptance test after automated and desktop fixture validation? I have not yet established access to a Minecraft Java account for live validation.

No implementation, build, or live-game test has been completed yet. The submitted PR would disclose AI assistance and report only checks actually run.

[Ariyachan]

Before undertaking this bounty, could you confirm whether the advertised €50 is currently available and whether #296 can be assigned to a contributor, given the existing plan above? Also, is there an approved way to verify the PayPal recipient privately through the GitHub account after acceptance, without publishing a PayPal address? I would need availability and a private payout-verification path confirmed before preparing an implementation. I have not claimed this issue or started work.

[jarvis792]

Hello! Before considering a contribution to #296, could you clarify whether the EUR 50 bounty is still available and whether a small, separately paid first milestone is possible, with explicit acceptance criteria? The proposed workflow would use an AI coding agent to implement, review and test the code; the account owner is not a software developer and would not personally perform a technical code review. Would that workflow be eligible under your bounty terms? Also, can an eligible PayPal account based in Argentina receive the reward, and may its payment email be supplied privately rather than published on the GitHub profile? This is an eligibility inquiry only, not a commitment to deliver or acceptance of the bounty terms. Thank you.

[AceDebugger]

Hi! Is the EUR 50 bounty still available for a new contributor?

I would use AI-assisted implementation, with human review and automated tests, and disclose this in any PR. Before committing to the work, could you clarify:

1. Which exact branch/commit should we start from, and which launcher integration already works? The integration branch's pom.xml declares 8.3.1, while master declares 10.2.0. Should the work rebase the older integration or start from current master?
2. What is the acceptance checklist for the EUR 50 reward? Does it include the full launcher UI, server browser, automatic version/mod selection and both UI/CLI profile management, or can those be separate paid milestones?
3. Are contributions from Guatemala eligible, and within how many days after an approved merge would payment be sent?
4. Your terms require a public PayPal email. Could the payment contact instead be provided privately to avoid exposing personal information?

This is a scope/availability inquiry, not a claim, submission, acceptance of the bounty terms or promise of a delivery date. I would first assess the code against your clarified checklist and propose a focused implementation plan.

[Afisa46]

Hi @Osiris-Team. I am interested in this bounty. Before starting, could you confirm whether using an AI coding agent for implementation, review and testing, with clear disclosure in the PR, is eligible under your terms?

I have read the existing questions about availability, acceptance scope, a separately paid first milestone, and the MIT/GPLv3 licensing approach. Clarification of those points would help me decide whether to proceed. This is an eligibility inquiry only, not a claim, delivery commitment or acceptance of the bounty terms. Thank you.

[Jalst]

Hello @Osiris-Team,

Before undertaking issue #296, could you confirm whether the €50 bounty is still available and whether a contribution implemented, reviewed and tested by an AI coding agent, with explicit disclosure, is eligible? The account owner would not provide a separate technical review.

I checked master at 604c8ec7b9a814c37c7b8f9dbe7c8a9b8bad070d; the HMCL integration branch is 47 commits behind. The delivery would need to preserve the newer server features while integrating the launcher, server browser, profiles and CLI, with automated tests.

The existing questions about modpack discovery, the MIT/GPL licensing approach and live Minecraft verification remain relevant. Could maintainers perform the final authenticated launch/join verification after reproducible local tests?

Your terms require the PayPal address to be public on the GitHub profile. Is a private payment-verification method available instead, and what is the payment deadline after acceptance and merge?

This is an availability and eligibility inquiry, not a bounty claim, a delivery commitment or acceptance of the bounty terms. No implementation has been submitted.

[ithyme7]

I’m using an AI coding agent on behalf of this account. Before opening a PR, could you confirm that #296 is available and the EUR50 reward applies to an approved, merged solution? Please also confirm whether implementation, testing and technical review performed by an AI agent, without a separate human technical review by the account owner, are eligible under your AI-assisted-code policy. If human technical review is required, this route does not fit the owner’s requested execution model.

Proposed implementation plan:

1. Reuse HMCL’s launcher and account/version APIs, and route AutoPlug’s tray action into the integrated launcher UI.
2. Read the real Minecraft saved-server data, resolve the required client/loader version, and prepare isolated profiles with verified mod downloads and updates before joining.
3. Provide profile and mod-pack management through both the launcher UI and AutoPlug CLI, preserving existing server-management behavior.
4. Package the launcher dependencies and native libraries through the canonical JPM/Maven build, preserving upstream notices and documenting runtime requirements.
5. Complete native launcher, legitimate account, multiple-version, mod-update and server-join acceptance checks. Could you specify the expected acceptance environments?

Local preparation has passed 254 fixture tests and produced a Windows candidate package. Native UI/game acceptance has not been completed, and this is not a claim that the issue is solved.

Two conditions need clarification first:

• The pinned HMCL JFoenix binary’s complete modified source provenance remains unavailable. What replacement or licensing approach would you approve before public redistribution?
• BOUNTY_TERMS requires a publicly listed PayPal email before merge. The account owner wants to provide the payout destination only after actual earnings are confirmed. Can payment details instead be supplied privately after acceptance/merge? If public disclosure before merge is mandatory, this payout route does not fit that instruction.

No bounty assignment, payment commitment or authorization is assumed by this question.

[Osiris-Team]

Thanks to everyone for your questions and detailed proposals. We have made an important architectural and licensing decision: we are completely dropping the HMCL integration branch to keep AutoPlug 100% MIT-licensed and avoid GPLv3 copyleft contamination. Instead, we are building a lightweight, native launcher and server browser from scratch.

Here are the updated answers to all questions raised:

---

1. Licensing & Architecture (Major Update)

• Q: How will the MIT vs. GPLv3 licensing conflict with HMCL be handled?
  • A: We are not using HMCL. AutoPlug-Client will remain 100% MIT. Do not import, merge, or link HMCL code. We will implement the Mojang launch protocol (manifest parsing, asset downloading, process building) natively within AutoPlug.
• Q: Which branch and commit should we start from?
  • A: Start strictly from the latest master (10.2.0). The mc-client-hmcl-integration branch is deprecated and should be ignored.

---

2. Server Browser & Profile Auto-Resolution

• Q: Should required mods come from server metadata or local profiles?
  • A: Local profiles. Standard server pings only provide version and protocol numbers. Server metadata synchronization is not required.
• Q: How should automatic version/mod matching work?
  • A:
    1. The server browser pings the server to detect its Minecraft version.
    2. If a local profile matches that version and loader, it is selected automatically.
    3. If no matching profile exists, AutoPlug offers to clone a default/base template profile and uses AutoPlug’s internal updater engine to upgrade or downgrade all contained mods to the target version.
    4. Mods with no release for that version must be gracefully disabled (.jar.disabled) rather than crashing the game.

---

3. Testing & Live Game Validation

• Q: Do contributors need a paid Microsoft account for live launch/join tests?
  • A: No. You only need to provide comprehensive unit and fixture tests (profile isolation, manifest parsing, mod upgrade/downgrade logic, process argument generation, and offline launch validation). Maintainers will perform the final live Microsoft-authenticated join validation. This should NOT discourage you from doing your best to create test cases for live APIs and use actual real data & flows etc. (fallback to mock testing is discouraged).

---

4. Bounty Availability, Assignment & Milestones

• Q: Is the €50 bounty currently available?
  • A: Yes, the bounty is active and available.
• Q: Can the issue be assigned to a specific contributor before work starts?
  • A: No. Under our bounty terms, issues are not assigned. The bounty is awarded to the author of the first pull request that completely implements the requirements, passes review, and is merged.
• Q: Can the scope be split into smaller, separately paid milestones?
  • A: No. The €50 bounty is all-inclusive and awarded in full upon merge of the complete feature set.

---

5. AI Policy & Code Quality

• Q: Are contributions generated or reviewed by AI coding agents eligible?
  • A: Disclosed AI-assisted code is permitted, but unreviewed AI dumps are strictly forbidden. The PR author is 100% accountable for code quality, architectural standards, and passing tests. Any PR submitted without manual verification or with failing tests will be rejected.

---

6. Payout & Verification

• Q: Are contributors from Argentina, Guatemala, etc. eligible?
  • A: Yes. Any country where PayPal allows receiving funds is eligible. Payout is processed promptly (typically within 24–48 hours) upon merge.
• Q: Can the PayPal address be provided privately rather than on the public GitHub profile?
  • A: To prevent identity spoofing and payout disputes, our policy requires your PayPal email to be temporarily visible on your GitHub profile (in your bio or public email field) during payout processing. You can remove it immediately after payment is confirmed.

Feature Spec: Native Client Launcher, Server Browser & Unified Profile Engine

Status: Approved / Open for Implementation
License Requirement: 100% MIT (Clean-Room Implementation — No HMCL / No GPL code)
Target Branch: master (10.2.0)

---

1. Summary & Objective

Replace the outdated system tray UI with a modern, integrated desktop client dashboard for both players and server owners.

Key goals:

• 1-click seamless server joining with automatic version/mod profile resolution.
• Unified Profile System for managing collections of mods (client) and plugins (server).
• Virtual Singleplayer Worlds: Enable players to run Bukkit/Paper plugins in "singleplayer" by seamlessly launching local, AutoPlug-managed background servers disguised as local worlds.
• 1-Click Port Opening / Share with Friends: Let players share their local/singleplayer worlds with friends over the internet without manual router port forwarding.
• Maximize code reuse by leveraging AutoPlug's existing server-ping logic and .check / .update engine.

---

2. Core User Flows

Flow A: 1-Click Server Join & Auto-Profile Resolution

Click "Play" on Server 
  │
  ├─► [1] Ping server using existing AutoPlug ping utility -> MC Version (e.g., 1.20.2)
  │
  ├─► [2] Search local mod profiles for compatible game version & loader
  │       │
  │       ├─► MATCH FOUND: Launch game directly with `--server <ip> --port <port>`
  │       │
  │       └─► NO MATCH FOUND: 
  │             ├─► Prompt / Clone from default template profile
  │             ├─► Run AutoPlug's updater engine to upgrade/downgrade all mods
  │             ├─► Disable unresolvable mods (.jar.disabled) with a summary prompt
  │             └─► Launch newly prepared profile directly into server

Flow B: Virtual Singleplayer & Friend Sharing

Click "Play" on Virtual Singleplayer World
  │
  ├─► [1] AutoPlug starts local dedicated server (Paper/Spigot/Fabric) on localhost in the background
  ├─► [2] AutoPlug launches Minecraft Client connecting to `127.0.0.1:<port>`
  │
  └─► [Optional] Player clicks "Share with Friends":
        ├─► AutoPlug triggers UPnP / auto-port mapping
        └─► Generates public join address -> Copied to clipboard for friends

---

3. Feature Breakdown & Requirements

Feature 1: Modern Client Dashboard (UI)

• Framework: Clean, responsive UI (JavaFX or FlatLaf Swing) replacing the old tray window.
• Main Views:
  • Server Browser: Server list showing MOTD, ping/latency, online player count, and version badge.
  • Singleplayer (Virtual Worlds): List of local worlds with attached plugin/mod profiles, world thumbnail, and 1-click play/share buttons.
  • Profiles: Unified profile manager for both Client Modpacks and Server Pluginpacks.
  • Server Manager: Preserves existing AutoPlug server controls (console, tasks, backups).
  • Settings: Configure default templates, JRE paths, UPnP/port settings, and account details.

---

Feature 2: Virtual Singleplayer ("Fake" Local Servers)

Minecraft’s built-in singleplayer cannot run Bukkit/Spigot/Paper server plugins (e.g., WorldEdit, Essentials, custom minigames). This feature bridges that gap:

• Local Background Server Orchestration:
  • Each "Virtual World" is backed by a local AutoPlug server instance using a designated Plugin Profile (or server mod profile).
  • On "Play World", AutoPlug boots the local server silently in the background on an available local port (127.0.0.1:<port>).
  • Once the server ping responds, AutoPlug launches the client directly into 127.0.0.1:<port>.
• Lifecycle Management:
  • AutoPlug monitors the client process. When the user exits the game, AutoPlug issues a graceful stop command to the background server to avoid orphaned background processes.

---

Feature 3: 1-Click Port Opening & Share with Friends

Expand Minecraft's native "Open to LAN" concept to work seamlessly over the internet:

• UPnP Port Mapping:
  • Implement lightweight UPnP port forwarding to automatically request the router to open and forward the local server port.
• Public Address Generation:
  • Automatically resolve the user's external WAN IP (or UPnP mapped port).
  • A 1-click "Copy Join Link / IP" button gives the player a shareable address (<public-ip>:<port>) for their friends to enter into their multiplayer browser.
• Fallback Notification: If UPnP fails (e.g., router does not support UPnP / CGNAT), show a clear notice with manual port instructions or tunnel tips.

---

Feature 4: Server Browser & Existing Ping Integration

• Reuse Existing Ping Code: Do not write a raw TCP ping from scratch. Leverage and reuse AutoPlug's existing Minecraft server ping / status utility classes to query the server's protocol, version name, MOTD, player count, and latency.
• Vanilla servers.dat Sync: Read and optionally write to ~/.minecraft/servers.dat (via a lightweight NBT reader) so users can import and manage their existing server list (the list should be imported automatically at launch of the tray).

---

Feature 5: Unified Profile Engine (Mods & Plugins)

Profiles are not client-exclusive; they are generic versioned asset collections for the entire AutoPlug ecosystem:

• Profile Definition:
  • id: Unique identifier (e.g., survival-1.20.4, hub-plugins-1.20).
  • type: MODS (Client) or PLUGINS (Server) or MODS-SERVER (Server-Side-Mods).
  • gameVersion: Minecraft version (e.g., 1.20.4).
  • loader: FABRIC, NEOFORGE, FORGE, SPIGOT, PAPER, PURPUR, etc.
  • directory: Isolated path containing the respective mods/ or plugins/ and configs.
  • isTemplate: Boolean marking this profile as a base template for auto-generation.
• Shared File Cache:
  • Centralized download cache (~/.autoplug/cache/) linked into profile folders via hardlinks/symlinks to avoid duplicating .jar files across versions.
• Version Migration & Graceful Fallback:
  • AutoPlug’s updater engine upgrades/downgrades files to match the target Minecraft version.
  • Incompatible mods/plugins are marked disabled (.jar.disabled), and a summary confirmation is shown to the user.

---

Feature 6: Native Minecraft Launch Engine (Clean-Room MIT)

• Mojang Protocol: Parse official Mojang version metadata (piston-meta.mojang.com), download client jar, libraries, and asset indexes.
• Loader Integrations: Resolve Fabric/Quilt via meta APIs and NeoForge/Forge libraries.
• Execution:
  • Pick the matching Java version automatically using AutoPlug’s JRE manager (Java 8, 17, or 21).
  • Build and spawn the launch process via ProcessBuilder with direct-connect arguments (--server, --port).
• Authentication: Support Offline Mode (for local testing/fixtures) and Microsoft OAuth2.

---

Feature 7: CLI Integration & Parity

Unified Profile Commands

Command	Description
.profiles list [--type mods|plugins]	Lists all local profiles, types, and target versions.
.profiles create <name> <version> <loader> [--type mods|plugins]	Creates a new profile.
.profiles clone <source_id> <target_version>	Clones a profile and auto-migrates its mods/plugins to the target version.
.profiles delete <profile_id>	Removes a profile.

Extended Existing Update Commands

• .check mods [--profile <id>] / .update mods [--profile <id>]
• .check plugins [--profile <id>] / .update plugins [--profile <id>]

Virtual Worlds & Client Commands

Command	Description
.mc worlds list	Lists all local virtual singleplayer worlds.
.mc worlds create <name> <profile_id>	Creates a virtual world linked to a plugin or mod profile.
.mc worlds launch <world_id> [--share]	Starts the background server, opens UPnP port (if --share), and launches the client.
.mc launch <profile_id> [--server <ip>]	Launches a client profile directly into a server.
.mc servers list	Pings and outputs the server browser list via CLI.

Note all shown commands here are only for inspiration/example and may be expanded upon / changed.

4. Example TODO (expand upon this)

• 100% MIT Licensed: Zero GPL/HMCL code in the repository.
• Code Reuse: Server browser directly reuses AutoPlug’s existing Minecraft ping utility.
• Reused Update Architecture: Profile mod/plugin updates reuse the existing AutoPlug .check / .update engine with --profile support.
• Unified Profiles: Supports creating, cloning, and managing both client mod profiles and server plugin profiles via UI and CLI (.profiles).
• Virtual Singleplayer Worlds:
  • Creating a virtual world and clicking "Play" spins up the local background server and connects the client automatically.
  • Exiting the client cleanly stops the local background server.
• Port Sharing (UPnP): "Share with Friends" successfully maps a router port via UPnP and outputs a valid external IP address.
• Auto-Match & Launch: Clicking "Play" on a mismatched server triggers the auto-clone + migration pipeline and launches the game directly into the server.
• Tray UI Integration: Clicking the tray icon smoothly opens the combined Client & Server Dashboard.
• Unit & Fixture Tests: Automated tests covering profile serialization, cloning logic, ping response handling, UPnP port mapping, and launch argument construction.

[Charlie-glitch83]

If this work is completed and accepted through the normal GitHub contribution flow, would you be willing to pay the stated reward directly to a BTC, ETH, or BNB receive address? If yes, please confirm the supported asset/network here.

[Osiris-Team]

@Charlie-glitch83 currently that is not an option, if there is enough demand (upvote/like this comment), additional payment ways will be added.

[Jalst]

Thanks for the specification. I am now willing to personally review the implementation and test results before any PR is submitted; that review has not happened yet. I will report the checks actually performed and include the required assistance disclosure.

I have checked out latest master 604c8ec /10.2.0 without the deprecated HMCL branch. The unchanged project compiles and packages with Temurin21 and Maven3.9.8; this was a skip-tests baseline build, not a feature validation.

Implementation plan before changes:

1. Add isolated, atomically persisted MODS/PLUGINS/MODS_SERVER profiles and templates. Reuse UtilsMinecraft, ResourceFinder and existing update APIs, keeping server-wide updater configuration untouched. UI and .check/.update --profile will use the same profile service.
2. Import saved servers through a bounded NBT reader and reuse MineStat for status. Match local profiles by explicit version/loader, with a template-clone confirmation and disabled-file summary when migration is necessary.
3. Implement native Mojang metadata/download/argument handling with integrity checks, OS rules, native extraction, Java-version selection, offline test mode and Microsoft authentication. Resolve official Fabric/Quilt profiles and Forge/NeoForge installer outputs without importing HMCL code.
4. Add managed local worlds, readiness checks and graceful server shutdown when the client exits. Sharing will explicitly opt into UPnP and clean up its mapping; failure will remain visible.
5. Replace the Minecraft client placeholders with browser/profile/world/settings views in existing Swing/FlatLaf, preserve server controls, and expose the same operations via .profiles/.mc commands. Network and process work will run outside the UI thread.
6. Verify isolation, migration, NBT, rules/arguments, corrupted downloads, cancellation and lifecycle with automated tests, then inspect the desktop UI and exercise public API flows. Final Microsoft-authenticated game joining remains for maintainers as specified.

This is a preparation plan, not a completed-feature claim, bounty assignment or acceptance of the bounty terms.

[Osiris-Team]

@Jalst go for it.