TypeScript

TypeScript is a programming language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript and adds optional static typing to the language. TypeScript is designed for the development of large applications and transcompiles to JavaScript. As TypeScript is a superset of JavaScript, existing JavaScript programs are also valid TypeScript programs.

Typescript is very beneficial to use when developing scripts for Minecraft addons. There exist libraries to aid in the development of Minecraft addons to provide intellisense and type-safety for broadcasting and listening to events.

How it Works #

TypeScript is a language which requires compilation into JavaScript. Minecraft has no idea what to do with a .ts file. Therefore some tooling needs to be set up in order to utilize TypeScript to build addons.

First, the TypeScript files need to be compiled into JavaScript, which is all accomplished by utilizing the TypeScript Compiler. Then the files can be utilized by Minecraft's scripting system.

Since there is already a build step, we might as well incorporate some other systems to allow for file separation and code sharing. Minecraft's scripting system will only act on the script files within their respective folders utilizing what is assumed to be, Mojang's own JavaScript interpreter. Therefore, any logic split across multiple files must be merged into a single large file. This is where tooling such as webpack and browserify come in handy.

Script API #

Prerequisites #

1. Minecraft Bedrock Edition (Windows 10)
2. A code editor like Visual Studio Code (although Notepad will technically be sufficient, we will be assuming the usage of VSCode going forward)
3. basic knowledge of Javascript (this tutorial will not be teaching you how to code in Javascript and presumes a baseline knowledge of it)
4. Node.js is required for installing tooling and compiling TypeScript into JavaScript.
5. Knowledge of TypeScript

Setup Guide #

This guide is for setting up a Script API TypeScript project using TypeScript compiler.

Getting Started #

Open a terminal (Command Prompt for Windows) and navigate to where the project should be located. It can be anywhere. For Windows 10 you can also Shift + RClick in file explorer and select Open in PowerShell.

Next we need to install the template generator for creating the addon. To do this, enter the following commands.

The following command install TypeScript globally.

npm install -g typescript

The following command creates a package.json file in current directory. See here for more information.

npm init -y

The following commands install Script API modules. Beta APIs is used in this example.

npm install @minecraft/server@beta
npm install @minecraft/server-ui@beta
npm install @minecraft/server-gametest@beta
npm install @minecraft/server-admin@beta
npm install @minecraft/server-net@beta

Now the project can be initialized. The next step is to create a TypeScript project by creating a tsconfig.json file in your current directory, with the following details which simulates the Minecraft Scripting API file system.

{
  "compilerOptions": {
    // Specify what type of code is generated.
    "module": "ES2020",
    "target": "ES2021",
    "moduleResolution": "Node",
    "allowSyntheticDefaultImports": true,
    // Specify the folder entry for your TS files
    "baseUrl": "./src",
    "rootDir": "./src",
    // Specify the folder output for generated JS files.
    "outDir": "./scripts"
  },
  "exclude": [ "node_modules" ],
  "include": [ "src" ]
}

Now that you created the project, it can be opened in your IDE of choice. If you are utilizing VS Code, you can cd into your project directory and run code . to open your project.

Project Structure #

Unless you know what you are doing, the only part of the project to be concerned with is everything within the src folder. That is where all the development should take place.

Commands #

The following commands are most utilized when developing a project.

tsc

tsc will compile all your TS files in scripts folder to your behavior packs folder.

tsc --watch

--watch will watch for any changes you make within the src directory and automatically reinstall the addon.

To run the code in Minecraft, zip the behavior pack and import it to a Minecraft world. In your behavior pack should only include these files in the following, and the rest of the files do not have to be included in .mcpack compressed file.

Legacy Scripting #

You do not need to know how to utilize these tools since there are already libraries that utilize them for you without any effort on your behalf. It is just important to understand the tooling making these sorts of libraries possible.

Prerequisites #

1. Beginners Guide Prerequisites
2. Node.js is required for installing tooling and compiling TypeScript into JavaScript.
3. Knowledge of TypeScript and read through the Beginners Guide

TypeScript-Supported Libraries #

Setup Guide #

This guide is for setting up and using the minecraft-addon-toolchain as it currently provides the most tooling with the easiest setup.

Getting Started #

Open a terminal (Command Prompt for Windows) and navigate to where the project should be located. It can be anywhere. For Windows 10 you can also Shift + RClick in file explorer and select Open in PowerShell.

Next we need to install the template generator for creating the addon. To do this, enter the following commands.

npm install -g yeoman

npm install -g generator-minecraft-addon

Now the project can be initialized. The next step is to generate the project with all the information you define.

yo minecraft-addon

Now that you created the project, it can be opened in your IDE of choice. If you are utilizing VS Code, you can cd into your project directory and run code . to open your project.

Project Structure #

Unless you know what you are doing, the only part of the project to be concerned with is everything within the packs folder. That is where all the development should take place.

Commands #

The following commands are most utilized when developing a project using minecraft-addon-toolchain.

npm run installaddon

installaddon will, as it says, install the addon into the development resource/behaviors folders. The pack can then be utilized like any other addon.

npm run watch

watch will watch for any changes you make within the packs directory and automatically reinstall the addon.

npm run packageaddon

packageaddon will build, package, and zip the addon in a connivent manner. By default, outputs to out/packaged directory.