@loontail/minecraft-kit v0.5.0

Classes

Class	Description
ChildProcessSpawner	Default spawner backed by node:child_process.spawn.
FabricVersionsApi	Public Fabric versions API surface.
FetchHttpClient	Default HttpClient implementation backed by Node's built-in fetch (undici under the hood). Maps fetch errors to MinecraftKitError.
ForgeVersionsApi	Public Forge versions API surface.
MinecraftKit	Single facade for the entire library.
MinecraftKitError	The single error class thrown by every public API in @loontail/minecraft-kit.
MinecraftVersionsApi	Public Minecraft versions API surface.
RuntimeVersionsApi	Public runtime versions API surface.
TargetsApi	Public Targets API surface.

Interfaces

Interface	Description
ArtifactDownload	A single hash-verified download.
AspectRepairInput	Inputs accepted by every aspect-specific planXxxRepair (planMinecraftRepair, planFabricRepair, planForgeRepair, planRuntimeRepair). The per-aspect input types are aliases over this shape.
AssetIndexDocument	Asset index document body.
AssetIndexReference	Reference to the asset-index JSON file.
AssetObject	A single asset object hash + size.
DetectSystemInput	Inputs allowing the host system to be derived from current Node values or overrides.
DiscoveredLoaderHint	Inferred loader hint (does not assert correctness).
DiscoveredRuntimeHint	Detected runtime files.
DiscoveredTarget	Discovered installation found by scanning a root directory. Contains only what was actually read from disk — no assumptions about correctness, completeness, or repair state.
DownloadAction	A single download step.
ExtractNativeAction	A native extraction step. Source jar must already exist on disk.
FabricCompatibilityEntry	Compatibility entry from /v2/versions/loader/{minecraftVersion}.
FabricListInput	Inputs to FabricVersionsApi.list.
FabricLoaderSummary	Summary entry from /v2/versions/loader.
FabricProfile	Fabric profile JSON returned by /v2/versions/loader/{mc}/{loader}/profile/json.
FabricResolveInput	Inputs to FabricVersionsApi.resolve.
FileRef	Reference to a single file used in download events.
ForgeBuildSummary	A Forge build entry derived from the Maven metadata XML.
ForgeInstallProfile	Modern Forge install_profile.json (spec 1) shape — only fields we actually consume.
ForgeListInput	Inputs to ForgeVersionsApi.list.
ForgeProcessor	A single processor invocation.
ForgeProfileData	Side-keyed data value pair.
ForgeResolveInput	Inputs to ForgeVersionsApi.resolve.
ForgeVersionJson	The version.json stored inside the Forge installer JAR.
HttpClient	Pluggable HTTP client. The default implementation uses Node's built-in fetch; consumers can inject a fake (e.g. for tests) by passing an httpClient to the MinecraftKit constructor.
HttpRequestOptions	Options for an HTTP request.
HttpResponse	Response delivered by the HttpClient interface.
InstallPlan	Pre-computed install plan: a flat ordered list of actions plus computed totals.
InstallReport	Outcome summary returned by install.run.
LaunchComposition	Fully composed launch command, ready to be passed to kit.launch.run.
LaunchExit	Outcome of a finished launch.
LaunchMemoryOptions	Optional memory configuration.
LaunchOptions	Inputs for kit.launch.compose (and the lower-level composeLaunch helper).
LaunchResolutionOptions	Optional resolution / window configuration.
LaunchRunOptions	Options for kit.launch.run (and the lower-level runLaunch helper).
LaunchSession	Live handle for a running game process.
LibraryArtifact	An individual library artifact (jar/zip).
LibraryRule	Rule entry used by libraries and modern arguments.
Logger	Pluggable logger. Default implementation is a silent logger; pass your own to surface logs.
MemoryCacheOptions	Inputs to createMemoryCache.
MetadataCache	Pluggable in-memory cache for HTTP metadata responses.
MinecraftArguments	Modern (1.13+) arguments structure.
MinecraftDownloads	Per-platform downloads block of the Minecraft per-version manifest.
MinecraftGetInput	Inputs to MinecraftVersionsApi.get / .resolve.
MinecraftJavaVersion	Required Java runtime descriptor from the version manifest.
MinecraftKitErrorContext	Structured context attached to errors.
MinecraftKitOptions	Constructor options for MinecraftKit.
MinecraftLatestInput	Inputs to MinecraftVersionsApi.latest.
MinecraftLibrary	Library entry. Combines vanilla, modern-natives, and legacy-classifier shapes.
MinecraftLibraryDownloads	Library downloads block.
MinecraftListInput	Inputs to MinecraftVersionsApi.list.
MinecraftLogging	Logging-config entry from the version manifest.
MinecraftVersionManifest	Subset of the per-version manifest used by resolvers and consumers.
MinecraftVersionSummary	One entry from the top-level Minecraft version_manifest_v2.json listing.
OfflineAuth	Offline authentication.
OnlineAuth	Online (token-based) authentication.
OperationOptions	Common options accepted by long-running operations.
PlanRuntimeInstallInput	Inputs to planRuntimeInstall.
PlanStandaloneRuntimeInstallInput	Inputs to planStandaloneRuntimeInstall.
ProcessStream	Stream-of-text channel exposed by spawned processes.
ProcessorRef	A single processor description used in Forge events.
RepairAspect	Shared shape of every aspect-specific repair surface (repair.minecraft, .fabric, …).
RepairPlan	A repair plan is, structurally, an install plan limited to actions needed to fix the issues reported by a previous VerificationResult. The runner is the same.
RepairPlanOptions	Options for any repair.<aspect>.plan call. Accepts one or many verification results.
RepairReport	Repair report — same shape as install report.
ResolvedFabricLoader	Resolved Fabric loader for a specific Minecraft version.
ResolvedForgeLoader	Resolved Forge loader.
ResolvedMinecraft	Fully resolved Minecraft version: summary + parsed manifest, ready to feed into kit.targets.create or kit.install.plan.
ResolvedRuntime	Resolved runtime ready to install or launch with.
ResolvedVanillaLoader	Trivial loader used when no mod loader is in play. Carries the resolved Minecraft so the launch composer has a uniform view across vanilla / Fabric / Forge.
ResolverContext	Shared context passed to every resolver.
RunForgeProcessorAction	A Forge processor invocation. Main-Class is intentionally NOT carried here — the runner reads it from classpath[0]'s manifest at execution time, because the JAR is not guaranteed to exist on disk during planning (newer Forge versions ship some processor JARs as regular Maven libraries instead of bundling them in the installer).
RunRepairInput	Inputs to runRepair. Shared across all aspect-specific repair flows.
RuntimeFileDirectory	A directory placeholder.
RuntimeFileFile	A file entry: real bytes to download, may have lzma sidecar.
RuntimeFileLink	A relative symlink.
RuntimeFilesManifest	Inner per-component file manifest.
RuntimeIndexEntry	A single available runtime release.
RuntimeListEntry	A summary entry for the list API.
RuntimeListInput	Inputs to RuntimeVersionsApi.list.
RuntimeResolveInput	Inputs to RuntimeVersionsApi.resolve.
RuntimeSystem	Identifies the host system for the launcher. All resolvers consume this object to pick the right artifacts (libraries, natives, runtime).
SpawnOptions	Options accepted by the spawner.
SpawnedProcess	Live handle for a child process.
Spawner	Pluggable process spawner. The default implementation uses node:child_process; tests inject a fake to avoid spawning real processes.
Target	Fully resolved target: a concrete Minecraft + loader + runtime + directory.
TargetCreateInput	Inputs accepted by kit.targets.create.
TargetListInput	Inputs to TargetsApi.list.
TargetResolveInput	Inputs to TargetsApi.resolve.
TargetsApiContext	Constructor inputs for TargetsApi.
UpdatePlan	Update plan — additive list of actions to bring an installation up to date.
UpdateReport	Update report.
VerificationFileResult	A single verified file.
VerificationResult	Aggregate verification result returned by each verify.<kind>.run API.
VerifyFabricInput	Inputs to verifyFabric.
VerifyForgeInput	Inputs to verifyForge.
VerifyMinecraftInput	Inputs to verifyMinecraft.
VerifyOperationOptions	Options accepted by every verify.<kind>.run.
VerifyRuntimeInput	Inputs to verifyRuntime.
WriteLoggingConfigAction	Write a logging config (log4j XML) to disk.
WriteVersionJsonAction	Write a version JSON to disk (Fabric / Forge).

