turbowarp / packager

Converts Scratch projects into HTML files, zip archives, or executable programs for Windows, macOS, and Linux.

TurboWarp Packager

https://packager.turbowarp.org/

Converts Scratch projects into HTML files, zip archives, or executable programs for Windows, macOS, and Linux.

Development

Install dependencies:

npm ci

Start in development mode:

npm start

Then visit http://localhost:8947. Manually refresh to see changes.

Packaged projects generated while in development mode should not be distributed. Instead, you should run a production build to significantly reduce file size of both the website and the packager.

npm run build-prod

Output will be located in the dist folder.

The general layout of src is:

• packager: The code that downloads and packages projects.
• p4: The Svelte website for the packager. "p4" is the name that the packager uses internally to refer to itself.
• scaffolding: A minimal Scratch project player. Handles most of the boring details of running Scratch projects like handling mouse inputs.
• common: Some files used by both scaffolding and the packager.
• addons: Optional addons such as gamepad support or pointerlock.
• locales: Translations. en.json contains the original English messages. The other languages are translated by volunteers and imported by an automated script. (you can help)
• build: Various build-time scripts such as webpack plugins and loaders.

Tips for forks

We strive to make the packager easy to fork, even for mods that aren't based on TurboWarp. Reading this section, at least the first half, should make it much easier to do so.

Packages

If you want to change the scratch-vm/scratch-render/scratch-audio/scratch-storage/etc. used, this is simple:

• npm install or npm link your package. The package name does not matter.
• Update src/scaffolding/scratch-libraries.js to import the packages with the name you have. (some of our packages are prefixed with @turbowarp/ while others are still just scratch-vm -- just make sure they match yours)

Then just rebuild. You can even install a vanilla scratch-vm and all core functionality will still work (but optional features such as interpolation, high quality pen, stage size, etc. may not work)

Note that npm is a very buggy piece of software and our dependency tree is very large. Occasionally you might get errors about missing dependencies, which should go away if you run npm install.

Deployment

The packager is deployed as a simple static website. You can host it anywhere by just copying the dist folder after a build.

We use GitHub Actions and GitHub Pages to manage our deployment. If you want to do this too:

• Fork the repository on GitHub and push your changes.
• Go to your fork's settings on GitHub and enable GitHub Pages with the source set to GitHub Actions.
• Go to the "Actions" tab and enable GitHub Actions if it isn't already enabled.
• Push commits to the "master" branch.
• In a few minutes, your site will automatically be built and deployed to GitHub Pages.

Branding

We ask that you at least take a moment to rename the website by editting src/packager/brand.js with your own app name, links, etc.

Large files

