Getting Started

MagicScript is a JavaScript runtime for running native Lumin Runtime applications on Magic Leap hardware. They are written in pure JavaScript and packaged and installed using the same .mpk format used by C++ applications except in this case there is no native code in the .mpk file.

Magic Leap SDK

The Magic Leap SDK is needed to run applications on an actual device. Detailed instructions can be found in the developer portal. For MagicScript development, all that is needed from Package Manager is the Lumin SDK that includes the mabu and mldb command-line tools.

If you are only writing MagicScript applications in JavaScript then there is no need to install Lumin Runtime Packages. They are for C++ programs. The entire runtime for MagicScript programs lives inside the Lumin OS and mpk files only contain JS source files and assets.

Make sure you've also created a developer certificate according to the instructions in the portal.

Once you have these, it's a good idea setup your command-line environment to use them. For example on MacOS and assuming you installed mlsdk v0.20.0, add the following to your shell startup config.


source $HOME/MagicLeap/mlsdk/v0.20.0/
export MLCERT=/path/to/downloaded/certificate.cert


SET MLCERT=c:\path\to\downloaded\certificate.cert

Verify that you have mldb and mabu in your path and that $MLCERT is set and points to your developer certificate.


  • mldb - If you setup everything right. Go to your terminal and type mldb. You should see a list of commands available through Magic Leap Debug Bridge(mldb). If for some reason you don’t see anything please refer yourself to official documentation. Connecting device and MLDB Overview

  • mabu - If you setup everything right. Go to your Terminal and type mabu. You should see a list of available commands. Mabu Overview

  • certificate - If you setup everything right. As a successful output you should see a path to your certificate. Open Terminal and do the following:


    echo $MLCERT


    echo %MLCERT%

MagicScript CLI Tool

In addition to the SDK, there is a helpful command-line tool known as magic-script that helps with MagicScript applications.

This tool is written using node.js. Make sure you have node and then install the CLI tool with npm.

Easiest way to check if you have node installed and properlly configured is to run following command in your terminal:

node -v

As output you will see node version.

*If you don't see node version, considering doing reboot of your PC.

npm install --global magic-script-cli

Verify this worked by checking for magic-script in your path.


  • magic-script - Open up your terminal and do input mentioned below. As a successful output you should see a path where mxs cli tool is being stored. The path may vary depending on npm installation. It won't affect development. Input:


    input: which magic-script

    output: /usr/local/bin/magic-script


    input: where magic-script

    output: C:\Program Files\nodejs\magic-script

    output: C:\Program Files\nodejs\magic-script.cmd

Create a new Project

For your first project, use the magic-script init command to generate a scaffold from a template:

  1. If your environment correctly set for Magic Script Development, you should see following message in your terminal.

*This name will be displayed on ML1 IconGrid.

? What is the name of your application?
  1. Next you need to enter your application ID. We need this to track your application processes inside Lumin OS.

*Use only lowercase characters.

Good example: com.mxs.myapp

Bad example:$.M9@pP1

? What is the app ID of your application?
  1. For more convenience we add this step that helps keep all project files in the same folder.
? In which folder do you want to save this project?
  1. Now it’s time to select project type. We have three options here:
  • Landscape - In the Landscape, users can customize their environment and create a seamless experience between the digital and physical world. Applications can co-exist, persist between sessions, and become a part of the environment that a user experiences by default. You can read more about Landscape Applications here.

  • Immersive - When launched, Immersive Apps hide Landscape Apps and take over the mixed reality experience for your space. Only one Immersive App can run at a time. You can read more about Immersive Applications here.

  • Components - Will create a Landscape application using Magic Script Components Framework. You can read more about Framework here.

? What app type do you want? (Use arrow keys)
> Landscape

Template changes over time, but it generates a tree structure something like this:

├── .out
├── bin
├── node_modules
├── res
└── src
├── app.js
└── main.js
├── .eslintrc.js
├── .npmignore
├── app.mabu
├── app.package
├── digest.sha512.signed
├── manifest.xml
├── package-lock.json
├── package.json
├── rollup.config.js
├── tsconfig.json

The manifest.xml file is pre-populated with the values set in the init command and most the other top-level files are build configuration and package metadata. The interesting part is the src/app.js file where customized code goes.

Open this folder in your favorite code editor. We recommend Visual Studio Code.

Build and Install

Build and install your application by attaching your device and running the following in your new project folder:

# Enter the project directory
cd my-app
# Plugin in device and verify it's connected
mldb devices
# Build and install the application onto the device.
magic-script build -i

For your information, This internally performs several steps:

  • Installs local npm dependencies with npm install to get rollup and plugins.
  • Uses rollup to bundle src/*.js into bin/*.js with rollup -c
  • Generates a bin/index.js executible with the #!/system/bin/script/mxs shebang line that imports user code.
  • Generates digest.sha512.signed which is a digest of all files in bin/*.js signed by your developer certificate.
  • Uses mabu build ... to bundle this into a mpk.
  • Uses mldb install ... to install the mpk on the device.

Run Application

On device

Run your application in debug mode with:

magic-script run

Internally this does a couple things:

  • Launches the app using mldb launch ....
  • Reads the output of mldb log to see the web inspector port and forwards it over USB to a local port using mldb forward ....

If all goes well, you'll eventually see a success message and a chrome-inspector url that can be copy-pasted into Chrome to remotely debug the application.

In Zero-Iteration

Run your app on the Simulator without a device.