- C 99%
- Shell 1%
| include | ||
| nsmcl@07d792da58 | ||
| src | ||
| .gitignore | ||
| .gitmodules | ||
| build.bash | ||
| libxnsmcl.a | ||
| LICENSE | ||
| README.md | ||
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=Falseleaves xnsmcl's own folder out;createand Java runtimes then go into Prism's. With both folders off xnsmcl warns and uses its own.use_curseforge=Trueis accepted but CurseForge isn't implemented yet:modsays so and uses Modrinth.use_modrinth=Falsemakes themodcommands 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 (
.zipwithinstance.cfg+mmc-pack.json, at the top or inside one folder) is unpacked as an instance; - a Modrinth modpack (
.mrpack, or a.zipwithmodrinth.index.json) creates an instance for the pack's Minecraft + loader version, downloads every listed file (sha512/sha1-verified, only fromcdn.modrinth.com,github.com,raw.githubusercontent.com,gitlab.com, as the format requires), skips files markedclient: unsupported, then appliesoverrides/andclient-overrides/. Imported mods are not inxnsmcl.lock.json, somod listshows 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 withxnsmcl modwhose jar still matches the lock become download links with sha1 + sha512 + size; everything else (hand-added jars, configs, resource packs) is embedded underoverrides/.--pack-version VsetsversionId(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, againsttests/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 loginis the real test (and needs the approved client ID). - Not run: an actual Minecraft launch (the tests use a fake
javathat records its arguments).
Next features:
instance exportinstance import