Large files such as NW.js, Electron, and WKWebView executables are stored on an external server outside of this repository. While we aren't actively removing old files (the server still serves files unused since November 2020), we can't promise they will exist forever. The packager uses a secure checksum to validate these downloads. Forks are free to use our servers, but it's easy to setup your own if you'd prefer (it's just a static file server; see src/packager/large-assets.js for more information).

Service worker

Set the environment variable ENABLE_SERVICE_WORKER to 1 to enable service worker for offline support (experimental, not 100% reliable). This is not recommended in development. Our GitHub Actions deploy script uses this by default.

Standalone builds

The packager supports generating "standalone builds" that are single HTML files containing the entire packager. Large files such as Electron binaries will still be downloaded from a remote server as needed. You can download prebuilt standalone builds from our GitHub releases. These can be useful if our website is blocked or you don't have a reliable internet connection. Note that standalone builds do not contain an update checker, so do check on your own occasionally.

To make a production standalone build locally:

npm run build-standalone-prod

The build outputs to dist/standalone.html.

Node.js module and API

See node-api-docs/README.md for Node.js API documentation.

To build the Node.js module locally:

npm run build-node-prod

License

Copyright (C) 2021-2024 Thomas Weber

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

packager's Issues

more options for TurboWarp packager

Add options: Loading Screen Text and Cloud Variables, to TurboWarp options.
And frame from compiled Forkphorus.

Custom variable background color

See my fork's website and choose forkphorus for runtime. A new option will appear called: Custom variable background color? It defaults to Scratch's orange.

Add support for loading custom extensions in compiled projects

Projects that use experimental extensions will throw an error stating SecurityError: Failed to construct 'Worker': Script at (file:///) cannot be accessed from origin 'null'. Since the packager is a modified version of TurboWarp, how hard would it be to implement experimental extension support?

Easier way to load custom extension from same directory as project

cloud variables aren't saving to localStorage when packaged

TurboWarp options

• Username
• Warp timer
• Disable compiler
• Framerate
• Cloud variables
• High quality pen
• Turbo mode

Offline support

Create an offline archived version of TurboWarp Packager, like HTMLifier.

Extra options for cloud variables

Options like:
URL - Contains and lets you set the current URL of the web page, I.e for parameters or redirects
Clipboard - Accesses the clipboard and allows you to copy or paste
Username - Changes the username in code for user input (I'm not sure how useful this would actually be but could be cool)
Eval - Evaluates Javascript code
New Tab - Let's you open a link in a new tab or window

Credits page

For people that made this and libraries used

Custom JS and CSS

Add option to store cloud variables locally

forkphorus packager has this

gamepad: cursor doesnt hide when joysticks used

Context menu to toggle addons, settings at runtime

How about an optional context menu to allow the user to enable/disable addons and features like hq pen while they use the packaged project?

List import/export

<is packaged> block

Cache project assets locally

We can store project assets in an indexeddb

Downloader is due for changes and a relicensing anyways

Comply with CC BY-SA 2.0

Make the necessary changes to make sure that the output of p3 isn't violating the license (https://creativecommons.org/licenses/by-sa/2.0/) used by projects uploaded to Scratch

Packing to .exe file 32-bit

Packing to .exe file 32-bit.
Just like the old version.

Does the packager contain custom extensions?

Custom Favicon

Android support

Can output Android Studio source code?

Translations

Verify hash of nwjs

Disable limits

Why isn't this already in the packager?

Gamepad extension - what exactly does it do?

It'd be nice if it could be described - I see no modal or settings is present, however having a description there would be mighty nice!

Custom stage size option

Website already supports it, so the packager should too

Don't include music files if project doesn't use music

Option to make some cloud variables use server and some variables use local storage

nw.js: add ourselves to credits.html

and Scratch too

Support non-png icons

Better error message alert

Right now it uses alert(), which isn't the greatest UX

Would be great to make a better error alert that

• is more consistent with the current styles
• has a button to open a github issue

Interpolation

Interpolation was merged into develop, so add support in the packager

MacOS Version does not work

So I tried converting a scratch project into a Mac compatible application but when I had tried to open the file it would not let me saying quote “The publisher cannot be verified therefore it cannot checked for viruses” or something along those lines. I would like to see this fixed so that I can use the turbo warp packager.

Choose a new non-temporary name

Because p3 is meant to be temporary

Restrictions:

• Cannot use the word "Scratch" in any way except "for Scratch"
• Try to avoid the word HTMLifier to avoid confusion with https://sheeptester.github.io/htmlifier/

Migrate from NW.js to electron

Electron appears to give smaller outputs (160MB vs 261MB uncompressed) and is more widely used

Autoplay option

Custom or hidden mouse cursor

Support for addons (gamepad support)

PLEASE ADD Some mods some I mainly want are green flag icons and also Bluetooth controller buttons like scratch addons do it. JUST PLEASE ADD MORE FEATURES/MODS

Originally posted by @zaydi-repl-it in #34

Add support for loading extension from file:///

vm.extensionManager.loadExtensionURL("file:/// (blah blah blah)")

Uncaught (in promise) Error: Invalid protocol
    at e.exports.loadExtensionURL (extension-manager.js:168)
    at <anonymous>:1:21

Packaging from url

Could you have the packager package projects from any url.

Name Suggestion

Maintain our own forkphorus files

similar to turbowarp's player.js

Ability to change colors

• Background color
• TW red

Optimize icns.js

Seems like I must've forgotten to do an optimized build because it's nearly 500KB

Easier way to add custom extensions

Drop support for forkphorus

Initially this project was "forkphorus packager v3" but it has since become "TurboWarp packager". dropping forkphorus would greatly simplify things, especially as forkphorus already has a functional packager

Custom background image instead of solid color

Better default icon

Make something that looks better than https://github.com/TurboWarp/packager/blob/master/src/packager/default-icon.png

• It's the default icon for NW.js, might end up being the default favicon too
• Should be an "abstract" representation of a packaged project, like how your system displays a generic text file for text documents
• No Scratch trademarks (no scratch logo, no scratch cat, etc.)
• Literally anything will look better than the current icon so don't be scared

Run project in TurboWarp or Forkphorus button

I think there should be a run project in TurboWarp or Forkphorus button. The layout of the three buttons will be: "Package/Run it in TurboWarp/Run it in Forkphorus.

iOS support

Like what http://html-build.glitch.me/ tries to do