microsoft / pxt

Microsoft MakeCode (PXT - Programming eXperience Toolkit)

Microsoft MakeCode

• Try out the editors in your browser...

Microsoft MakeCode is based on the open source project Microsoft Programming Experience Toolkit (PXT). Microsoft MakeCode is the name in the user-facing editors, PXT is used in all the GitHub sources.

PXT is a framework for creating special-purpose programming experiences for beginners, especially focused on computer science education. PXT's underlying programming language is a subset of TypeScript (leaving out JavaScript dynamic features).

The main features of PXT are:

• a Blockly-based code editor along with converter to the text format
• a Monaco code editor that powers VS Code, editor's features are listed here.
• extensibility support to define new blocks in TypeScript
• an ARM Thumb machine code emitter
• a command-line package manager

More info:

• About
• Documentation

Examples of Editors built with MakeCode:

• https://makecode.microbit.org
• https://arcade.makecode.com
• https://makecode.adafruit.com
• https://minecraft.makecode.com
• https://makecode.mindstorms.com
• https://makecode.chibitronics.com
• More editors at https://makecode.com/labs

Branches

• master is the active development branch, currently v3.* builds
• v* is the servicing branch for v*.* builds

Running a target from localhost

Please follow the instructions here.

Linking a target to PXT

If you are modifying your own instance of PXT and want a target (such as pxt-microbit) to use your local version, cd to the directory of the target (pxt-microbit, in our example, which should be a directory sibling of pxt) and perform

pxt link ../pxt

If you have multiple checkouts of pxt, you can do the following:

• run npm i in pxt and the target
• in the target, run pxt link ..\some-other-pxt (you may need to update your CLI first by running npm install -g pxt)

If you run npm i afterwards (in either the target or pxt), you might need to repeat these steps.

Build

First, install Node: minimum version 8.

To build the PXT command line tools:

npm install
npm run build

Then install the pxt command line tool (only need to do it once):

npm install -g pxt

Then install gulp (only need to do it once):

npm install -g gulp

After this you can run pxt from anywhere within the build tree.

To start the local web server, run pxt serve from within the root of an app target (e.g. pxt-microbit). PXT will open the editor in your default web browser.

If you are developing against pxt, you can run gulp watch from within the root of the pxt repository to watch for changes and rebuild.

gulp watch

If you are working on the CLI exclusively,

gulp watchCli

If you don't need to build the suite of associated webapps (skillmap, multiplayer, etc.), you can skip them and speed up your build a bit:

gulp --no-webapps

Icons

