DOCSEARCHbyAlgolia
Submit Docs

Bilup Documentation

website·Indexed 30 days ago

https://docs.bilup.org

Documentation for Bilup, a block-based programming environment built on Scratch. Includes guides on the Bilup Packager for embedding and standalone HTML builds, internals for the Redux store and architecture, and instructions for building compiled or unsandboxed extensions.

Tokens
70.1K
Snippets
203
Records
553
Agent score
50%

What's inside Bilup

  1. Overview of Bilup features and capabilities

    Bilup is a modification of Scratch built on top of TurboWarp. It maintains compatibility with Scratch blocks, sprites, costumes, and the stage, while adding the following enhancements:

    • Performance: A compiler that translates blocks into JavaScript for faster execution than the standard Scratch interpreter.
    • Display Control: Support for arbitrary frame rates (beyond 30 FPS) and custom stage sizes (beyond 480x360).
    • Developer Tooling: A debugger for stepping through and inspecting running projects, and a packager to convert projects into standalone apps or web pages.
    • Project Management: Git version control, live collaboration, restore points, and autosave.
    • Customization: Themes (including dark mode and custom color schemes) and optional Addons to modify editor and player behavior.
    • Community: A platform for accounts, publishing projects, following users, and commenting.

  2. Overview of the Music extension

    The Music extension allows for playing instrument notes and drum sounds using a built-in synthesized sound set. It works offline, requires no external hardware, and is compatible with Scratch. To use it, go to Add Extension and select Music.

  3. Overview of Bilup features and access

    Bilup is a Scratch modification built on TurboWarp. It maintains the standard Scratch editor interface while adding several advanced developer tools: a compiler that converts blocks into JavaScript, a debugger, git version control, live collaboration, a project packager, and various addons and themes.

    Bilup can be used entirely in the browser at https://com.bilup.org/ without an account or installation. A Bilup Accounts account is required only for publishing projects, following users, and syncing settings across devices.

  4. Use the Backpack to share assets and scripts across projects

    The backpack is a collapsible bar at the bottom of the editor used to store and transport reusable assets between sprites and projects. It acts as a personal library tied to the user account rather than a specific project, ensuring items persist across different sessions.

    Supported item types:

    • Scripts (stacks of blocks)
    • Sprites
    • Costumes
    • Sounds

  5. Understand Bilup Editor Internal Architecture

    The Bilup editor is built using a React and Redux architecture. It is primarily split into two main parts:

    1. scratch-gui: Contains the user interface, the Redux store, the theme engine, and the addon framework.
    2. scratch-vm: Contains the runtime and compiler.

    The boundary where the GUI interacts with the Virtual Machine (VM) is the core of the editor's communication flow. Bilup is a fork of TurboWarp, which is a fork of Scratch, meaning it inherits much of its structural design from those projects.

  6. Create a minimal Redux container

    A minimal container reads state (such as the VM instance or a status flag) and provides a method to trigger updates. In this architecture, the VM is treated as a stable object reference stored in the state (state.scratchGui.vm) rather than a singleton import.
    import {connect} from 'react-redux';

class TurboMode extends React.Component {
    toggleTurboMode () {
        // Access VM and state via props provided by the container
        this.props.vm.setTurboMode(!this.props.turboMode);
    }
    render () {
        const {children, vm, ...props} = this.props;
        // Render-prop pattern: pass the callback and state to children
        return this.props.children(this.toggleTurboMode, props);
    }
}

const mapStateToProps = state => ({
    vm: state.scratchGui.vm,
    turboMode: state.scratchGui.vmStatus.turbo
});

export default connect(
    mapStateToProps,
    () => ({}) // Return empty object if no actions need to be dispatched
)(TurboMode);

  7. How the Sequencer manages thread execution

    The Sequencer (engine/sequencer.js) is responsible for running threads. On every frame, stepThreads() is called, which:

    1. Sets a work budget (WORK_TIME) to 75% of the frame interval.
    2. Iterates through runtime.threads and calls stepThread(thread) for running or yielded threads.
    3. Continues looping if there are active threads and budget remains, provided turbo mode is on or no block has requested a screen redraw.
    4. Removes and returns finished threads.

    If a thread is compiled, the sequencer uses the compiled executor; otherwise, it uses the interpreter to walk blocks, handle reporters, and manage yields.

  8. Use Compiled Threads for performance

    Bilup can compile scripts into JavaScript generator functions for faster execution. When isCompiled is true, the generator is stepped instead of the interpreter walking blocks. The overall thread model (status, warp, lifecycle) remains the same. The compiler is enabled by default but can be disabled in project settings.

  9. Understand the Bilup project architecture and repository structure

    Bilup is a modification of Scratch built on top of TurboWarp. It consists of a collection of forked Scratch packages and Bilup-specific services. The primary components are:

    • scratch-gui: The editor and community site (Webpack build).
    • scratch-vm: The project runner and compiler; this is where blocks are defined.
    • scratch-render, scratch-blocks, scratch-paint, and scratch-audio: Forked engine packages.
    • packager: Converts projects into standalone HTML or executables.
    • bilup-api: The backend for the community platform.
    • docs: The documentation site.

  10. Understand the container/component split in scratch-gui

    The codebase separates React code into two distinct directories to decouple presentation from business logic:

    • Components (src/components/): Responsible for rendering the UI. They receive data and callbacks via props and must not import the Redux store or the VM. This ensures they are predictable, reusable, and easy to test.
    • Containers (src/containers/): Responsible for wiring. They interact with the Redux store and VM, select the necessary state, bind callbacks, and pass them as props to the corresponding components.

    Note: Components may still maintain local UI state (e.g., hover, drag, layout measurements) using React hooks or useState if that state does not need to be global in Redux.

  11. Identify Bilup core repositories

    Bilup is distributed across several GitHub repositories. The primary repositories for development are:

    • scratch-gui: The editor and community site (most UI work).
    • scratch-vm: Project execution, block definitions, and the compiler.
    • Engine packages: scratch-blocks, scratch-render, scratch-paint, and scratch-audio.

  12. Understand the Bilup GUI Higher-Order Component (HOC) architecture

    The Bilup GUI is constructed using a series of Higher-Order Components (HOCs) wrapped around the ConnectedGUI component via a compose helper. Each HOC is responsible for a specific cross-cutting concern such as localization, error handling, theme management, and VM bridging.

    Key VM-related HOCs include:

    • vmManagerHOC: Drives the VM (attaches audio, starts the VM, loads project data).
    • vmListenerHOC: Listens to VM events and dispatches Redux actions.

    The VM instance is created in the vm reducer (src/reducers/vm.js) and is accessible globally in the Redux store at state.scratchGui.vm.

    const WrappedGui = compose(
    LocalizationHOC,
    ErrorBoundaryHOC('Top Level App'),
    TWThemeManagerHOC,
    TWFullScreenResizerHOC,
    FontLoaderHOC,
    ProjectFetcherHOC,
    SB3PostMessageHOC,
    TitledHOC,
    ProjectSaverHOC,
    vmListenerHOC,
    vmManagerHOC,
    SBFileUploaderHOC,
    cloudManagerHOC
)(ConnectedGUI);