Type Aliases

Type alias	Description
ApiEndpointsShape	Surface type useful for DI.
Architecture	Architecture literal used in launcher metadata.
ArgumentEntry	A single argument entry: bare string or rule-gated value.
AuthMode	Auth mode literal.
EventType	Literal type of the type discriminator of a ProgressEvent.
HttpHeaders	Subset of fetch headers the library actually uses.
InstallAction	Discriminated union of install actions.
InstallActionKind	Discriminator for an install action.
InstallPhase	Install phase literal.
LaunchAuth	Auth shape consumed by kit.launch.compose.
LaunchPlaceholder	Token literal type.
Loader	A fully resolved loader pinned to a specific Minecraft version. Use the type field to narrow to the concrete shape.
LoaderKind	Loader-kind literal (used as discriminator on loader objects).
LogLevel	Log-level literal.
MinecraftChannel	Channel literal as it appears in version manifest entries.
MinecraftKitErrorCode	Stable error code discriminator. Consumers can switch (e.code) exhaustively.
OperatingSystem	OS literal as used inside Mojang/Forge/Fabric JSON manifests.
PlanFabricRepairInput	Inputs to planFabricRepair.
PlanForgeRepairInput	Inputs to planForgeRepair.
PlanMinecraftRepairInput	Inputs to planMinecraftRepair.
PlanRuntimeRepairInput	Inputs to planRuntimeRepair.
ProgressEvent	Discriminated union of all runtime progress events. Pass an onEvent callback to install.run, update.run, verify.run, repair.run, or launch.run to receive these.
ProgressListener	Listener signature accepted by every long-running operation.
RepairPhase	Repair phase literal.
RuntimeComponent	Runtime component literal.
RuntimeFileEntry	A single file in the runtime manifest.
RuntimeIndex	Top-level runtime index returned by Mojang.
RuntimeIndexPlatform	Per-platform component map inside the runtime index.
RuntimePreferenceKind	Runtime preference literal.
TargetLoaderInput	Loader input variants.
VerificationKind	Verification kind literal.
VerifyFileCategory	Verification file category literal.
VerifyFileStatus	File status literal.
VersionPreferenceKind	Resolution-preference literal.