There are a number of custom icons (to use in addition to http://semantic-ui.com/elements/icon.html) in the svgicons/ directory. These need to be 1000x1000px. Best start with an existing one. To see available icons go to http://localhost:3232/icons.html (this file, along with icons.css containing the generated WOFF icon font, is created during build).

If you're having trouble with display of the icon you created, try:

npm install -g svgo
svgo svgicons/myicon.svg

Shared Styling

When adding a CSS color or other style element that will be shared across editor targets (e.g. micro:bit, Arcade) and sub-applications (a.k.a. "CRAs", like skillmap, teachertool, etc.). Declare a CSS variable for it in theme/themepacks.less:

1. Add the new variable to the :root pseudo-class. Choose a reasonable default value according to the guidlines in the file.
2. Add the new variable to all theme classes defined in that file. At the time of this writing, only theme-highcontrast is defined. Choose a value that works well for the given theme.
3. Add the new variable to the theme overrides for each target. This will be done in the target repo's theme/themepacks.less file (e.g. pxt-microbit, pxt-arcade).

Variables declared this way will be available to CRAs at runtime, and they will be initialized with the override values defined by the target in which they're running.

Documentation Highlighting

In the documentation, highlighting of code snippets uses highlight.js (hljs). Currently, the following languages are included:

• TypeScript
• Python
• JavaScript
• HTML,XML
• Markdown

If you need to add other languages or update existing ones, you can find the distribution at https://highlightjs.org/download/; select all the languages you want to include (including the ones above!), download and unzip, and finally copy over highlight.pack.js into webapp/public/highlight.js/.

Tests

The tests are located in the tests/ subdirectory and are a combination of node and browser tests. To execute them, run npm run test:all in the root directory.

License

MIT License

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Contact Us

Get in touch

Trademarks

MICROSOFT, the Microsoft Logo, and MAKECODE are registered trademarks of Microsoft Corporation. They can only be used for the purposes described in and in accordance with Microsoft’s Trademark and Brand guidelines published at https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general.aspx. If the use is not covered in Microsoft’s published guidelines or you are not sure, please consult your legal counsel or MakeCode team ([email protected]).

pxt's Issues

@param comment causing custom libs to fail to load

I'm defining this function in a custom lib:

    /**
     * Match string against regular expression
     * param input The input string, eg: "Hello, World!"
     * @param pattern The regular expression, eg: "^Hello"
     */
    //% blockId="str_matches" block="%input|matches %pattern"
    export function matches(input: string, pattern:string) : boolean { return false; }

If I place an @ in front of the first param entry in the comment, then all custom libs will fail to load in the editor when I refresh the page.

need finer grain control over blocks

Need to be able to hide built-in blocks as well as put some in my own namespace.

add //%flag to hide entry from TS autocompletion

Some methods are only for blocks really, especially ones using enums

support for virtual JS methods in Thumb

Will require a virtual method table etc

It will also need to be implemented in JS, but there it's trivial.

ARM vs Javascript compilation

We should identify the ARM specific features vs Javascript only features and separate them to provide an optimized experience in both cases.

For example, JSON support is built-in javascript but not required in ARM, etc...

Stray shadow numbers

This may be a bug in blockly. In my branch of pxt-sample, I've defined a class as a type that can be assigned to a blockly variable. Using it, I've found a way to create shadow number blocks that are undeletable:
1: Drop a Logic/assignment block
2: Define a block that returns the custom class mentioned above.
3: Drag this block to either argument of the assignment block and attach.
Result: Shadow number wlil pop out and be undeletable from the workspace.
Expected: Shadow number would disappear, or be deletable.

after script uninstall there is 404 console error from pouchdb

generated sims.d.ts missing reference to enums.d.ts

Assuming the user has a enum file in the libs, the sims.d.ts should add a reference to it.

support for lambdas returning values

This requires some work, especially on the ARM side

hardware debugger support

See https://github.com/Microsoft/dapjs

Some steps to implement

• collect all addresses of 'bl' instructions - look for them on the stack to delimit stackframes
• With every BL instruction include stack size - after we find one we should be able to find the others easily
• Have 'status' global variable to enable 'debugger' stmts; have debugger write it - could be first global variable
• Thread switching - get list of active threads, maybe restore them? Or maybe just look in the data structures

Create Project Cancel Button (Not the X) does not work. You have to click X

support direct binding to C++ class methods

They have different calling convention.

Implement IsEmpty for string type

Convenience method for brevity and readability.

auto-generate shims.d.ts from simulator files

We currently only generate it from .cpp files, but we should be able to also do it from simulator files. This reduces needs for #26

CC @pelikhan

Login needed for demo at kindscript.com

• Open https://kindscript.com/
• See :

Perhaps a demo username / password should be mentioned in the readme 🌹

Undo: Does not work 100% of the time

Undo failed to remove added block. Sometimes it works but not consistently.
a. Add 2 Blocks (Clear screen and Show String)
b. Move the above blocks together
c. Add a 3rd block (Show Number) and drop right under shows string
d. Click Undo x 2 and the Show number goes away
e. Add 3rd block again (Show String and drop under 2nd block)
f. Click Undo (as many times as you want)
The block may not be removed * 30-50% of the time the block is removed**

implement list blocks

• compile to javascript
• decompile from javascript

string leak when using ? : operator

When running this script,

let x = 0;
basic.showString(true ? x.toString(): "a")

we get

Live String: "0" refcnt= 1

Also, we don't seem to clear those "live string" counter when we restart the script?

ProjectView.render() throws React warning

Because we load editor file from there. Do it with nextTick?

implement 3-way merge for workspace sync

Right now, we take the latest version. This may become more of an issue when we support cloud workspaces more widely.

support for specifying floating point in target

A target should be able to enable floating point math.

surface runtime errors in code

An API that allows the runtime (simulated or hardware) to surface a runtime issue in the code editor. We had a simular feature in TD.

• message passing support for surfacing messages from simulator or debugger interface
• API to report an error
• walk the stack back under the first user frame is found
• display in javascript editor (Sam)
• display in block editor (peli)

Argument of type string[] in a block definition breaks category.

When string[] appears in a block definition it will not load correctly, making the entire category unusable. Example:

    /**
     * Prompt the user to choose from a list of choices.
     * @param choices The choices to present to the user.
     * @param prompt The prompt, eg: "Select a color:"
     */
    //% async
    //% blockId="bots_choose" block="choose from %choices|with prompt %prompt"
    export function choose(choices:string[], prompt:string): string { return ""; }

When on Code Mode, I was not able to edit any part of the code

Create Block Code
Switch to -Show Code
Try to edit
Result: Cannot edit any part of the code

Right Click>> Help: Missing Page - Control

Add Create Big Image
Right Click on the control
Click Help
Result: Page not found

clear ref-counted locals vars when out of scope

For example:

if (...) {
  let x = "a" + "b"
  ...
  // implict 'x = null' here
}

This can free significant amount of memory, especially if 'x' happen to be outside of any function.

Need ability to set height of simulator area

For my pxt target (bot framework), the intention is to host a chat control in the simulator area for interfacing with the bot. The simulator area is a fixed size, but currently too small vertically to host a usable chat control. One solution would be to provide the ability to change the height of the simulator.

split localstorage per-target

For cases when several targets are deployed under a single domain (eg github pages), we need to avoid sharing local storage or workspace between target.

• use localStorage[targetName + ":foo"] instead of localStorage["foo"]
• only remove the releavent keys, not localStorage.clear() on logout
• use target name as the pouchdb name
• update docs that warn about this (docs/staticpkg.md)

Comment Scrollbars appear twice

Add Comment to Create Big Image
Type a long comment - at least 5 lines
Result: Scroll bar shows twice

SSL cert for kindscript.com is invalid

Chrome is rejecting the SSL certificate issued for kindscript.com. The error is included below:

Your connection is not private

Attackers might be trying to steal your information from kindscript.com (for example, passwords, messages, or credit cards). NET::ERR_CERT_COMMON_NAME_INVALID

Macbook Air mid 2012
OS X Yosemite : 10.10.5
1.8GHz Core i5
8GB RAM
Version 48.0.2564.116 (64-bit)

cancel button text does not trigger click

Click on Cancel (Not X) nothing happens (X does cancel)

microbit images method not support in blocks.

I found those BugblockId annotations. Is this supported?

https://github.com/Microsoft/pxt-microbit/blob/master/libs/microbit/images.cpp#L41

pxt-microbit test suite getting 429

Yes, rate limiting works!...

*** nvogiv.ts, size=83
*** nujrlc.ts, size=966
ERROR nqxloa: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nqxloa/text; message: {"message":"Too Many Requests"}
ERROR nsaumh: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nsaumh/text; message: {"message":"Too Many Requests"}
ERROR nrjdzu: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nrjdzu/text; message: {"message":"Too Many Requests"}
ERROR nqgyno: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nqgyno/text; message: {"message":"Too Many Requests"}
ERROR npkjbk: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/npkjbk/text; message: {"message":"Too Many Requests"}
ERROR nqdtvd: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nqdtvd/text; message: {"message":"Too Many Requests"}
ERROR noyovd: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/noyovd/text; message: {"message":"Too Many Requests"}
*** ntfmsx.ts, size=252
ERROR novevx: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/novevx/text; message: {"message":"Too Many Requests"}
ERROR noxyjg: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/noxyjg/text; message: {"message":"Too Many Requests"}
ERROR noikvz: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/noikvz/text; message: {"message":"Too Many Requests"}
ERROR noftar: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/noftar/text; message: {"message":"Too Many Requests"}
ERROR nmdfik: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nmdfik/text; message: {"message":"Too Many Requests"}
ERROR nmuhlk: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nmuhlk/text; message: {"message":"Too Many Requests"}
ERROR nmbxkh: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nmbxkh/text; message: {"message":"Too Many Requests"}
ERROR nlyuwy: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nlyuwy/text; message: {"message":"Too Many Requests"}
ERROR nkdbmy: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nkdbmy/text; message: {"message":"Too Many Requests"}
ERROR njynsd: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/njynsd/text; message: {"message":"Too Many Requests"}
ERROR njvcbs: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/njvcbs/text; message: {"message":"Too Many Requests"}
ERROR njfeff: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/njfeff/text; message: {"message":"Too Many Requests"}
ERROR nitcfc: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nitcfc/text; message: {"message":"Too Many Requests"}
ERROR nikzhg: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nikzhg/text; message: {"message":"Too Many Requests"}
ERROR nhtyzy: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nhtyzy/text; message: {"message":"Too Many Requests"}
ERROR nghraa: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nghraa/text; message: {"message":"Too Many Requests"}
ERROR nhpyof: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nhpyof/text; message: {"message":"Too Many Requests"}
ERROR ndqgow: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/ndqgow/text; message: {"message":"Too Many Requests"}
ERROR nfjrxg: Bad HTTP status code: 429 at https://www.microbit.co.uk/api/nfjrxg/text; message: {"message":"Too Many Requests"}

support class field initializers

Classes name ends up being "Thing"... always

Try

class Foo {}

new Foo()

Clicking main.blocks when main.ts has errors results in data loss without warning

1. Make a new blocks project
2. Show files
3. Add an "if" block
4. Show code
5. Change "if" to "idf"
6. Click main.blocks file
7. Notice "if" block is gone

Expected to see the warning dialog.

analytics should be configurable

Seperate targets should be able to provide different analytics.

• support analytics settings from pxtarget.json
• rewrite index.html
• rewrite run.html

Account Options is not working

Login
Click under your name
Click Account Option
Result: Nothing happens

Need A+B on Screen Button

Need A+B Button on screen

add sample docs to pxt-sample

Usage of cards etc

generate strings.json from API signatures

To complete the localization story, we need to:

• extract all commands from the various shim definition files in a target (Michal)
• generate a "strings.json" file that can be localized (Michal)
• package the localized "strings.json" file tree produced by the localization tool (Peli)
• load target specific strings into the web editor (Peli)

show help for specific arguments

we currently only show help in auto-completion for the entire method not specific parameters

implement export to TypeScript with async/await

Right now, we do not generate human-readable JavaScript/TypeScript. We could.

Build status badge broken

When going through the README I noticed that your repositories "build status badge" from Travis CI is broken.

Looks like it is linking to the old name of the repo? Either way, it doesn't look like CI has been set up for the project under this name.

implement text blocks

Support for string manipulation

• pxtarget.json configuration
• compile to javascript
• decompile from javascript
• comparison operators
• concat operators
• literals

Need Button to Simulate Shake

Need to have a Shake button on the screen to simulate Shake

better UI for simulator debugger in TS editor

add auto-fix for parenthasis

prevent decimal numbers in blocks

When not supported (like microbit), floating point numbers should not be allowed.

simulator auto-restarts too eagerly

Scenario:

• make a change
• hit stop, start to see the change (manual restart)
• simulator starts running
• after a few seconds simulator restarts again (auto-restart)