How TurboWarp Packager Converts Scratch Projects to HTML

Overview Architecture

The conversion process involves several key components working together:

1. Parsing .sb3 Files

File Structure

An .sb3 file is simply a ZIP archive containing:

• project.json — The project definition (blocks, sprites, variables, etc.)
• Asset files — Images (.svg, .png) and sounds (.wav, .mp3) named by their content hash

Parser Pipeline

module.exports = function (input, isSprite, callback) {
    unpack(input, isSprite)
        .then(function (unpackedProject) {
            return parse(unpackedProject[0])
                .then(validate.bind(null, isSprite))
                .then(function (validatedProject) {
                    return [validatedProject, unpackedProject[1]];
                });
        })
        .then(callback.bind(null, null), callback);
};

Three steps:

1. unpack.js — Detects file format by byte signature (80 75 = ZIP) and extracts using JSZip
2. parse.js — Parses the JSON string using turbowarp/json (handles control characters)
3. validate.js — Detects Scratch version (SB2 vs SB3) by checking for targets or objName keys

2. Scaffolding — The Scratch Player

The Scaffolding class (src/scaffolding/scaffolding.js) is a minimal Scratch project player.

Core Dependencies

import VM from 'scratch-vm';
import Renderer from 'scratch-render';
import ScratchStorage from '@turbowarp/scratch-storage';
import AudioEngine from 'scratch-audio';
import {BitmapAdapter} from '@turbowarp/scratch-svg-renderer';

• scratch-vm — The Scratch Virtual Machine that compiles blocks to JavaScript and executes them
• scratch-render — WebGL renderer for sprites and pen
• scratch-storage — Asset loading system
• scratch-audio — Sound playback engine

Setup Process

setup () {
    this.vm = new VM();
    this.vm.setCompatibilityMode(true);
    this.vm.setLocale(navigator.language);
    this.vm.on('MONITORS_UPDATE', this._onmonitorsupdate.bind(this));
    this.vm.runtime.on('QUESTION', this._onquestion.bind(this));
    // ... renderer, storage, audio engine initialization
}

Project Loading

loadProject (data) {
    return this.vm.loadProject(data)
        .then(() => {
            this.vm.setCloudProvider(this.cloudManager);
            this.cloudManager.projectReady();
            this.renderer.draw();
            // ...
        });
}

The vm.loadProject(data) call is where the magic happens — scratch-vm parses the project JSON, loads all sprite costumes and sounds, and compiles the block scripts to JavaScript.

3. Block Compilation (scratch-vm)

The scratch-vm library handles the conversion from Scratch blocks to executable JavaScript in three stages:

1. Deserialize — Parses project.json into internal data structures
2. Compile — TurboWarp's VM includes a JIT compiler that converts block stacks to optimized JavaScript functions
3. Runtime — Executes the compiled code in a game loop, handling events, broadcasts, clones, etc.

The VM exposes compiler configuration:

if (vm.setCompilerOptions) vm.setCompilerOptions({
    enabled: ${this.options.compiler.enabled},
    warpTimer: ${this.options.compiler.warpTimer}
});

4. HTML Generation (Packager)

Resource Loading

async loadResources () {
    const texts = [COPYRIGHT_HEADER];
    if (this.project.analysis.usesMusic) {
        texts.push(await this.fetchLargeAsset('scaffolding', 'text'));
    } else {
        texts.push(await this.fetchLargeAsset('scaffolding-min', 'text'));
    }
    // ...
    this.script = texts.join('\n');
}

Project Data Embedding

For HTML output, the entire .sb3 is base85-encoded and embedded in chunks:

for (let i = 0; i < projectData.length; i += CHUNK_SIZE) {
    const projectChunk = projectData.subarray(i, i + CHUNK_SIZE);
    const base85 = encode(projectChunk);
    result.push(`<script data="${base85}">decodeChunk(${projectChunk.length})</script>\n`);
}

Runtime Initialization

The generated HTML includes inline JavaScript that bootstraps the player:

const scaffolding = new Scaffolding.Scaffolding();
scaffolding.width = ${this.options.stageWidth};
scaffolding.height = ${this.options.stageHeight};
scaffolding.setup();
scaffolding.appendTo(appElement);

Project Loading at Runtime

const run = async () => {
    const projectData = await getProjectData();
    await scaffolding.loadProject(projectData);
    setProgress(1);
    loadingScreen.hidden = true;
    if (${this.options.autoplay}) {
        scaffolding.start();
    }
};

5. Data Flow Summary