@bocoup/phoenix-fyre

Standalone Scratch Player Documentation

Table of contents

• Getting this Demo Running
• Adding Your Own Scratch Project
• Production Release Guidelines
• General Reference
• Package Contents

Getting this Demo Running

How to download and run this demo.

1. Visit https://registry.npmjs.org/@bocoup/phoenix-fyre/-/phoenix-fyre-1.1.3.tgz in your browser and a download will start. Unzip this demo project, and move the contents of the "package" sub-directory that it creates into a location of your choosing, i.e. your home directory. Or, on the command line, this looks like:

$ wget https://registry.npmjs.org/@bocoup/phoenix-fyre/-/phoenix-fyre-1.1.3.tgz
$ mkdir ~/my-project-name
$ tar -xf phoenix-fyre-1.1.3.tgz -C ~/my-project-name --strip=1

1. Check that the demo is working with a local server, using npx for example (requires node and npm to work):

$ cd ~/my-project-name
$ npx http-server

Open a browser to http://localhost:8080/example.index.html

Adding Your Own Scratch Project

How to add a new local scratch project with flat uncompressed files to this demo project.

1. Follow the demo project "phoenix-fyre" download instructions in the previous "Getting this Demo Running" section.

2. Choose the scratch project you would like to load. You can download it from the scratch editor on scratch.mit.edu, or ask the person who made the project to send it to you.

3. Unzip the scratch .sb3 file and move the files into a sub-directory of this demo project's assets folder. You can do this manually by changing the downloaded scratch sb3 file extension to a .zip file extension, unzipping it and then dragging and dropping the files into this project. Or if you prefer to use the command line you can do something like:

$ unzip "Scratch Project.sb3" -d "~/my-project-name/assets/project-name"

1. Duplicate example.index.html to index.html and update the <canvas> tag data-source attribute to match the name of your unziped sb3 file assets, for example: <canvas data-source="assets/project-name/project.json"></canvas>. If you are using the data-path attribute, you will also have to update that.

2. Check that this demo is still working working with a local server, using npx for example (requires node and npm to work):

$ cd ~/my-project-name
$ npx http-server

Open a browser to http://localhost:8080/index.html

Production Release Guidelines

How to integrate this player and your own scratch project with another website.

1. You can either start with the project you downloaded in the last section (~/my-project-name/assets/project-name), or download and unzip a new scratch project.

2. Compress the scratch project assets as much as you can. We have a set of png compression recommendations in our authoring guidelines for fast scratch projects, available at https://docs.google.com/document/d/1Mriw6cCxWhNvn1wqrqSm411GboXdsuobqnWgGJ80MOE. We recommended that you compress pngs using the "save for web method" in Photoshop, for example. If you are working with assets from an uncompressed and un-optimized sb3, you can also use pngquant on the command-line to batch compress files.

3. Copy my-project-name into the third-party code section of your production project.

4. Copy the relevant parts of the index.html file into the target location in your production project, including references to the CSS and JS files at the correct path (E.G my-project-name/base.css, my-project-name/player.css and my-project-name/main.min.js). Copy the HTML snippet <div class="stage-container"> containing a <canvas id="scratch-stage"> and any other relevant player controls. You should also include the meta tags apple-mobile-web-app-capable and viewport as written in the example HTML in order for the embed to work properly on mobile.

5. Update the <canvas> element's data-source attribute to match the name of your unziped sb3 file assets, for example: data-source="assets/project-name/project.json". If you are using the data-path attribute, you will also have to update that.

The ultimate location of the embedded player assets and the scratch project assets should be on the same origin. The player CSS and JavaScript should be on in the same directory as the HTML file which your <canvas> tag is in. Your <canvas> tag should reference a data-source path to a project.json that is in the same directory as the scratch project assets it came with in the .sb3 file you started with.

1. Check that the relative paths work correctly. Start a server in your project directory and visit it in your browser using your development environment.

General Reference

The player supports three ways of loading a project: locally from flat files (the fastest and recommended), locally/remotely from a bundled .sb3, or remotely from a scratch project id on the scratch servers (not recommended in production).

The player is embedded as a <canvas> element with an id of scratch-stage. If no project is specified, then the the player looks for a scratch project .json in assets/playground/project.json. You can override this behavior with the following html attributes and url parameters.

data-source

You can change the data source to a project.json or zipped .sb3 file of your choosing, or a .sb3 file:

<canvas data-source="path/to/my-project/project.json">

The above example will load a project.json and which will look for Scratch project assets in the same directory as the json file.

<canvas data-source="path/to/my-project.sb3">

The above example will load a my-project.sb3 and unzip it in the browser. This is a bit slower to load, but faster to develop with, so we only recommned this approach for development.

Fully qualified scratch project URLs also work, so you can do something like the following and expect it to load the corresponding scratch project, so long as that project is live and public:

<canvas data-source="https://projects.scratch.mit.edu/319681786"></canvas>

data-path

The data-path attribute changes the base path for the project, so you can do something that looks more like this:

<canvas data-source="my-project.sb" data-path="path/to/">

Query Params

If you're looking to quickly iterate on the embedded player with different scratch projects you can leave the data-source and data-path attributes unset and set them in the url of the page with links like: http://localhost:8080?source=path/to/my-project.sb3 or http://localhost:8080?source=my-project.sb3&?path=path/to

You can even use fully qualified scratch project URLs in the params, like ?source=https://projects.scratch.mit.edu/319681786 for example.

Package Contents

Player contents

This project comes with the following files:

├── assets
│   ├── playground
│   │   ├── 83a9787d4cb6f3b7632b4ddfebf74367.wav
│   │   ├── 83c36d806dc92327b9e7049a565c6bff.wav
│   │   ├── b7853f557e4426412e64bb3da6531a99.svg
│   │   ├── cd21514d0531fdffb22204e0ec5ed84a.svg
│   │   ├── e6ddc55a6ddd9cc9d84fe0b4c21e016f.svg
│   │   ├── project.json
│   ├── down.svg
│   ├── left.svg
│   ├── playground.sb3
│   ├── right.svg
│   └── up.svg
├── base.css
├── example.index.html
├── extension-worker.js
├── extension-worker.js.map
├── main.min.js
└── player.css

assets

This directory holds images for the virtual key's styling and a default project.

example.index.html

This HTML file contains demo code for using the standalone player. Almost all of the contents of this file are required for production use.

extension-worker.js, extension-worker.js.map

These files are used for running scratch extensions in web workers.

main.min.js

This is a minified version of all of the JavaScript we need to run the the standalone player itself.

CSS Files

The player is designed to have two sets of styling instructions. base.css contains a small amount of styling for the player to maintain Scratch's aspect ratio of 4/3 and also styling for the virtual keys UI. player.css is suggested styling for the UI around the player. player.css can be optional, if it conflicts with other styles needed for the page.

base.css

Minimal styling to maintain the correct aspect ratio for the Scratch player and also style the virtual keys.

player.css

Suggested styling for the UI around the player. If you are using this in addition to base.css, make sure it is linked to in the page second for intended styling.