fix: Support --quickPlayMultiplayer options for newer Minecraft versions (#321)

* Initial plan

* Initial exploration and planning for quickPlayMultiplayer support

Co-authored-by: ci010 <[email protected]>

* Implement quickPlayMultiplayer support for Minecraft launcher

- Add quickPlayMultiplayer option to LaunchOption interface
- Update generateArguments to handle quickPlayMultiplayer over legacy server/port options
- Add createQuickPlayMultiplayer helper function for easy migration
- Add comprehensive tests for new functionality
- Maintain backward compatibility with existing server option

Co-authored-by: ci010 <[email protected]>

* Add documentation for quickPlayMultiplayer feature

- Update README with usage examples for quickPlayMultiplayer option
- Include helper function documentation
- Show backward compatibility examples
- Explain precedence when both options are provided

Co-authored-by: ci010 <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: ci010 <[email protected]>

Author: Copilot

packages/core/README.md

@@ -66,3 +66,41 @@ Detach from the parent process. So your launcher's exit/crash won't affact the M
 ```ts
 const proc: Promise<ChildProcess> = Launcher.launch({ gamePath, javaPath, version, extraExecOption: { detached: true } });
 ```
+
+#### Launching with Server Connection
+
+For newer Minecraft versions, use the `quickPlayMultiplayer` option to directly connect to a server:
+
+```ts
+import { launch, createQuickPlayMultiplayer } from "@xmcl/core"
+
+// Option 1: Use quickPlayMultiplayer directly
+const proc = launch({ 
+  gamePath, 
+  javaPath, 
+  version,
+  quickPlayMultiplayer: 'play.hypixel.net:25565'
+});
+
+// Option 2: Use helper function
+const proc = launch({ 
+  gamePath, 
+  javaPath, 
+  version,
+  quickPlayMultiplayer: createQuickPlayMultiplayer('mc.example.com', 8080)
+});
+```
+
+For backward compatibility, the legacy `server` option is still supported:
+
+```ts
+// Legacy server option (still works)
+const proc = launch({ 
+  gamePath, 
+  javaPath, 
+  version,
+  server: { ip: 'play.hypixel.net', port: 25565 }
+});
+```
+
+**Note:** When both `quickPlayMultiplayer` and `server` options are provided, `quickPlayMultiplayer` takes precedence.

packages/core/launch.test.ts

@@ -2,7 +2,7 @@ import assert from 'assert'
 import { spawnSync } from 'child_process'
 import { EOL } from 'os'
 import * as path from 'path'
-import { DEFAULT_EXTRA_JVM_ARGS, generateArguments, generateArgumentsServer } from './launch'
+import { DEFAULT_EXTRA_JVM_ARGS, generateArguments, generateArgumentsServer, createQuickPlayMultiplayer } from './launch'
 import { describe, test, expect } from 'vitest'
 
 function getJavaVersion(javaPath: string) {
@@ -281,5 +281,48 @@ describe('Launcher', () => {
       expect(args[args.indexOf('--server') + 1]).toEqual(server.ip)
       expect(args[args.indexOf('--port') + 1]).toEqual(server.port.toString())
     })
+    test('should generate correct command with quickPlayMultiplayer', async ({ mock }) => {
+      const args = await generateArguments({
+        version: '1.14.4', gamePath: mock, javaPath: '/test/java', quickPlayMultiplayer: '127.0.0.1:25565',
+      })
+      expect(args[args.indexOf('--quickPlayMultiplayer') + 1]).toEqual('127.0.0.1:25565')
+      // Should not contain old server arguments
+      expect(args.indexOf('--server')).toBe(-1)
+      expect(args.indexOf('--port')).toBe(-1)
+    })
+    test('should prefer quickPlayMultiplayer over server option', async ({ mock }) => {
+      const server = {
+        ip: '192.168.1.1',
+        port: 25565,
+      }
+      const args = await generateArguments({
+        version: '1.14.4', 
+        gamePath: mock, 
+        javaPath: '/test/java', 
+        server,
+        quickPlayMultiplayer: '127.0.0.1:25565',
+      })
+      expect(args[args.indexOf('--quickPlayMultiplayer') + 1]).toEqual('127.0.0.1:25565')
+      // Should not contain old server arguments when quickPlayMultiplayer is present
+      expect(args.indexOf('--server')).toBe(-1)
+      expect(args.indexOf('--port')).toBe(-1)
+    })
+  })
+
+  describe('#createQuickPlayMultiplayer', () => {
+    test('should create quickPlayMultiplayer string with IP only', () => {
+      const result = createQuickPlayMultiplayer('127.0.0.1')
+      expect(result).toEqual('127.0.0.1')
+    })
+
+    test('should create quickPlayMultiplayer string with IP and port', () => {
+      const result = createQuickPlayMultiplayer('127.0.0.1', 25565)
+      expect(result).toEqual('127.0.0.1:25565')
+    })
+
+    test('should create quickPlayMultiplayer string with custom port', () => {
+      const result = createQuickPlayMultiplayer('play.example.com', 8080)
+      expect(result).toEqual('play.example.com:8080')
+    })
   })
 })

packages/core/launch.ts

@@ -106,6 +106,11 @@ export interface LaunchOption {
    * Directly launch to a server
    */
   server?: { ip: string; port?: number }
+  /**
+   * Directly launch to a server using quickPlayMultiplayer option (for newer Minecraft versions)
+   * This will use --quickPlayMultiplayer instead of --server and --port
+   */
+  quickPlayMultiplayer?: string
   /**
    * Resolution. This will add --height & --width or --fullscreen to the java arguments
    */
@@ -805,7 +810,9 @@ export async function generateArguments(options: LaunchOption) {
   if (options.extraMCArgs) {
     cmd.push(...options.extraMCArgs)
   }
-  if (options.server) {
+  if (options.quickPlayMultiplayer) {
+    cmd.push('--quickPlayMultiplayer', options.quickPlayMultiplayer)
+  } else if (options.server) {
     cmd.push('--server', options.server.ip)
     if (options.server.port) {
       cmd.push('--port', options.server.port.toString())
@@ -854,3 +861,13 @@ function normalizeArguments(args: Version.LaunchArgument[], platform: Platform,
     return result
   }, [])
 }
+
+/**
+ * Create a quickPlayMultiplayer string from server IP and optional port
+ * @param ip The server IP address
+ * @param port The server port (optional, defaults to 25565 if not specified)
+ * @returns A formatted string for quickPlayMultiplayer option
+ */
+export function createQuickPlayMultiplayer(ip: string, port?: number): string {
+  return port ? `${ip}:${port}` : ip
+}