This package has been deprecated

Author message:

Package rewritten and abandoned! Please use the new package @xmcl/minecraft-launcher-core

ts-minecraft

Provide several useful functions for Minecraft.

This package is targeting the Electron environment. Feel free to report issues related to it.

This package is now MAINTAINING only! The bug might not be fixed on time. I did a refactor on this package and split it into multiple small packages. The alternative of this @xmcl/minecraft-launcher-core

Usage

import { NBT, ServerInfo, ...so on...} from 'ts-minecraft'

Getting Started

• ts-minecraft
  • Usage
  • Getting Started
    • NBT
    • WorldInfo
    • Server
    • Minecraft Install
    • GameSetting
    • Language
    • ResourcePack
    • Game Profile
    • Mojang Account Info
    • Forge
    • Fabric
    • TextComponent
    • Auth
    • Version
    • Launch
  • Experiental Features
    • Monitor download progress
  • Caching Request
  • Issue
  • Credit

NBT

    import { NBT } from 'ts-minecraft'
    const fileData: Buffer;
    const compressed: boolean;
    const readed: NBT.TypedObject = NBT.Serializer.deserialize(fileData, compressed);
 
    const serial: NBT.Serializer.create()
        .register('server', {
            name: NBT.TagType.String,
            host: NBT.TagType.String,
            port: NBT.TagType.Int,
            icon: NBT.TagType.String,
        });
    const serverInfo;
    const serialized: Buffer = serial.serialize(serverInfo, 'server');

Serialize/deserialize NBT.

    import { NBT } from 'ts-minecraft'
    // First create NBT tag like this.
    let rootTag: NBT.TagCompound = NBT.TagCompound.newCompound();
    rootTag.set('TheEnd', NBT.TagScalar.newString("That's all"));
    rootTag.set('key1', NBT.TagScalar.newString('value1'));
    // Checks if key exists. Then cast it to string tag.
    let key1Tag: NBT.TagString = checkExists(rootTag.get('key1')).asTagString();
    function checkExists<T>(t: T | undefined): T {
        if (t === undefined)
            throw new Error('key not exists');
        return t;
    }
    console.log(key1Tag.value); // print value1
    // If list contains list. list those inside forget there element type.
    let listTag: NBT.TagList<NBT.TagAnyList> = NBT.TagList.newListList();
    rootTag.set('testList', listTag);
    let stringListTag: NBT.TagList<NBT.TagString> = NBT.TagList.newStringList();
    stringListTag.push(NBT.TagScalar.newString('hello'), NBT.TagScalar.newString('world'));
    let doubleListTag: NBT.TagList<NBT.TagDouble> = NBT.TagList.newDoubleList();
    // This gives you a way to add different list in.
    listTag.push(stringListTag, doubleListTag);
    // And still prevent you add other things in it.
    // listTag.push(NBT.TagCompound.newCompound()); // Illegal
    // You can cast list to whatever list you want after you got a list without element type.
    console.log(listTag[0].asTagListString()[0].asTagString().value); // print hello
    // You can iterate values in list.
    for (let stringTag of stringListTag) {
        console.log(stringTag.value); // print hello then print world
    }
    // And also entries in compound.
    for (let [key, value] of rootTag) {
        if (value.tagType === NBT.TagType.String)
            console.log('[' + key + ' = ' + value.asTagString().value + ']');
    }
    // Finally you can write root tags to buffer and read root tags from buffer.
    let buffer: Buffer = NBT.Persistence.writeRoot(rootTag, { compressed: true } );
    let ourTag: NBT.TagCompound = NBT.Persistence.readRoot(buffer, { compressed: true } );
    console.log(checkExists(ourTag.get('TheEnd')).asTagString().value); // print That's all

Typed NBT API for structured NBT manipulation.

WorldInfo

    import { WorldInfo } from 'ts-minecraft'
    const levelDatBuffer: Buffer;
    const info: WorldInfo = WorldInfo.parse(levelDatBuffer);

