@bauxite/launcher-api
Advanced tools
> Provides config, data storage and high-level API for managing Minecraft client instances. > Designed to be consumed by `launcher-ui` and `launcher-cli`.
Provides config, data storage and high-level API for managing Minecraft client instances. Designed to be consumed by
launcher-uiandlauncher-cli.
$ yarn add @bauxite/launcher-api
or
$ npm install --save @bauxite/launcher-api
All methods described below return a Promise unless otherwise specified. "Return" implies the Promise having been resolved, and "throw" implies the Promise having been rejected.
These methods, where interacting with the filesystem, will all write their files to the user's local configuration directory:
%APPDATA%/Bauxite~/Library/Preferences/Bauxite~/.bauxiteAll methods that write to the filesystem will automatically ensure that any required directories exist.
These methods provide read/write access to the user's local configuration data. These
preferences get stored as a JSON file, config.json.
Default values will be supplied for any values not stored in the configuration file, or if the file is missing entirely.
getConfiguration (async)Returns a Promise to return the user's local configuration data as a JSON object.
Returns an object, comprising:
directory: The base directory used by Bauxite for file storage. This is calculated as described above.managedBy: An object containing two keys: name and version. This is to be used to allow migrations where configuration format is changed.clientToken: A token supplied by Mojang to identify this client instance, when authenticating Minecraft users. This will only be present once a user has logged in.{
"directory": "/home/<user>/.bauxite",
"managedBy": {
"name": "@bauxite/launcher-api",
"version": "1.0.0"
},
"clientToken": "abdef0123456789abdef0123456789"
}
const { getConfiguration } = require('@bauxite/launcher-api')
// in an async function:
const { directory, clientToken } = await getConfiguration()
setConfiguration (async)Returns a Promise to update the user's local configuration data. Changes supplied will be merged into the existing configuration, and written to the directory specified above.
It is not possible to override the directory configuration item as yet ─ doing so will throw an error. This restriction may be relaxed in later versions as the ability to relocate an installation directory is introduced.
configChanges - an object containing the new values to apply to the configuration.Returns an object containing the (entire) updated configuration data, identical to that of getConfiguration.
const { setConfiguration } = require('@bauxite/launcher-api')
// in an async function:
const updatedConfig = await setConfiguration({
clientToken: '<hexadecimal token>'
})
These methods provide read/write access to the user's stored Mojang profiles. These preferences are stored as a JSON file in a subdirectory of the user's home directory.
listProfiles (async)Gets a list of the user profiles
Returns a Promise to return an array of profile objects, each of the following shape:
[
{
"username": "tehminerer@aol.com",
"name": "tehminerer",
"uuid": "<meaty hexadecimal token>"
"properties": []
"isDefault": true,
"accessToken": "<hefty hexadecimal token>"
}
]
username: The email address of the Mojang account used to authenticate the user, or the username for legacy Minecraft accounts.name: The player's in-game nameuuid: The player's in-game UUIDproperties: An array additional metadata associated with the account, such as a Twitch access token.isDefault: Whether this account is to be used by default when launching MinecraftaccessToken: The Mojang access token used to launch Minecraftconst { listProfiles } = require('@bauxite/launcher-api')
// in an async function
const profiles = await listProfiles()
createProfile (async)Authenticates a Mojang account, and stores the associated profile for use in-game.
username: The email address of the Mojang account, or legacy Minecraft username.password: The password associated with the Mojang/Minecraft accountReturns an object containing the profile data, equivalent to an element of the array returned by listProfiles.
The isDefault property will be true if there is not already a default profile selected.
If the profile has already been added, an error will be thrown.
If the account does not exist, or the password is wrong, then an error will be thrown.
const { createProfile } = require('@bauxite/launcher-api')
const { name, uuid } = await createProfile('tehminerer@aol.com', 'hunter2')
console.log(`New profile "${name}" added successfully!`)
deleteProfile (async)Removes a stored profile, and revokes the stored access token.
username: The email/username of the account to delete.Returns the profile object for the deleted profile. At this point, the returned access token will be invalid.
If the username does not match that of a stored profile, an error will be thrown.
const { deleteProfile } = require('@bauxite/launcher-api')
const { name } = await deleteProfile('tehminerer@aol.com')
console.log(`Successfully removed profile "${name}"`)
getAccessToken (async)Returns a valid access token for the named profile.
The existing stored access token is first validated ─ if it is still valid, it is returned ─ otherwise a fresh token is requested.
username: Self-explanatoryReturns the access token as a string.
If the username supplied does not match that of a stored profile, an error will be thrown.
const { getAccessToken } = require('@bauxite/launcher-api')
const accessToken = await getAccessToken('tehminerer@aol.com')
getProfileByUsername (async)Gets profile data for the supplied username
username - The email address/usernameA profile object, just like an element of the array returned by listProfiles.
const { getProfileByUsername } = require('@bauxite/launcher-api')
const { name } = await getProfileByUsername('tehminerer@aol.com')
console.log(`In-game name is "${name}"`)
getProfileByUUID (async)Like getProfileByUsername, but accepting a profile's UUID as a parameter instead.
getProfileByName (async)Like getProfileByUsername, but accepting a profile's in-game name as a parameter instead.
getDefaultProfile (async)Gets the default selected user profile.
A profile object, just like an element of the array returned by listProfiles, where isDefault is true.
const { getDefaultProfile } = require('@bauxite/launcher-api')
const { name } = await getDefaultProfile()
console.log(`Default profile is "${name}"`)
setDefaultProfile (async)Sets the default profile to use when launching the game.
name: The in-game name of the profile to set as defaultNothing. Zip. undefined.
If the profile has not already been added, then an error will be thrown.
getAvatarByUuid asyncGets the user's avatar as a Buffer containing PNG image data. Uses API from Crafatar to fetch images.
uuid: The UUID of the player for which to fetch the avataroptions: An optional object with the following properties:
cache: If true, a caching layer will be used to speed up repeated calls. This is enabled by default.size: The pixel width/height (it's square) to render the avatar. Default is 8, matching the actual size of the texture.A Buffer, containing the image file in PNG format.
These methods provide access to the user's locally installed instances of Minecraft (as installed by Bauxite).
listInstances (async)Gets a list of locally installed Minecraft instances, based on the contents of the instances directory.
Returns an array of objects, each representing a locally installed Minecraft instance, looking something like:
[
{
"ID": "sketchy-villager-23",
"directory": "/home/<user>/.bauxite/instances/sketchy-villager-23",
"versionID": "1.10.2"
},
{
"ID": "friendly-creeper-11",
"directory": "/home/<user>/.bauxite/instances/friendly-creeper-11",
"versionID": "1.12.2"
}
]
const { listInstances } = require('@bauxite/launcher-api')
const instances = await listInstances()
console.log(`There are ${instances.length} instances installed:`)
instances.forEach(({ ID, versionID }) => {
console.log(` - ${ID} (${versionID})`)
})
getInstance (async)Gets details of a locally installed Minecraft instance by ID.
ID: The ID of the instance to fetch details for.An object representing the named instance, just like an element of the array returned by listInstances.
const { getInstance } = require('@bauxite/launcher-api')
const { ID, versionID } = await getInstance('friendly-creeper-11')
console.log(`Instance "${ID}" is version "${versionID}"`)
deleteInstance (async)Deletes (i.e. from the filesystem) an installed Minecraft instance, stored data and all.
instanceID: The ID of the instance to delete.Returns true if the instance existed (and was removed), or false if it does not exist.
renameInstance (async)Renames (i.e. changes the ID of) an installed Minecraft instance, including renaming the instance directory.
oldInstanceID: The current ID of the existing instance.newInstanceID: The new ID of the instance.An object representing the renamed instance, just like an element of the array returned by listInstances. The ID returned will be the newInstanceID.
If the new chosen ID is already taken by another installed instance, an error will be thrown.
Likewise, if the new instance ID forms an invalid directory name, an error will be thrown.
installInstanceInstalls an instance of the Minecraft locally.
inputInstanceID: The ID of the instance to install. If omitted, a name will be generated at random using generateInstanceName.versionID: The version of Minecraft to install. If omitted, the latest stable version will be selected.options: An optional object with the following keys:
onProgress: An optional callback function which will be called with progress updates. See details below.cache: If set to false, the installation cache will not be used. By default, it is true.overwrite: If set to true, and inputInstanceID is specified, this will overwrite an existing instance matching that ID instead of throwing an error. This allows installInstance to function both as a means to repair a damaged instance, and as a way to upgrade instances, although for the latter you should use upgradeInstance.When the installation is complete, an object is returned representing the new instance. It looks just like an element of the array returned by listInstances.
onProgress callbackIf the onProgress callback is supplied, it will be called every few miliseconds with an update in the following shape:
{
"delta": 3233, // bytes transferred since last update
"total": 4561282, // total size of transfer
"progress": 2341232, // total progress so far
"percent": 51.3283765 // progress as percent
}
The callback will be called a minimum of twice - once at the start of the installation, and once at the end.
In reality, for most installations, this will be called many times a second - be sure not to attach any heavy UI logic to this callback without throttling it first!
upgradeInstance (async)Upgrades an existing instance of Minecraft to a newer version.
Please note that while this method is capable of downgrading an instance, this is likely to cause issues with any savegames, especially if using snapshot versions of Minecraft, or moving between major releases.
This will not perform upgrades on any savegames attached to the instance ─ this is performed by Minecraft itself when you first attempt to load that world.
instanceID: The ID of the instance to upgradeversionID: The new version of Minecraft to upgrade tooptions: An optional object, with the following properties:
backupFirst: If true (default), then the instance will be cloned before performing the upgrade. The backup instance will be named in the format {instanceID}-backup-{oldVersionID}.installInstance can be used, except overwrite, which will be ignored if set.Returns a value identical to that of installInstance.
If the specified instance does not already exist, an error is thrown.
const { upgradeInstance } = require('@bauxite/launcher-api')
const { ID, versionID } = await upgradeInstance('spicy-pig-32', '1.12.2')
// A short time later...
console.log(`Instance "${ID}" is now on version "${versionID}"!`)
cloneInstance (async)Makes a complete copy of an existing instance, worlds and all.
instanceID: The ID of the instance to clone.cloneInstanceID: The new ID for the copy.Returns an object describing the details of the new copy of the instance, just
like getInstance
const { cloneInstance } = require('@bauxite/launcher-api')
await cloneInstance('jumpy-zombie-99', 'svelte-ghast-38')
backupInstance (async)Makes a backup copy of an existing instance. This is a wrapper around cloneInstance.
instanceID: The ID of the instance of which to make a backup.Returns an object identical to that of cloneInstance.
const { backupInstance } = require('@bauxite/launcher-api')
const { ID } = await backupInstance('covert-enderman-58')
console.log(ID)
// => covert-enderman-58-backup-1.12.2-2018-01-25T00:52:36.962Z
These methods allow the starting, stopping, and interrogation of locally installed Minecraft client instances.
startInstance (async)Starts a locally installed Minecraft instance.
instanceID: the ID of the instance to launch.username: the username to launch the instance with.Returns an object containing data about the launched instance, like the return value of getInstance, with the addition of a processID field. This is an integer representing the launched Minecraft process's ID from the operating system.
If the instance is already running, an error will be thrown.
stopInstance (async)Forcibly stops a running Minecraft instance.
instanceID: The ID of the instance to stop.Returns an object containing data about the stopped instance, like the return value of getInstance.
If this instance is not already running, an error will be thrown.
getCurrentProcessIDForInstance (async)Returns the process ID (pid) of the Minecraft instance, if it is currently running.
instanceID: The ID of the instance to queryIf the instance is currently running, the PID is returned as reported by the operating system.
Otherwise, null is returned.
getOperatingSystem (sync)Returns the name of the current operating system, as used by Minecraft's version manifests.
Returns one of:
WindowsOSXLinuxgenerateInstanceName (sync)Returns a randomly-generated instance name of the format noun-adjective-XX, where noun is the name of a mob from Minecraft, and XX is a random 2-digit number.
FAQs
> Provides config, data storage and high-level API for managing Minecraft client instances. > Designed to be consumed by `launcher-ui` and `launcher-cli`.
We found that @bauxite/launcher-api demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.