eXtended NSMCL: A more feature-rich unofficial MInecraft launcher that uses NSMCL as its core
  • C 99%
  • Shell 1%
Find a file
2026-11-19 06:00:12 -03:00
include 0.1.2: export/import instances 2026-11-19 06:00:12 -03:00
nsmcl@07d792da58 reupload working it 2026-11-06 00:13:19 -03:00
src 0.1.2: export/import instances 2026-11-19 06:00:12 -03:00
.gitignore reupload working it 2026-11-06 00:13:19 -03:00
.gitmodules reupload working it 2026-11-06 00:13:19 -03:00
build.bash 0.1.2: export/import instances 2026-11-19 06:00:12 -03:00
libxnsmcl.a 0.1.2: export/import instances 2026-11-19 06:00:12 -03:00
LICENSE reupload working it 2026-11-06 00:13:19 -03:00
README.md 0.1.2: export/import instances 2026-11-19 06:00:12 -03:00

XNSMCL: eXtended NSMCL

The "launcher-like" features that don't belong in nsmcl, built on top of it: Microsoft login, Modrinth mods, (next) modpack import and CurseForge.

NSMCL stays the tiny "build the command and run java" core. xnsmcl links it as libnsmcl.a and calls one function, nsmcl_launch().

xnsmcl launch [--offline|--online] [-a ACCOUNT] [--name N] [-v] <instance>
xnsmcl <instance>                       # shorthand, same one-word UX as nsmcl
xnsmcl login                            # Microsoft device-code sign-in
xnsmcl accounts [list | use <acct> | logout <acct>]
xnsmcl create [name] [--mc V] [--loader fabric|quilt|forge|neoforge] [--loader-version V] [--java PATH] [--no-prepare]
xnsmcl create --list [--loader L] [--mc V] [--all]
xnsmcl versions [--releases] [--types] [--loader L [--mc V]]   # one per line: xnsmcl versions | fzf
xnsmcl prepare [--plan] [--verify] [-j N] [-q] <instance>   # download libraries, assets, client jar
xnsmcl fetch-runtime [--list] [--platform P] <component>   # Mojang's Java runtime, by hand
xnsmcl instance info|copy|rename|delete|set|unset <instance> ...
xnsmcl config [show | init | use-xnsmcl-folder on|off | use-prism on|off | root <dir>|default | auto-prepare on|off | get|set <section>.<key> [value]]
xnsmcl import <file.zip|file.mrpack|https-url> [--name N] [--no-prepare]
xnsmcl export <instance> [prism|modrinth] [-o FILE] [--all] [--force]
xnsmcl instances                        # on a pipe: name<TAB>details[<TAB>[prism]]
xnsmcl -in | --launch-stdin [opts]       # launch the instance named on stdin: xnsmcl instances | fzf | xnsmcl -in
xnsmcl mod -i <inst> search <query>
xnsmcl mod -i <inst> add <slug>...      # + required dependencies, sha512-verified
xnsmcl mod -i <inst> remove [--prune] <slug>...
xnsmcl mod -i <inst> list | update [--check] | sync

<instance> = a name under xnsmcl's data folder or (if enabled) PrismLauncher's instances/, or any path containing a /.

Data folder and PrismLauncher compatibility

xnsmcl keeps its own root (XNSMCL_ROOT, or config root, default: the XDG data dir) using PrismLauncher's on-disk format (instances/, libraries/, assets/, meta/), so the two can share instances. PrismLauncher's instances are included by default: instances, launch, prepare, mod, instance ... all see both roots (Prism's are tagged [prism]; if a name exists in both, xnsmcl's own wins). config use-prism off (or XNSMCL_USE_PRISM=0) turns that off. An instance always uses the libraries, assets and Java of the root it lives in; new instances (create) go into xnsmcl's root.

Configuration: ~/.config/xnsmcl/xnsmcl.ini

[instances]
use_xnsmcl_folder=True
use_prism_folder_also=True

[mods_sources]
default=Modrinth
use_modrinth=True
use_curseforge=False

[export]
; prism or modrinth: what `export` does when no format is given
export_format=prism

(XDG_CONFIG_HOME is honoured; XNSMCL_CONFIG=/path points elsewhere. xnsmcl config init writes a commented copy, config show prints what is in effect, config set <section>.<key> <value> edits a key without touching your comments.) Optional extras: [instances] root=/abs/dir and [launch] auto_prepare=False. Section and key names are case-insensitive, booleans are True/False (also yes/no, on/off, 1/0). Environment variables (XNSMCL_ROOT, XNSMCL_USE_PRISM, XNSMCL_AUTO_PREPARE...) override the file.

  • use_xnsmcl_folder=False leaves xnsmcl's own folder out; create and Java runtimes then go into Prism's. With both folders off xnsmcl warns and uses its own.
  • use_curseforge=True is accepted but CurseForge isn't implemented yet: mod says so and uses Modrinth. use_modrinth=False makes the mod commands refuse.