Read a WorldInfo from buffer.

Server

    import { Server } from 'ts-minecraft'
    const seversDatBuffer: Buffer;
    const infos: Server.Info[] = Server.parseNBT(seversDatBuffer);
    const info: Server.Info = infos[0]
    // fetch the server status
    const promise: Promise<Server.Status> = Server.fetchStatus(info);
    // or you want the raw json
    const rawJsonPromise: Promise<Server.StatusFrame> = Server.fetchStatusFrame(info);

Read sever info and fetch its status.

Minecraft Install

    import { VersionMeta, VersionMetaList, Version, MetaContainer, MinecraftLocation } from 'ts-minecraft'
    const minecraft: MinecraftLocation;
    const versionPromise: Promise<Version> = Version.updateVersionMeta()
        .then((metas: MetaContainer) => metas.list.versions[0]) // i just pick the first version in list here 
        .then((meta: VersionMeta) => Version.install('client', meta, minecraft))

Fully install vanilla minecraft client including assets and libs.

GameSetting

    import { GameSetting } from 'ts-minecraft'
    const settingString;
    const setting: GameSetting = GameSetting.parse(settingString);
    const string: string = GameSetting.stringify(setting);

Serialize/Deserialize the minecraft game setting string.

Language

    import { Language, MinecraftLocation } from 'ts-minecraft'
    const location: MinecraftLocation;
    const version: string;
    const langs: Promise<Language[]> = Language.read(location, version)

Read language info from version

ResourcePack

    import { ResourcePack } from 'ts-minecraft'
    const fileFullPath;
    Promise<ResourcePack> packPromise = ResourcePack.read(fileFullPath);
    // or you want read from folder, same function call
    Promise<ResourcePack> fromFolder = ResourcePack.read(fileFullPath);
 
    // if you have already read the file, don't want to reopen the file
    // the file path will be only used for resource pack name
    const fileContentBuffer: Buffer;
    Promise<ResourcePack> packPromise = ResourcePack.read(fileFullPath, fileContentBuffer);

Read ResourcePack from filePath

Game Profile

    import { ProfileService, GameProfile } from 'ts-minecraft'
    const userUUID: string;
    const gameProfilePromise: Promise<GameProfile> = ProfileService.fetch(userUUID);

Or lookup profile by name.

    const username: string;
    const gameProfilePromise: Promise<GameProfile> = ProfileService.lookup(username);

Fetch the user game profile by uuid. This could also be used for get skin.

    const gameProfile: GameProfile;
    const texturesPromise: Promise<GameProfile.Textures> = ProfileService.fetchProfileTexture(gameProfile);

Mojang Account Info

    import { MojangService } from 'ts-minecraft'
    const accessToken: string;
    const info: Promise<MojangAccount> = MojangService.getAccountInfo(accessToken); 

Forge

    import { Forge } from 'ts-minecraft'
    const forgeModJarBuff: Buffer;
    Promise<Forge.MetaData[]> metasPromise = Forge.meta(forgeModJarBuff);

Read the forge mod metadata, including @Mod annotation and mcmod json data

    const modConfigString: string;
    const config: Forge.Config = Forge.Config.parse(modConfigString);
    const serializedBack = Forge.Config.stringify(config);

Read the forge mod config

    import { ForgeWebPage } from 'ts-minecraft'
    const pagePromise = ForgeWebPage.getWebPage(); 
    const minecraftLocation: MinecraftLocation;
    pagePromise.then((page) => {
        const mcversion = page.mcversion;
        const firstVersionOnPage = page.versions[0];
        const forgeVersionMeta = Forge.VersionMeta.from(firstVersionOnPage);
        return Forge.install(forgeVersionMeta, minecraftLocation);
    });

Get the forge version info and install forge from it.

Notice that this installation doesn't ensure full libraries installation. Please run Version.checkDependencies afther that.