Variables

Variable	Description
ASSETS_DIR	-
ASSETS_INDEXES_DIR	-
ASSETS_LEGACY_DIR	-
ASSETS_LOG_CONFIGS_DIR	-
ASSETS_OBJECTS_DIR	-
ASSETS_RESOURCES_DIR	-
ASSETS_VIRTUAL_DIR	-
ApiEndpoints	Endpoint builders.
Architectures	CPU architecture identifiers. Matches the values that appear in Mojang library os.arch fields, after normalization from Node's NodeJS.Architecture.
AuthModes	Authentication modes accepted by the launch composer.
BASE_JVM_ARGS	JVM args appended for every launch.
CACHE_MAX_ENTRIES	Maximum number of entries kept in the metadata cache.
CACHE_TTL_MS	TTL for in-memory metadata cache entries, in milliseconds.
DEFAULT_KILL_GRACE_MS	Time after a SIGTERM before escalating to SIGKILL when aborting a launch.
DEFAULT_LAUNCHER_NAME	Default launcher brand sent through ${launcher_name}.
DEFAULT_LAUNCHER_VERSION	Default launcher version sent through ${launcher_version}.
DEFAULT_LIBRARY_REPOSITORY	Default Maven base URL when a library entry has no url.
DEFAULT_MAX_MB	Default max heap size in megabytes.
DEFAULT_MIN_MB	Default min heap size in megabytes.
DOWNLOAD_CONCURRENCY	Default per-host concurrency for downloads. The runner uses a worker-pool: when one file finishes, the next file in the queue starts immediately. There is no batch barrier.
EXTRACTION_MAX_COMPRESSION_RATIO	Maximum compression ratio (decompressed / compressed) before treating as a zip bomb.
EXTRACTION_MAX_ENTRY_COUNT	Maximum entry count per archive.
EXTRACTION_MAX_FILE_SIZE	Per-file size cap during archive extraction (bytes).
EXTRACTION_MAX_TOTAL_SIZE	Total decompressed-bytes cap per archive.
EventTypes	Stable string constants for the type discriminator of every ProgressEvent. Use these instead of bare string literals when filtering events.
FABRIC_MAVEN_BASE	Fabric's Maven base.
FALLBACK_COMPONENT	Fallback Mojang component when the per-version manifest declares none. Pre-1.7 vanilla versions and a handful of legacy snapshots fall in this bucket.
FORGE_INSTALLERS_DIR	-
FORGE_INSTALLER_MAX_SIZE	Reasonable maximum bytes a Forge installer JAR can be.
FORGE_MAVEN_BASE	Forge's Maven base.
HTTP_RETRY_BACKOFF_BASE_MS	Base delay for exponential backoff, in milliseconds.
HTTP_RETRY_BACKOFF_CAP_MS	Maximum delay for exponential backoff, in milliseconds.
HTTP_RETRY_MAX	Maximum retry attempts for transient HTTP failures.
HTTP_TIMEOUT_MS	HTTP request timeout for metadata calls, in milliseconds.
InstallActionKinds	Action kinds inside an InstallPlan.
InstallPhases	Coarse-grained install phases. Used in install:phase-changed events so consumers can render a progress bar with named steps.
JAVA_EXECUTABLE	Java executable filename per OS (relative to the runtime root).
LAUNCH_PLACEHOLDERS	All ${...} tokens substituted into JVM and game arguments.
LEGACY_JVM_ARGS	JVM args added for legacy (≤1.12) versions that lack arguments.jvm.
LIBRARIES_DIR	-
Loaders	Discriminator literal identifying which mod loader is active for a target.
LogLevels	Log levels accepted by the pluggable logger.
MACOS_JVM_ARGS	macOS-only JVM args (suppress dock label).
MAC_RUNTIME_PREFIX	macOS runtime layout adds this prefix above JAVA_EXECUTABLE.osx.
MAX_PROCESSOR_STDERR_LINES	Maximum number of stderr lines retained from a Forge processor for diagnostics.
MinecraftChannels	Minecraft release channels matching the type field of Mojang version manifest entries.
NATIVES_DIR_NAME	-
NODE_ARCH_TO_MOJANG_ARCH	Mapping from Node's process.arch to Mojang/Mojang-runtime arch tags.
NODE_PLATFORM_TO_MOJANG_OS	Mapping from Node's process.platform to Mojang OS names.
OperatingSystems	Operating-system identifiers used by Mojang launcher metadata.
PROGRESS_EVENT_INTERVAL_MS	Throttle interval for emitting download:progress events (in milliseconds).
RUNTIMES_DIR	-
RUNTIME_PLATFORM_KEYS	Mapping from {OperatingSystem, Architecture} to the runtime-index platform key.
RepairPhases	Coarse-grained repair phases used for repair:phase-changed events.
RuntimeComponents	Mojang Java-runtime component identifiers. New components appear over time (e.g. java-runtime-delta for Java 21).
RuntimePreference	User-supplied resolution preferences.
SPAWNER_MAX_LINE_BYTES	Maximum bytes per line emitted by ChildProcessSpawner. Lines longer than this are split: a Minecraft crash that prints megabytes of unbroken text should not exhaust memory inside the launcher.
USER_AGENT	User-agent value sent on every HTTP request.
VERSIONS_DIR	Relative-path segments used to build per-target directory layouts.
VerificationKinds	Aspect of an installation a verification result describes.
VerifyFileCategories	Categories assigned to each verified file for easier filtering.
VerifyFileStatuses	Status of an individual file checked during verification.
VersionPreference	Resolution preference used when a user wants the latest, recommended, or a specific version. Preferences are inputs to resolvers; resolved targets always carry concrete versions.
consoleLogger	Logger that mirrors messages to console.<level> with structured fields.
silentLogger	Logger that drops every message. Default when no logger is supplied.

