A VS Code extension for making retro-style video games with Microsoft MakeCode Arcade. Code, create pixel art, and play your game in both native VS Code and vscode.dev!
To start a new MakeCode project in VS Code, you first need to open an empty folder (File > Open Folder).
Note: In vscode.dev, the File menu is located in the hamburger button in the top-left corner of the page.
Once you've opened a folder, you can create an empty project by clicking the "Create a New Project" command in the MakeCode Asset Explorer.
If you have a share link for a MakeCode Arcade project, you can also import it by clicking the "Import Project from URL" command and pasting the URL in the input that appears.
If you have opened a GitHub repository that contains a MakeCode Arcade project, you'll need to install your project's dependencies for features like intellisense to work. Click the "Install project dependencies" command in the actions section of the MakeCode Asset Explorer to download and install them.
Note: You must be connected to the internet in order to download and install extensions
You can access the MakeCode Asset Explorer by clicking on the MakeCode icon in the Visual Studio Code action bar.
At the top of the asset explorer you'll find a list of commands for managing MakeCode Arcade projects. Click on a command to run it!
Inside your MakeCode project, you'll see a folder structure that looks something like this:
project/
├─ built/
├─ main.ts
└─ pxt.json
...
Don't worry if you don't see all of these files or if your project contains more than what's listed here! We're just going to go over the important ones first:
built/
contains all of the compiled code for your project. If you compile your project, the result will show up inside this directory.main.ts
is the main code file for your project. This code will run when you run your game.pxt.json
is the file that configures your project. More on that below!Some other files you might see in your project include:
*.jres
and *.g.jres
- these files contain the assets for your project like images, animations, songs, and tilemaps. See "Managing your project's assets" below for more information on assets.*.g.ts
- these files are autogenerated when the assets for your project change. Don't edit these by hand!README.md
- this is a markdown file where you can add documentation for your project that other people can read when they import it.main.blocks
- if you imported your project, it might have a blocks file inside. You can't edit this file inside of VS code!tsconfig.json
- this file is required to make features like intellisense work in the editor. You probably don't need to edit it!.github
, mkc.json
, .vscode
, .gitignore
, .prettierrc
, assets.json
- These are all advanced configuration files. You can safely ignore them!pxt.json
is a very important file that is required in all MakeCode projects. Be careful when editing this file! If it isn't valid JSON or is missing required fields, your project might stop working. Always check for errors before saving it!
Some of the important fields include:
device
extension; make sure not to remove it if you want your project to work with MakeCode Arcade!.ts
, .jres
, .g.ts
, .g.jres
, and .md
files should be listed here.Whenever you create a new file that you want to be included in your project, you need to add it to the files entry inside pxt.json
. If you aren't seeing your changes when you run your game, make sure you didn't leave a file out!
Click the "Start MakeCode Simulator" command in the MakeCode Asset Explorer to run your game inside of VS Code. A new view pane will open after the project has finished compiling and will automatically reload whenever you save a file in the open workspace.
To use your keyboard to control the simulator, make sure you first click on the simulator pane so that it has focus.
All serial messages and exceptions from the simulator are printed in VS Code's output view pane. If the output view pane is hidden, you can open it from the View menu in the top bar (View > Output).
Note: In vscode.dev, the View menu is located in the hamburger button in the top-left corner of the page
Once the pane is visible you can view all MakeCode messages by selecting "MakeCode" from the dropdown in the top-right:
All of your projects images, tilemaps, animations, and songs will be listed inside the MakeCode Arcade Asset Explorer. Clicking on an asset from this list will open the asset editor. Any changes made to an asset inside of this editor will be automatically saved in your project.
To create a new asset, hover over the asset type in the MakeCode Asset Explorer and click the "Create File" icon that appears:
To edit an existing asset, click on its name in the asset explorer to open it in the asset editor. To rename an asset, change its name in the text input that appears in the bottom of the asset editor. If you don't see the text input, you may need to increase the width of the pane that the asset editor is in.
When you hover over the name of an asset, two icons will appear next to it:
Clicking the trash can icon will delete the asset from your project. Be careful, there is no undo for this operation!
Clicking the copy icon will duplicate the asset and open the copy in the asset editor.
To reference an asset you've created inside your code, you can use the name you gave it with one of the tagged templates on the assets
namespace:
let myImage = assets.image`imageName`;
let myAnimation = assets.animation`animName`;
let myTile = assets.tile`tileName`;
let myTilemap = assets.tilemap`tilemapName`;
let mySong = assets.song`songName`;
You can also create or edit an asset referenced in code using Code Actions:
To add a MakeCode extension to your project, click the "Add an Extension" command in the actions section of the MakeCode Asset Explorer. Then either select an extension from the list that appears or paste a GitHub URL for an extension repo in the text input and press Enter.
Note: You must be online to add an extension to your project
After you add an extension to your project, an entry for it will automatically appear inside your pxt.json
file.
To remove an extension, run the "MakeCode: Remove an Extension" command in the VS Code command palette and select the extension to remove.
If you manually edited your project's pxt.json
file and need to reinstall the project's dependencies, click the "Install Project Dependencies" command in the actions section of the MakeCode Asset Explorer.
To compile your project and download it to hardware (e.g. a Meowbit), first run the "Build Project for Hardware" command in the actions section of the MakeCode Asset Explorer. Once the compile finishes, you can find the generated hex/uf2 file under the built/
folder in your project workspace. Depending on what hardware you selected to compile for, the file may be under a subdirectory (e.g. built/n3/binary.hex
). The file will be named either binary.hex
or binary.uf2
.
Right click on the uf2/hex file in your built/
folder and select "Reveal in File Explorer" or "Reveal in Finder" to locate the downloaded file on your computer:
Connect your hardware to the computer with a USB cable. It should appear as a USB drive in your computer's file explorer. If you don't see the USB drive, see "Troubleshooting hardware connections" below.
Drag the file you located into the USB drive for your hardware. It should automatically reset and load with your compiled game.
Right click on the uf2/hex file in your built/
folder and select "Download..." to download the uf2/hex file to your computer:
Connect your hardware to the computer with a USB cable. It should appear as a USB drive in your computer's file explorer. If you don't see the USB drive, see "Troubleshooting hardware connections" below.
Drag the file you downloaded into the USB drive for your hardware. It should automatically reset and load with your compiled game.
If your hardware is failing to show up as a USB drive when you plug it in, try the following steps:
To create a MakeCode share link for your project, click the "Create MakeCode Share Link" command in the MakeCode Asset Explorer. This will cause the output pane to open with a link that you can copy/paste.
To change the name of your shared project, see the pxt.json
section above.
See the developer guide for info on developing vscode-makecode.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.