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

1    import { NBT } from 'ts-minecraft'
2    const fileData: Buffer;
3    const compressed: boolean;
4    const readed: NBT.TypedObject = NBT.Serializer.deserialize(fileData, compressed);
5
6    const serial: NBT.Serializer.create()
7        .register('server', {
8            name: NBT.TagType.String,
9            host: NBT.TagType.String,
10            port: NBT.TagType.Int,
11            icon: NBT.TagType.String,
12        });
13    const serverInfo;
14    const serialized: Buffer = serial.serialize(serverInfo, 'server');

Serialize/deserialize NBT.

1    import { NBT } from 'ts-minecraft'
2    // First create NBT tag like this.
3    let rootTag: NBT.TagCompound = NBT.TagCompound.newCompound();
4    rootTag.set('TheEnd', NBT.TagScalar.newString("That's all"));
5    rootTag.set('key1', NBT.TagScalar.newString('value1'));
6    // Checks if key exists. Then cast it to string tag.
7    let key1Tag: NBT.TagString = checkExists(rootTag.get('key1')).asTagString();
8    function checkExists<T>(t: T | undefined): T {
9        if (t === undefined)
10            throw new Error('key not exists');
11        return t;
12    }
13    console.log(key1Tag.value); // print value1
14    // If list contains list. list those inside forget there element type.
15    let listTag: NBT.TagList<NBT.TagAnyList> = NBT.TagList.newListList();
16    rootTag.set('testList', listTag);
17    let stringListTag: NBT.TagList<NBT.TagString> = NBT.TagList.newStringList();
18    stringListTag.push(NBT.TagScalar.newString('hello'), NBT.TagScalar.newString('world'));
19    let doubleListTag: NBT.TagList<NBT.TagDouble> = NBT.TagList.newDoubleList();
20    // This gives you a way to add different list in.
21    listTag.push(stringListTag, doubleListTag);
22    // And still prevent you add other things in it.
23    // listTag.push(NBT.TagCompound.newCompound()); // Illegal
24    // You can cast list to whatever list you want after you got a list without element type.
25    console.log(listTag[0].asTagListString()[0].asTagString().value); // print hello
26    // You can iterate values in list.
27    for (let stringTag of stringListTag) {
28        console.log(stringTag.value); // print hello then print world
29    }
30    // And also entries in compound.
31    for (let [key, value] of rootTag) {
32        if (value.tagType === NBT.TagType.String)
33            console.log('[' + key + ' = ' + value.asTagString().value + ']');
34    }
35    // Finally you can write root tags to buffer and read root tags from buffer.
36    let buffer: Buffer = NBT.Persistence.writeRoot(rootTag, { compressed: true } );
37    let ourTag: NBT.TagCompound = NBT.Persistence.readRoot(buffer, { compressed: true } );
38    console.log(checkExists(ourTag.get('TheEnd')).asTagString().value); // print That's all

Typed NBT API for structured NBT manipulation.

WorldInfo

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

Read a WorldInfo from buffer.

Server

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

Read sever info and fetch its status.

Minecraft Install

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

Fully install vanilla minecraft client including assets and libs.

GameSetting

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

Serialize/Deserialize the minecraft game setting string.

Language

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

Read language info from version

ResourcePack

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

Read ResourcePack from filePath

Game Profile

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

Or lookup profile by name.

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

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

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

Mojang Account Info

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

Forge

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

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

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

Read the forge mod config

1    import { ForgeWebPage } from 'ts-minecraft'
2    const pagePromise = ForgeWebPage.getWebPage(); 
3    const minecraftLocation: MinecraftLocation;
4    pagePromise.then((page) => {
5        const mcversion = page.mcversion;
6        const firstVersionOnPage = page.versions[0];
7        const forgeVersionMeta = Forge.VersionMeta.from(firstVersionOnPage);
8        return Forge.install(forgeVersionMeta, minecraftLocation);
9    });

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

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

Fetch the new fabric version list.

1    import { Fabric } from 'ts-minecraft'
2    const minecraftLocation: MinecraftLocation;
3    const yarnVersion: string; // e.g. "1.14.1+build.10"
4    const loaderVersion: string; // e.g. "0.4.7+build.147"
5    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

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

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

Auth

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

Using AuthService to online/offline auth

Version

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

Parse existed version.

Launch

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

Launch minecraft from a version

Experiental Features

They might be not stable.

Monitor download progress

1    import { Version } from 'ts-minecraft';
2
3    const expectedVersion: string;
4    const expectedMcLoc: MinecraftLocation;
5    const resolvedVersion: Version = await Version.parse(expectedMcLoc, expectedVersion);
6    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:

1    const forceGetTheVersionMeta = Version.updateVersionMeta();
2    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:

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

For Forge, it's the same:

1    const forgeGet = ForgeWebPage.getWebPage(); // force get
2
3    const oldWebPageCache = JSON.parse(fs.readFileSync("forge-anyname-cache.json").toString());
4    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.