The new 1.13 forge installation process requires java to run. Either you have java executable in your environment variable PATH, or you can assign java location by Forge.install(forgeVersionMeta, minecraftLocation, { java: yourJavaExecutablePath });.

If you use this auto installation process to install forge, please checkout Lex's Patreon. Consider support him to maintains forge.

Fabric

    import { Fabric } from 'ts-minecraft'
    const versionList: Fabric.VersionList = await Fabric.updateVersionList();
    const latestYarnVersion = versionList.yarnVersions[0]; // yarn version is combined by mcversion+yarn build number
    const latestLoaderVersion = versionList.loaderVersions[0];

Fetch the new fabric version list.

    import { Fabric } from 'ts-minecraft'
    const minecraftLocation: MinecraftLocation;
    const yarnVersion: string; // e.g. "1.14.1+build.10"
    const loaderVersion: string; // e.g. "0.4.7+build.147"
    const installPromise: Promise<void> = Fabric.install(yarnVersion, loaderVersion, minecraftLocation)

Install fabric to the client. This installation process doesn't ensure the minecraft libraries.

Please run Version.checkDependencies after that to install fully.

TextComponent

    import { TextComponent } from 'ts-minecraft'
    const fromString: TextComponent = TextComponent.str('from string');
    const formattedString: string;
    const fromFormatted: TextComponent = TextComponent.from(formattedString);

Create TextComponent from string OR Minecraft's formatted string, like '§cThis is red'

Auth

    import { Auth } from 'ts-minecraft'
    const username: string;
    const password: string;
    const authFromMojang: Promise<Auth> = Auth.Yggdrasil.login({username, password});
    const authOffline = Auth.offline(username);

Using AuthService to online/offline auth

Version

    import { Version } from 'ts-minecraft'
    const location: MinecraftLocation;
    const versionId: string;
    const version: Version = Version.parse(location, versionId);

Parse existed version.

Launch

    import { Launcher } from 'ts-minecraft'
    const version: string;
    const javaPath: string;
    const gamePath: string;
    const proc: Promise<ChildProcess> = Launcher.launch({gamePath, javaPath, version});

Launch minecraft from a version

Experiental Features

They might be not stable.

Monitor download progress

    import { Version } from 'ts-minecraft';
 
    const expectedVersion: string;
    const expectedMcLoc: MinecraftLocation;
    const resolvedVersion: Version = await Version.parse(expectedMcLoc, expectedVersion);
    const task: Task<Version> = Version.checkDependenciesTask(resolvedVersion, expectedMcLoc);

Caching Request

The functions that request minecraft version manifest, forge version webpage, or liteload version manifest can have cache option.

You should save the old result from those functions and pass it as the fallback option. These function will check if your old manifest is outdated or not, and it will only request a new one when your fallback option is outdated.

For Minecraft:

    const forceGetTheVersionMeta = Version.updateVersionMeta();
    const result = Version.updateVersionMeta({ fallback: forceGetTheVersionMeta }); // this should not request the manifest url again, since the forceGetTheVersionMeta is not outdated.

Normally you will load the last version manifest from file:

    const oldManifest = JSON.parse(fs.readFileSync("manifest-whatevername-cache.json").toString());
    const result = Version.updateVersionMeta({ fallback: oldManifest }); // the result should up-to-date.

For Forge, it's the same:

    const forgeGet = ForgeWebPage.getWebPage(); // force get
 
    const oldWebPageCache = JSON.parse(fs.readFileSync("forge-anyname-cache.json").toString());
    const updated = ForgeWebPage.getWebPage({ fallback: oldWebPageCache }); // this should be up-to-date

Issue

• Really need runtime check for parsed Forge/LiteMod data(Hopefully, more people write this correctly)

Credit

Yu Xuanchi, co-worker, quality control of this project.

Haowei Wen, the author of JMCCC, Authlib Injector, and Indexyz, help me a lot on Minecraft launching, authing.