Scribd
Upload
14 views4 pages

Develop MakeCode Extensions with TypeScript

This document provides a guide on using VS Code and TypeScript to develop MakeCode extensions with custom annotations. It covers the prerequisites, setup process, writing custom annotations, testing extensions, and emphasizes the importance of compile-time metadata for block generation. Key takeaways include the separation of function logic from block metadata and the iterative development workflow without forking the PXT repository.

Uploaded by

aeagan0507
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
14 views4 pages

Develop MakeCode Extensions with TypeScript

This document provides a guide on using VS Code and TypeScript to develop MakeCode extensions with custom annotations. It covers the prerequisites, setup process, writing custom annotations, testing extensions, and emphasizes the importance of compile-time metadata for block generation. Key takeaways include the separation of function logic from block metadata and the iterative development workflow without forking the PXT repository.

Uploaded by

aeagan0507
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

Using VS Code and TypeScript to Develop

MakeCode Extensions with Custom Annotations

1. Overview
This document shows how to:

1. Use VS Code for editing TypeScript for MakeCode Arcade.


2. Write and test code without merging or forking the PXT repository.
3. Create your own annotations (like //% myCustomAnnotation ) for controlling parameters.
4. Connect your TypeScript directly to MakeCode for block generation and runtime execution.

Key Concept: MakeCode reads annotations at compile-time, not runtime. Extensions must
expose metadata correctly for blocks to work.

2. Prerequisites
• VS Code installed – [Link]
• [Link] installed – [Link]
• MakeCode Arcade project template – online or locally.
• Basic knowledge of TypeScript and MakeCode block annotations ( //% ).

3. Set Up a MakeCode Extension


1. Create a folder for your extension, e.g., my-extension .
2. Inside, create [Link] :

{
"name": "my-extension",
"description": "My custom MakeCode extension",
"dependencies": {},
"files": [
"[Link]"
]
}

1. Create [Link] :

1
namespace myExt {

//% block="shoot projectile at $x $y"


//% myCustomAnnotation=optional
export function shootProjectile(x: number, y?: number) {
// Engine logic goes here
}

myCustomAnnotation is a new annotation to be processed in compileInfo or


equivalent PXT metadata handler.

4. Linking VS Code to MakeCode


1. Open the MakeCode Arcade project folder in VS Code.
2. Create a subfolder for extensions:

project/
├─ [Link]
├─ my-extension/
│ ├─ [Link]
│ └─ [Link]

1. In the project, import your extension in [Link] :

//% color="#AA00AA"
namespace myExt { }

• MakeCode automatically loads extensions in the folder.


• No need to fork or merge the PXT repo.

5. Writing Custom Annotations


1. Add annotations as comments above functions or parameters:

//% block="move tank $x $y"


//% myOptionalParam=y
export function moveTank(x: number, y?: number) { }

1. Extend metadata parsing by overriding compileInfo in your extension:

2
function parseMyAnnotations(fn: any) {
const annotations = [Link] || {};
if ([Link]) {
// mark parameter as optional in BlockCompileInfo
}
}

• This tells MakeCode to treat your annotation at compile-time.

6. Testing Your Extension in MakeCode


1. Run the MakeCode Arcade simulator.
2. Check that your custom blocks appear and optional parameters behave as intended.
3. Update compileInfo mapping if needed.

MakeCode reads annotations statically from module metadata, not runtime logic.

7. Iterative Development Without Forking


• Edit TypeScript in VS Code
• Save → MakeCode detects changes in your extension
• Simulate and test in online editor or local simulator

Tips:

1. Keep extension code in a separate folder.


2. Only modify metadata parsing or annotation handling inside your extension.
3. Never touch pxt-common-packages ; your extension can be fully independent.

8. Diagram: Flow from TypeScript → MakeCode

┌───────────────┐
│ [Link] / │ <- Your TypeScript code with //% annotations
│ [Link] │
└───────┬───────┘
│
▼
┌─────────────────────┐
│ PXT Compiler │
│ - Reads annotations│
│ - Generates │

3
│ BlockCompileInfo │
└───────┬─────────────┘
│
▼
┌─────────────────────┐
│ MakeCode Blocks │
│ - Optional params │
│ - Field editors │
│ - Shadow blocks │
└───────┬─────────────┘
│
▼
┌─────────────────────┐
│ Simulator / Device │
│ - Executes runtime │
│ - Uses engine code │
└─────────────────────┘

• Shows how TypeScript + annotations feed the block system.


• Custom annotations are read at compile-time.

9. Key Takeaways
1. Function logic ≠ block metadata — annotations are static.
2. Use VS Code to write TypeScript in an extension folder.
3. No need to fork PXT; add your extension locally.
4. Custom annotations require metadata parsing.
5. Iterative workflow: edit TS → save → test in simulator.

Common questions

Powered by AI

The significance of compile-time over runtime in the context of TypeScript annotations for MakeCode lies in the way metadata is handled. Annotations are parsed at compile-time, which means that all necessary block metadata, such as optional parameters and block properties, are resolved and set before any execution takes place. This approach eliminates the need for runtime logic to handle metadata, thus reducing potential errors and improving performance by ensuring that blocks are fully configured and recognized by the MakeCode environment beforehand .

The PXT compiler plays a crucial role in MakeCode extension development by reading custom annotations in TypeScript at compile-time. It generates BlockCompileInfo, which includes parsed information about blocks, optional parameters, and field editors. This information facilitates the automatic creation and management of MakeCode blocks, which get integrated into the visual programming environment. By processing custom annotations, the PXT compiler allows developers to define how functions are represented in MakeCode, without requiring runtime interpretation .

Custom annotations influence the handling of optional parameters in MakeCode blocks by allowing developers to specify metadata that defines which parameters should be treated as optional at compile-time. This is achieved by including annotations like //% myOptionalParam or using functions like parseMyAnnotations to mark parameters accordingly. As a result, when the PXT compiler reads these annotations, it generates block metadata that instructs MakeCode to present these parameters as optional in the block representation, creating more flexible and user-friendly blocks .

It is unnecessary to fork or merge the PXT repository because MakeCode is designed to automatically load extensions from the local project folder. As long as the extension is correctly set up with a folder containing necessary files like main.ts and pxt.json, MakeCode can read these extensions directly without needing changes in the centralized PXT repository. This promotes ease of development and iterative testing .

Custom annotations in TypeScript are used in MakeCode Arcade to control block generation and function metadata. These annotations are read at compile-time by the PXT compiler, not at runtime. This means that any custom annotation, like //% myCustomAnnotation, is parsed and recognized through functions like parseMyAnnotations, which influence the optional parameters in the generated block metadata. This process allows developers to customize how their functions are represented as blocks in the MakeCode environment without altering function logic .

The prerequisites for developing a MakeCode extension using VS Code and TypeScript include having VS Code and Node.js installed, as well as a MakeCode Arcade project template available either online or locally. Additionally, a basic understanding of TypeScript and MakeCode block annotations is necessary to effectively write and test the code .

Linking VS Code to a MakeCode Arcade project involves creating an appropriate folder structure where the extension files, such as main.ts and pxt.json, reside within subfolders in the project directory. This linkage allows the developer to directly edit TypeScript code within VS Code and leverage features like syntax highlighting and error checking. The importance of this integration is that it streamlines the development process, enabling real-time editing and testing without additional configuration steps, as the MakeCode environment automatically reflects these changes .

To test a MakeCode extension after modifying its TypeScript code, you simply need to save your changes in VS Code. MakeCode automatically detects these changes and updates the corresponding blocks. The extension can then be tested using the MakeCode Arcade simulator or a local simulator to ensure that the custom blocks appear and function as intended .

The recommended iterative development strategies for testing MakeCode extensions include editing the TypeScript code in VS Code and immediately saving the changes, which are then detected by MakeCode. The updated extensions can be tested in the MakeCode Arcade simulator to ensure correct functionality. Developers are advised to keep extension code separate to avoid modifying core packages. This iterative workflow allows for quick testing and debugging cycles, enabling efficient fine-tuning and improvement of the extension features .

Creating a separate folder for extensions when developing in MakeCode Arcade serves to organize the project structure and isolate extension-specific code. This ensures that the main project files remain untouched and allows for cleaner management of extension logic, making it easier to update or change extension-specific code without impacting the main application. This also aligns with MakeCode's design, which automatically loads extensions from folders, facilitating seamless integration .

You might also like