Mods

mod list shows what is really in <instance>/minecraft/mods/ (and one level of version subfolders): what xnsmcl installed, flagged [CHANGED] if the jar no longer matches the lock, [MISSING] or [disabled] (.jar.disabled); and everything else (jars dropped in by hand or by a modpack), identified from the jar itself (fabric.mod.json, quilt.mod.json, mods.toml, 1.7.10-style mcmod.info; a ${file.jarVersion} version is taken from the manifest), or listed by file name if the jar says nothing. It never needs the network.

create

xnsmcl create my-fabric --mc 1.20.1 --loader fabric writes a Prism-format instance (instance.cfg, mmc-pack.json, minecraft/) and runs prepare on it. Components come from Prism's meta server exactly as Prism resolves them: the newest release if --mc is omitted, the LWJGL the Minecraft version suggests, the recommended loader build that fits that Minecraft (Fabric/Quilt also pull in their intermediary mappings), and everything is ordered by the meta's order field. A loader version built for another Minecraft is refused. The instance is built in a temporary directory and renamed into place, and an existing instance is never overwritten. create --pick opens fzf over every Minecraft version (and over the loader's builds when --loader is given); xnsmcl versions prints the same lists for any other picker. --list shows Minecraft releases (--all: snapshots), or loader versions for --mc. create does not make it launchable beyond what nsmcl supports; Forge/NeoForge instances are created correctly but launching them depends on nsmcl handling their arguments.

Instance management

xnsmcl instance info   <instance>
xnsmcl instance copy   <instance> <new-name>
xnsmcl instance rename <instance> <new-name>
xnsmcl instance delete <instance> [--yes]
xnsmcl instance set    <instance> <setting> <value>   # java, java-args, max-memory, min-memory, width, height, maximized
xnsmcl instance unset  <instance> <setting>

Settings are stored as Prism does (MaxMemAlloc + OverrideMemory=true, ...), so Prism sees them too, and the rest of instance.cfg is left as it was. copy and rename keep name= in sync; delete asks you to type the name unless --yes, only ever touches a directory directly inside an instances/ folder, and never follows symlinks. copy/create build in a temporary directory and rename into place.

import / export

import takes a local path or an https:// URL and recognises the format by content:

  • a PrismLauncher instance export (.zip with instance.cfg + mmc-pack.json, at the top or inside one folder) is unpacked as an instance;
  • a Modrinth modpack (.mrpack, or a .zip with modrinth.index.json) creates an instance for the pack's Minecraft + loader version, downloads every listed file (sha512/sha1-verified, only from cdn.modrinth.com, github.com, raw.githubusercontent.com, gitlab.com, as the format requires), skips files marked client: unsupported, then applies overrides/ and client-overrides/. Imported mods are not in xnsmcl.lock.json, so mod list shows them as "not installed by xnsmcl";
  • CurseForge (manifest.json, curseforge://) and Technic packs are recognised and refused for now.

Archives are treated as hostile: entry names with .., absolute paths, backslashes or control characters refuse the whole pack before anything is written; sizes are capped; CRCs are checked; nothing is ever written through a symlink; a failed import leaves no instance behind. The instance is named after the pack (or --name); a taken name gets (2), (3)... unless you gave --name, which then errors.

export <instance> [format] writes <name>.zip / <name>.mrpack in the current folder (or -o FILE; it won't overwrite without --force). The instance may be a name, a path, or a whole line of xnsmcl instances (so xnsmcl export "$(xnsmcl instances | fzf)" works). Logs, caches, saves/ and screenshots/ are left out unless --all; symlinks never go in.

  • prism: the instance folder as a zip, which PrismLauncher imports as it is.
  • modrinth: mods installed with xnsmcl mod whose jar still matches the lock become download links with sha1 + sha512 + size; everything else (hand-added jars, configs, resource packs) is embedded under overrides/. --pack-version V sets versionId (default 1.0.0).

Options

Options (and their values) can go anywhere, before or after the command or subcommand, and values may be written -i x, -ix, --instance x or --instance=x: xnsmcl -i foo mod add sodium, xnsmcl mod add -i foo sodium and xnsmcl mod add sodium --instance=foo are the same command.

Java

prepare also makes sure the instance can run: if nsmcl finds no suitable Java (the instance's java setting, <root>/java/<name>, JAVA_HOME, /usr/lib/jvm), it downloads the Mojang runtime the instance's meta names (jre-legacy = Java 8 for old versions, java-runtime-gamma = 17, ...) into <root>/java/<name>/, where nsmcl looks first. Old Minecraft/Forge versions crash on newer Java (ClassCastException ... URLClassLoader), which is exactly what this prevents. An instance with its own java setting never triggers a download. launch does the same through its automatic prepare.

xnsmcl fetch-runtime [--list] [--platform P] <component> installs a specific runtime by hand (resumable, sha1-verified; manifest paths and symlinks are checked to stay inside <root>/java/<component>/). Mojang publishes no Linux ARM64 build; there you install a JDK yourself and point the instance at it.

prepare

Reads what nsmcl says an instance needs and downloads what's missing: meta from Prism's meta server, libraries/natives/client jar from the URLs in the component JSON, assets from Mojang's resource server. Parallel, written to .part, verified (size by default, sha1 with --verify), then renamed; transient errors retry with backoff, 4xx fail at once. HTTPS only. launch runs it automatically unless --offline, --no-prepare, or config auto-prepare off; a failed download warns but never blocks the launch. --plan shows what would be fetched. Tests redirect hosts with XNSMCL_URL_MAP="from=to,..." (which also allows plain http).

Build

nsmcl is a git submodule (and it has its own, common_utils), so clone recursively:

git clone --recurse-submodules <url> xnsmcl && cd xnsmcl
# forgot the flag?  git submodule update --init --recursive
./build.bash          # -> ./xnsmcl and libxnsmcl.a (needs: cc, pkg-config, jansson, libcurl, libcrypto, zlib)
./build.bash lib      # only libxnsmcl.a
./build.bash test     # ASan+UBSan build + end-to-end tests (needs python3 for the mock server)

As a library

Everything except src/main.c is libxnsmcl.a; main.c only picks the command and calls cmd_*(). A front end (the planned graphical app) links libxnsmcl.a, then libnsmcl.a, then jansson, libcurl, libcrypto and zlib, and includes include/xnsmcl.h. The pieces that are already GUI-shaped: the download pool is polled (dl_step() from an idle callback, progress through a callback), and instance creation is xn_create_instance(). Known limit: much of the code still reports errors with xn_err() on stderr and some helpers call xn_die(), which exits the process; a GUI needs those turned into return codes and a message callback first (see xn_die users). The generic download pool lives in common_utils (download.h) and has no xnsmcl dependencies.

Design

The Prism instance directory is the contract. xnsmcl never invents its own instance format: it reads mmc-pack.json / instance.cfg and writes mods into minecraft/mods/, so everything it touches still opens in Prism and still launches with plain nsmcl. Extra state is two small files: ~/.local/share/xnsmcl/accounts.json (0600) and <instance>/xnsmcl.lock.json.

A launch is never blocked by authentication — the reason nsmcl exists. launch is best-effort: valid token → use it; expired → refresh (the Microsoft refresh token rotates and the new one is saved immediately, even if a later step fails); can't (offline, revoked, 5xx, no licence) → warn and start offline using your cached name/uuid. Offline fallback with no network takes ~40 ms (connect timeout is 6 s only if packets are silently dropped). --online makes failure fatal, --offline skips the network.

Mods are planned, then installed. mod add resolves the whole dependency tree first (required deps, pinned dependency versions, incompatible in both directions) and only then downloads; a conflict or missing build aborts with the mods folder untouched. Downloads go to *.part, are checked against the sha512 Modrinth publishes, and only then renamed. File names from the server are rejected if they contain a path separator or start with a dot. Jars xnsmcl didn't install are never modified or deleted.

Test/dev hooks: XNSMCL_{MS_LOGIN,XBL,XSTS,MC_API,MODRINTH}_URL redirect the services (the test-suite uses them); XNSMCL_PRISM_ROOT, XNSMCL_HOME, XNSMCL_USER_AGENT (Modrinth asks for a UA with contact info, e.g. xnsmcl/0.1.0 (you@example.com)).

What has and hasn't been verified

  • Verified: 70 end-to-end checks (tests/run_tests.sh) under AddressSanitizer/UBSan with zero reports, against tests/mock_server.py, using real Prism meta JSON for the launch fixtures. Two deliberate bugs (no hash check, no filename check) were injected and caught.
  • Not verified: any real service. The mock was written from the documented protocol; it proves the client is self-consistent and sends the documented request shapes, not that Microsoft / Xbox / Mojang / Modrinth answer exactly like that today. The first real xnsmcl login is the real test (and needs the approved client ID).
  • Not run: an actual Minecraft launch (the tests use a fake java that records its arguments).

Next features:

  • instance export
  • instance import