Functions

Function	Description
createMemoryCache	In-memory metadata cache backed by lru-cache.
detectSystem	Resolve the current host system identifiers.
isErrorCode	True when e is an MinecraftKitError carrying the given code.
isMinecraftKitError	True when e is an MinecraftKitError.
offlineUuidFor	Derive a stable v3-style UUID for an offline player username.
planFabricRepair	Build a repair plan covering the Fabric loader slice: profile JSON + libraries.
planForgeRepair	Build a repair plan covering the Forge loader slice: version JSON, libraries, installer download, and the Forge processors that produce the final installation. When the Forge version JSON was missing during verify (so libraries couldn't be enumerated), every forge-library download is added defensively — downloadFile skips files already on disk.
planMinecraftRepair	Build a repair plan covering only the vanilla Minecraft slice: client jar, version JSON, libraries (incl. native jars), assets, logging config, and native extractions.
planRuntimeInstall	Build an install plan that downloads ONLY the Java runtime declared by target.runtime.
planRuntimeRepair	Build a repair plan covering the Java runtime files. target.runtime.installRoot is honoured automatically because both planInstall and the verify side resolve runtime paths through the same targetPaths.runtimeRoot(..., installRoot) helper.
planStandaloneRuntimeInstall	Plan a runtime-only install without a Minecraft target. Useful for "Install Java/runtime" flows where the user just wants a JRE on disk and never had a Minecraft version to choose from. The returned plan is shaped exactly like a normal InstallPlan and runs through the standard install runner — but its target.minecraft and target.loader fields are intentional placeholders. The runner only reads target.runtime for runtime-only plans, so the placeholders are never accessed at runtime.
runRepair	Execute any repair plan. Reuses the install runner.
stripUuidDashes	Strip the dashes from a UUID. Used by ${auth_uuid}.
verifyFabric	Verify the Fabric loader slice: profile JSON + every library it pulls in.
verifyForge	Verify the Forge loader slice: the on-disk Forge version JSON and every library it declares. Libraries can only be enumerated once the JSON is present and parsable; a malformed JSON is surfaced as a CORRUPT issue so repair rewrites it before re-running.
verifyMinecraft	Verify the vanilla Minecraft slice of an installation: the client jar, version JSON, libraries (incl. native jars), assets (index + objects), logging config, and the extracted natives directory.
verifyRuntime	Verify the Java runtime files. Honours target.runtime.installRoot when set so a shared/global runtime install is checked at its real location instead of the per-target runtime/ subfolder.