Minecraft Launcher Core Node

Minecraft Launcher Core is a collection of specialized packages designed to provide the necessary functionality to build a Minecraft launcher. Most packages are optimized for the Electron environment.

Key functional areas include:

• Launching & Installation: @xmcl/core (launching) and @xmcl/installer (installing).
• Authentication & Users: @xmcl/user (authentication and skins).
• Modding & APIs: @xmcl/mod-parser (parsing mod files), @xmcl/curseforge (Curseforge API), and @xmcl/modrinth (Modrinth API).
• Data Parsing: @xmcl/nbt (NBT), @xmcl/resourcepack (resource packs), @xmcl/game-data (level/server data), and @xmcl/text-component (Minecraft text).
• Networking & Files: @xmcl/client (server pinging), @xmcl/file-transfer (high-performance downloads), and @xmcl/system (filesystem middleware).

The @xmcl/installer module provides specialized functions to install Minecraft clients, libraries, and assets. It is designed for efficiency and reliability using a "diagnose-first" pattern, which verifies existing files on disk before attempting downloads to skip already-valid files.

Key capabilities include:

• Smart Resume: Automatically continues interrupted installations by skipping valid files.
• Efficient Downloads: Uses parallel checksum validation and downloads.
• AbortSignal Support: Allows canceling ongoing installation operations using standard web AbortSignal.
• Progress Tracking: Includes a built-in system to monitor installation progress.
• Browser Compatibility: Uses fetch-based APIs, making it suitable for browser environments.

To use @xmcl/game-data effectively, understand these two core Minecraft data structures:

Level

Represents the metadata of a Minecraft save (e.g., world name, creation time). In this library, this is represented by the LevelDataFrame type.

Region

Minecraft block data is stored in .mca region files.

• Structure: One region contains 16 sections. Each section contains 16x16x16 blockstates, biomes, entities, and tile entities.
• Version Differences:
  • < 1.13: NBT data stores global blockstate IDs in Data and Blocks fields.
  • >= 1.13: NBT data stores local blockstate IDs in BlockStates and a mapping to convert local IDs to BlockState objects.
• In-Chunk Coordinates: A chunk (section) contains 4096 blockstates indexed from [0, 4096). The coordinate mapping is: (x, y, z) -> y << 8 | z << 4 | x.

The package is designed with a functional approach and does not bundle heavy implementations for system-level tasks. Instead, it relies on interface-based abstractions. To use the package, you must provide implementations for the following interfaces:

• Logger: For logging operations.
• ChecksumWorker: For computing file hashes.
• ResourceManager: For managing resource metadata.
• FileSystem: For file system operations.

This design ensures the package remains framework-agnostic and can be integrated into any environment (Node.js, browser, etc.) by providing the appropriate adapters.

The package provides built-in support for parsing and managing the following instance formats:

• MultiMC: Supports MultiMC and PolyMC launcher formats.
• Modrinth: Supports Modrinth App instances.
• CurseForge: Supports CurseForge launcher instances.
• Vanilla: Supports official Minecraft launcher profiles.

For browser-based environments, use the @xmcl/installer/browser entrypoint. These functions use the standard fetch API instead of Node.js-specific networking modules. You must provide a fetch implementation (e.g., window.fetch).

import { getVersionList, getForgeVersionList } from "@xmcl/installer/browser";

const versions = await getVersionList({
  fetch: window.fetch.bind(window)
});

The @xmcl/system module provides a unified API to perform read operations on both local directories and ZIP files. It is designed to work in both Node.js and browser environments, allowing you to treat a directory or a compressed ZIP archive as a single filesystem.

Use openFileSystem(path) to obtain a filesystem instance. Once opened, you can use methods like readFile to access files within that path, regardless of whether the source is a raw directory or a .zip file.

import { openFileSystem } from "@xmcl/system";

// Accessing a directory
let filePath = "/path/to/dir/"
const fs = await openFileSystem(filePath);
fs.readFile("a.txt"); // reads /path/to/dir/a.txt

// Accessing a ZIP file
let zipPath = "/path/to/file.zip"
const fsZip = await openFileSystem(zipPath);
fsZip.readFile("a.txt"); // reads a.txt inside the zip file

The project is written in TypeScript and built using esbuild, producing both esm and commonjs versions. Many modules also include a specific browser build.

Bundler Configuration

Modern bundlers should automatically resolve the module field in package.json to use the ESM version.

• esbuild & vite: These work out-of-the-box with the current package.json configuration.
• webpack: If using Webpack, you may need to configure resolve.mainFields to ensure the bundler selects the preferred field (e.g., module for ESM).

The @xmcl/bytebuffer module provides functions for handling byte buffers, ported from bytebuffer.js. It is designed to be compatible with both Node.js and browser environments by using DataView. It supports ESM (mjs) and uses BigInt to represent the long type.

npm install @xmcl/bytebuffer