diff --git a/README.md b/README.md index 2d1bdb5..00bd05d 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,128 @@ -# Microsoft MakeCode extension for vscode.dev +# Microsoft MakeCode extension for Visual Studio Code -This repo contains a vscode web extension for creating and editing MakeCode Projects. +## Opening the MakeCode Asset Explorer -## Using the extension +You can access the MakeCode Asset Explorer by clicking on the MakeCode icon in the Visual Studio Code action bar. -### Create a new project +![Screenshot of the VS code action bar with an arrow pointing to the MakeCode Arcade Asset Explorer](./images/action-bar.png) -1. Open an empty folder where you want your new project to live -2. Run the "MakeCode: Create empty project" command from the command palette -3. Select the desired MakeCode target from the list that appears +## Running actions in the MakeCode Asset Explorer -### Import a share link +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! -1. Open an empty folder where you want your imported project to live -2. Run the "MakeCode: Import project from URL" command -3. Paste the share URL into the text input that appears and press enter +![Screenshot of the MakeCode Asset Explorer with a red box around the command list](./images/command-list.png) -### Run your project in the simulator +## Starting a new project -To run your project in the simulator, run the "MakeCode: Start MakeCode simulator" command. -This will also start a file watcher that will automatically reload the simulator whenever you change a file. -To use your keyboard to control the simulator, make sure you have the simulator pane focused. +To start a new MakeCode project in VS Code, you first need to open an empty folder (File > Open Folder). -#### Viewing the simulator console +> Note: In vscode.dev, the File menu is located in the hamburger button in the top-left corner of the page. -All serial messages and exceptions from the simulator are printed in vscode's output view pane. +Once you've opened a folder, you can create an empty project by clicking the "Create an empty project" command in the MakeCode Asset Explorer. -1. Open the "Output" view pane (View > Output in the top bar). -2. In the top-right of the pane that appears, change the dropdown to "MakeCode". +### Importing an existing MakeCode project -### Managing your project assets (images, tilemaps, animations, etc.) +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. -The asset explorer can be accessed by clicking the MakeCode logo located in vscode's "Action Bar". -Inside the explorer, there are collapsible sections for each type of project asset. +### Opening an existing GitHub project -> Important: when editing an asset, be sure to press the "Done" button in the bottom right of the asset editor to save your work +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. -#### Creating an asset +> Note: You must be connected to the internet in order to download and install extensions -To create a new asset, hit the "Create File" icon next to the asset type in the asset explorer. +## Anatomy of a MakeCode project -#### Editing assets +Inside your MakeCode project, you'll see a folder structure that looks something like this: -To edit an existing asset, click on its name in the asset explorer. +``` +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 + +`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: + +* **name** - The name of the project. When you create a share link, this name is what people will see. Try to make it descriptive! +* **description** - A description of your project. +* **dependencies** - This field contains all of the extensions used by your project. To add/remove an extension, see the sections below. By default, all arcade projects depend on the `device` extension; make sure not to remove it if you want your project to work with MakeCode Arcade! +* **files** - This is a list of the files in your project. All `.ts`, `.jres`, `.g.ts`, `.g.jres`, and `.md` files should be listed here. +* **palette (optional)** - This optional field can be used to change the 15 colors that MakeCode Arcade uses for its color palette. More information [here](https://arcade.makecode.com/developer/images). +* **version (optional)** - This optional field is used to set the version of your project. Versions should be in the from 0.0.0 (aka [semantic versioning](https://semver.org/)). This field is mostly just for extensions. +* **testFiles (optional)** - This optional field lists files to include when building the project itself, but not include when the project is added to another project as an extension. It's useful for testing out your code if you are authoring an extension. + +### Adding a file to your project + +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! + +## Run your project in the simulator + +![Screenshot of VS Code with the MakeCode simulator open and the "Start MakeCode simulator" command highlighted](./images/simulator-pane.png) + +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. + +### Viewing the simulator console + +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: + +![Screenshot of VS Code with the output pane open and a red arrow pointing to a dropdown with MakeCode selected](./images/output-pane.png) + + +## Managing your project assets + +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. + +### Creating an asset + +To create a new asset, hover over the asset type in the MakeCode Asset Explorer and click the "Create File" icon that appears: -To duplicate or delete the asset, click on the icons that appear next to its name when you hover over it. +![Screenshot of the MakeCode Asset Explorer with a red arrow pointing to the create icon in the images section](./images/create-new-asset.png) -To rename the 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 (this is a known bug). +### Editing assets -#### Referencing your assets inside your code +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. -To reference an asset you've created inside your code, use one of the tagged templates that MakeCode defines: +![Screenshot of VS Code with the asset editor open to a cat sprite and a red box around the asset name.](./images/asset-rename.png) + +### Deleting and duplicating assets + +When you hover over the name of an asset, two icons will appear next to it: + +![Screenshot of the MakeCode Asset Explorer with a red square around two icons next to the name of an image asset](./images/duplicate-delete.png) + +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. + +### Referencing assets inside your code + +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: ```ts let myImage = assets.image`imageName`; @@ -60,71 +132,62 @@ let myTilemap = assets.tilemap`tilemapName`; let mySong = assets.song`songName`; ``` -### Adding a dependency to your project - -To add a MakeCode extension to your project, add an entry in the dependency map inside your project's `pxt.json`. - -For example, to add the [character-animations](https://github.com/microsoft/arcade-character-animations) extension the entry should look like this: - -```json -{ - "name": "Untitled", - "description": "", - "dependencies": { - "device": "*", - "arcade-character-animations": "github:microsoft/arcade-character-animations#v0.0.2" - }, - "files": [ - "main.blocks", - "main.ts", - "README.md", - "assets.json" - ] -} -``` +## Adding an extension to your project -After you save `pxt.json`, run the "MakeCode: Install project dependencies" command to update your project's pxt_modules +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. -## Local development of vscode-makecode +> Note: You must be online to add an extension to your project -Prerequisites: -1. Install node -2. Install yarn: - `npm install -g yarn` +After you add an extension to your project, an entry for it will automatically appear inside your `pxt.json` file. -After you clone the repo, install the dependencies with yarn: +### Removing an extension from a project -``` -yarn install -``` +To remove an extension, run the "MakeCode: Remove an extension" command in the VS Code command palette and select the extension to remove. -### Running the extension locally +### Reinstalling project extensions -To run and debug the extension locally, open the extension in vscode and press F5. +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 debug the webviews in the extension host, run ctrl+shift+i to open the dev tools. +## Downloading a project to hardware -### Running the extension in the browser +To compile your project and download it to hardware (e.g. a Meowbit), first run the "Compile project to uf2/hex" 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`. -To run the extension in the browser, run: +### Flashing hardware from native VS Code -``` -yarn run-in-browser -``` +1. 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: -### Creating a vsix file + ![Screenshot of VS Code with the right-click context menu open over the file binary.uf2](./images/reveal-in-file-explorer.png) -To create a vsix file, first install vsce: +2. 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. +3. Drag the file you located into the USB drive for your hardware. It should automatically reset and load with your compiled game. -``` -npm install -g @vscode/vsce -``` +### Flashing hardware from vscode.dev -Then use vsce to package the vsix +1. Right click on the uf2/hex file in your `built/` folder and select "Download..." to download the uf2/hex file to your computer: -``` -vsce package -``` + ![Screenshot of VS Code with the right-click context menu open over the file binary.hex](./images/download-hex.png) + +2. 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. +3. Drag the file you downloaded into the USB drive for your hardware. It should automatically reset and load with your compiled game. + +### Troubleshooting hardware connections + +If your hardware is failing to show up as a USB drive when you plug it in, try the following steps: + +1. Try a different USB cable (some USB cables are power-only and will not allow data transfer). +2. Try updating the firmware for your device. Follow the manufacturer's instructions for how to do this with your device. +3. As a last resort, try a different computer. There may be a device policy in place that is restricting access to USB ports. + + +## Sharing your project + +To create a share link for your project, click the "Create a 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. + +## Local development + +See the [developer guide](./development.md) for info on developing vscode-makecode. ## Contributing diff --git a/development.md b/development.md new file mode 100644 index 0000000..a233bbe --- /dev/null +++ b/development.md @@ -0,0 +1,56 @@ +# Developer guide + +Prerequisites: +1. Install node +2. Install yarn: + `npm install -g yarn` + +After you clone the repo, install the dependencies with yarn: + +``` +yarn install +``` + +## Running the extension locally + +To run and debug the extension locally, open the extension in vscode and press F5. + +To debug the webviews in the extension host, run ctrl+shift+i to open the dev tools. + +## Running the extension in the browser + +To run the extension in the browser, run: + +``` +yarn run-in-browser +``` + +## Creating a vsix file + +To create a vsix file, first install vsce: + +``` +npm install -g @vscode/vsce +``` + +Then use vsce to package the vsix + +``` +vsce package +``` + +## Linking pxt-mkc + +If you want to develop using your local clone of [pxt-mkc](https://github.com/microsoft/pxt-mkc), you need to link the `makecode-core` and `makecode-browser` packages. + +``` +cd pxt-mkc/packages/makecode-core +yarn link +cd ../makecode-browser +yarn link +cd ../../vscode-makecode +yarn link makecode-core makecode-browser +``` + +Make sure you run `yarn compile` inside of `makecode-core` and `makecode-browser` to build the packages! + diff --git a/images/action-bar.png b/images/action-bar.png new file mode 100644 index 0000000..e760114 Binary files /dev/null and b/images/action-bar.png differ diff --git a/images/asset-rename.png b/images/asset-rename.png new file mode 100644 index 0000000..c2f6cea Binary files /dev/null and b/images/asset-rename.png differ diff --git a/images/command-list.png b/images/command-list.png new file mode 100644 index 0000000..082a503 Binary files /dev/null and b/images/command-list.png differ diff --git a/images/create-new-asset.png b/images/create-new-asset.png new file mode 100644 index 0000000..162eadb Binary files /dev/null and b/images/create-new-asset.png differ diff --git a/images/download-hex.png b/images/download-hex.png new file mode 100644 index 0000000..1cb6e51 Binary files /dev/null and b/images/download-hex.png differ diff --git a/images/duplicate-delete.png b/images/duplicate-delete.png new file mode 100644 index 0000000..cf82bf0 Binary files /dev/null and b/images/duplicate-delete.png differ diff --git a/images/output-pane.png b/images/output-pane.png new file mode 100644 index 0000000..ab3dffb Binary files /dev/null and b/images/output-pane.png differ diff --git a/images/reveal-in-file-explorer.png b/images/reveal-in-file-explorer.png new file mode 100644 index 0000000..51353c2 Binary files /dev/null and b/images/reveal-in-file-explorer.png differ diff --git a/images/simulator-pane.png b/images/simulator-pane.png new file mode 100644 index 0000000..8f00df2 Binary files /dev/null and b/images/simulator-pane.png differ diff --git a/package.json b/package.json index be7a839..d496b3e 100644 --- a/package.json +++ b/package.json @@ -304,7 +304,13 @@ "description": "%makecode.configuration.showCompileDescription%" } } - } + }, + "viewsWelcome": [ + { + "view": "workbench.explorer.emptyView", + "contents": "%makecode.viewsWelcome.welcomeMessage%" + } + ] }, "scripts": { "test": "vscode-test-web --browserType=chromium --extensionDevelopmentPath=. --extensionTestsPath=dist/web/test/suite/index.js", diff --git a/package.nls.json b/package.nls.json index 5c47bfc..d6e4c89 100644 --- a/package.nls.json +++ b/package.nls.json @@ -25,5 +25,6 @@ "makecode.tileExplorer.title": "Tiles", "makecode.tilemapExplorer.title": "Tilemaps", "makecode.songExplorer.title": "Songs", - "makecode.configuration.showCompileDescription": "Show a notification after compiling a MakeCode project" + "makecode.configuration.showCompileDescription": "Show a notification after compiling a MakeCode project", + "makecode.viewsWelcome.welcomeMessage": "You need to open a folder to use the MakeCode Arcade extension!\n[Open Arcade Docs](https://github.com/microsoft/vscode-makecode#microsoft-makecode-extension-for-visual-studio-code)" }