Bitbybit Runner: Execute 3D Scripts From Visual Programming Editors Anywhere on the Web

We are excited to introduce Bitbybit Runner, a powerful tool that allows you to execute your Bitbybit scripts directly on any website simply by including a single JavaScript file from our CDN. This significantly simplifies the process of creating, integrating, and sharing interactive 3D experiences, empowering you to build custom UIs and seamlessly connect them with Bitbybit's rich 3D and CAD functionalities.

This section will guide you through understanding and utilizing the Bitbybit Runner, unlocking new possibilities for deploying your parametric designs, 3D configurators, and simulations across the web.

The Evolution of Bitbybit Runner

The Bitbybit Runner is a single JavaScript file you can include in your website. It bundles all the open-source components of the Bitbybit platform, including CAD kernels (like OCCT, JSCAD) and various 3D algorithms, making it easier than ever to develop sophisticated parametric 3D experiences and model configurators directly in your web projects.

Our journey with the Runner began with a version fully based on the BabylonJS game engine. This initial runner proved to be incredibly powerful, allowing direct execution of Bitbybit algorithms via JavaScript and enabling users to export scripts from our visual editors (Rete, Blockly, TypeScript) for use in any browser-based coding environment like StackBlitz, CodePen, JSFiddle, or their own websites.

• For more background, check out our original announcement: Introducing BITBYBIT-RUNNER.JS

New and Improved: ThreeJS Support & Lite Versions

Responding to community feedback and our recent integration of the ThreeJS game engine, we are thrilled to announce:

1. A Dedicated ThreeJS Runner: This new runner follows the same principles as the BabylonJS version but is specifically designed to work with ThreeJS. It's a single JavaScript file that automatically loads all necessary resources, including web workers, CAD kernels, and other dependencies.
2. "Lite" Versions for Both Engines: We realized many projects already include ThreeJS or BabylonJS as a dependency. To avoid redundant loading and optimize performance, we've introduced Lite versions of our runners. These Lite bundles are significantly smaller as they do not include the game engine dependencies themselves, expecting you to load them separately in your project. This makes your website faster and more efficient if you're already using one of these engines.

Overview of Available Runners

Here's a breakdown of the different Bitbybit Runner versions:

• bitbybit-runner-babylonjs.js:
  • The most powerful and feature-rich runner, including all resources and the BabylonJS engine.
  • Ideal if your project doesn't already use BabylonJS.
  • Offers the best support for scripts exported from our visual programming editors, including BabylonJS-specific features like GUI elements and Havok physics.
• bitbybit-runner-lite-babylonjs.js:
  • A smaller version that excludes the BabylonJS engine.
  • Expects BABYLON, GUI, LOADERS, MATERIALS, SERIALIZERS global objects to be available on the window object for successful initialization.
• bitbybit-runner-threejs.js:
  • Bundles the ThreeJS game engine and OrbitControls.
  • Can execute Bitbybit's open-source 3D modeling algorithms and visual scripts, as long as they don't contain BabylonJS-specific logic.
• bitbybit-runner-lite-threejs.js:
  • A lightweight version that excludes the ThreeJS engine.
  • Expects THREEJS and OrbitControls global objects to be available on the window object.

Key Differences: BabylonJS vs. ThreeJS Runners

Both runner families can execute all of Bitbybit's open-source 3D modeling algorithms and CAD kernels. The primary differences relate to the game engines:

• Visual Script Compatibility: If you're exporting scripts from our visual editors on bitbybit.dev (which are BabylonJS-based), the BabylonJS runner offers broader compatibility, especially if your scripts use BabylonJS-specific features (skyboxes, GUI, physics).
• ThreeJS Runner for Visual Scripts: The ThreeJS runner will attempt to run visual scripts but will throw an error if it encounters BabylonJS-specific logic. However, if your visual coding is limited to 3D modeling features, it should execute fine.
• Direct JavaScript Coding: If you're writing Bitbybit logic directly in JavaScript, either runner family will work well for accessing the core algorithms.
• Bundle Size: The BabylonJS runner file is generally larger than the ThreeJS one. Consider this when choosing.

No matter your preference, we support both these fantastic game engines and are excited to see what you'll create!

Where to Find and How to Use the Runners

The Bitbybit Runners are served from the jsDelivr CDN. Include them in your website using <script> tags. Remember to replace <version-number-of-bitbybit> with an actual version number. You can find all Bitbybit release versions on Bitbybit GitHub Releases.

• BabylonJS Runner (Full):

  <script src="https://cdn.jsdelivr.net/gh/bitbybit-dev/bitbybit-assets@<version-number-of-bitbybit>/runner/bitbybit-runner-babylonjs.js"></script>
• BabylonJS Runner (Lite):

  <script src="https://cdn.jsdelivr.net/gh/bitbybit-dev/bitbybit-assets@<version-number-of-bitbybit>/runner/bitbybit-runner-lite-babylonjs.js"></script>
• ThreeJS Runner (Full):

  <script src="https://cdn.jsdelivr.net/gh/bitbybit-dev/bitbybit-assets@<version-number-of-bitbybit>/runner/bitbybit-runner-threejs.js"></script>
• ThreeJS Runner (Lite):

  <script src="https://cdn.jsdelivr.net/gh/bitbybit-dev/bitbybit-assets@<version-number-of-bitbybit>/runner/bitbybit-runner-lite-threejs.js"></script>

Once included, you can access the runner's functionality via the window.bitbybitRunner object.

Core window.bitbybitRunner Functions:

• run(options):
  • An async function that initializes the runner. You must await this function or use .then() before executing scripts.
  • Requires an options object, minimally containing canvasId: 'your-canvas-element-id'.
  • It creates and configures a default 3D scene (BabylonJS or ThreeJS depending on the runner), instantiates CAD kernels, loads WebAssembly libraries, fonts, physics engines (for BabylonJS runner), and other resources.
  • You can disable various features via the options object if not needed (e.g., occt: false, jscad: false).
• executeScript(scriptContent, inputs):
  • Executes a script (either JavaScript code you write or code exported from Bitbybit editors).
  • scriptContent: Can be a string of JavaScript code or the content exported from our editors.
  • inputs (optional): An object containing input values for your script if it's designed to accept them.
  • Returns a promise that resolves with the resulting values collected from the script's execution.
• cleanOCCTCache() / cleanJSCADCache() / cleanManifoldCache():
  • Functions to clear the internal cache for the respective CAD kernels (OCCT, JSCAD, Manifold). This can be useful if you need to ensure fresh computations.

Exporting Scripts from Bitbybit for the Runner

All Bitbybit editors (Rete, Blockly, TypeScript) feature an "Export to Runner" button under the "More Actions" menu.

Clicking this opens a dialog displaying the generated JavaScript code. You can save this as a file or copy-paste it directly into your website's script.

Preparing Scripts for Inputs and Outputs

When creating scripts in Bitbybit (especially visual ones) intended for the Runner with external UI interaction, you'll use specific components/functions to:

• Read Inputs: Special "Get Runner Input" components/functions allow your script to receive data passed via the inputs object in executeScript. These inputs might be undefined when running in the editor but will be correctly populated by the Runner.
• Set Outputs: "Set Runner Output" components/functions allow your script to return data (numbers, text, mesh references, OCCT shape hashes) back to your main JavaScript code after execution.

This enables dynamic 3D configurators where your website's UI can control parameters of the Bitbybit script, and the script can return results.

Treat the exported script as a static code snippet; the Runner executes JavaScript directly without the Rete/Blockly UI or runtime. This often results in faster and more efficient execution.

Practical Examples

To see the Bitbybit Runner in action, explore our example projects. These are often single index.html files you can open directly in your browser.

• ➡️ Example Use Cases of BabylonJS & ThreeJS Runners on GitHub This repository contains examples using both full and lite runners, demonstrating various scenarios, including:
  • Simply running an exported Rete script.
  • Coding Bitbybit logic directly in JavaScript using the runner.
  • Interacting with an exported Rete script through custom UI buttons (a basic 3D configurator).

ThreeJS Runner Demo: 3D Printable Logo A 3D model configurator for creating a customizable ThreeJS logo, ready for 3D printing.

• Live Demo: 3D Printable ThreeJS Logo
• Examples on Coding Platforms:
  • StackBlitz Example
  • CodePen Example
  • JSFiddle Example
• Source Code: GitHub Source

StackBlitz - Bitbybit Runner Starter

script.js

import GUI from 'https://cdn.jsdelivr.net/npm/lil-gui@0.20/+esm';

const current = {
    group: undefined,
    gui: undefined,
};

let finalShape = undefined;
let shapesToClean = [];

const domNode = document.getElementById('myCanvas');

const camera = new THREEJS.PerspectiveCamera(
    70,
    domNode.clientWidth / domNode.clientHeight,
    0.01,
    1000
);
const scene = new THREEJS.Scene();
const light1 = new THREEJS.HemisphereLight(0xffffff, 0x000000, 10);
scene.add(light1);
const light2 = new THREEJS.HemisphereLight(0xffffff, 0x000000, 10);
light2.position.y = -1;
scene.add(light2);

const renderer = new THREEJS.WebGLRenderer({
    antialias: true,
    canvas: domNode,
});
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);

const controls = new OrbitControls(camera, renderer.domElement);
camera.position.set(0, 20, 0);
controls.update();
controls.target = new THREEJS.Vector3(0, 0, 0);
controls.enableDamping = true;
controls.dampingFactor = 0.1;
controls.zoomSpeed = 1;

renderer.shadowMap.enabled = true;

const onWindowResize = () => {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
};
window.addEventListener('resize', onWindowResize, false);

renderer.setClearColor(new THREEJS.Color(0x1a1c1f), 0);

function adjustShadowSettings(light) {
    light.castShadow = true;
    light.shadow.camera.near = 0;
    light.shadow.camera.far = 1000;
    const dist = 8;
    light.shadow.camera.right = dist;
    light.shadow.camera.left = -dist;
    light.shadow.camera.top = dist;
    light.shadow.camera.bottom = -dist;
    light.shadow.mapSize.width = 3000;
    light.shadow.mapSize.height = 3000;
}
const dirLight1 = new THREEJS.DirectionalLight(0xffeeff, 50);
dirLight1.position.set(35, 12, -15);
const dirLight2 = new THREEJS.DirectionalLight(0xffeeff, 50);
dirLight2.position.set(35, -12, -15);

adjustShadowSettings(dirLight1);
adjustShadowSettings(dirLight2);

scene.add(dirLight1);
scene.add(dirLight2);

const animation = (time) => {
    renderer.render(scene, camera);
    controls.update();
};
renderer.setAnimationLoop(animation);

const runnerOptions = {
    enableOCCT: true,
    enableJSCAD: false,
    enableManifold: false,
    loadFonts: [],
    externalThreeJSSettings: {
        scene,
        camera,
        renderer,
    },
};

const runner = window.bitbybitRunner.getRunnerInstance();
const { bitbybit, Bit } = await runner.run(runnerOptions);

const downloadStep = async () => {
    if (bitbybit && finalShape) {
        await bitbybit.occt.io.saveShapeSTEP({
        shape: finalShape,
        fileName: 'threejs.stp',
        adjustYtoZ: true,
        tryDownload: true,
        });
    }
};

const downloadSTL = async () => {
    if (bitbybit && finalShape) {
        await bitbybit.occt.io.saveShapeStl({
        shape: finalShape,
        fileName: 'threejs.stl',
        precision: 0.01,
        adjustYtoZ: true,
        tryDownload: true,
        });
    }
};

const updateShape = async () => {
  showSpinner();
  disableGUI();
  await createShape(bitbybit, scene);
  enableGUI();
  hideSpinner();
};

const model = {
    scale1: 0.4,
    scale2: 0.1,
    heightBase: 0.1,
    heightMid1: 0.2,
    heightMid2: 0.4,
    downloadSTL,
    downloadStep,
};

    const createShape = async () => {
    if (shapesToClean.length > 0) {
        await bitbybit.occt.deleteShapes({ shapes: shapesToClean });
        shapesToClean = [];
    }

    const triangleFrame1 = await bitbybit.occt.shapes.wire.createNGonWire({
        nrCorners: 3,
        radius: 9,
        center: [0, 0, 0],
        direction: [0, 1, 0],
    });

    const triangleFrame2 = await bitbybit.occt.shapes.wire.createNGonWire({
        nrCorners: 3,
        radius: 6,
        center: [0, 0, 0],
        direction: [0, 1, 0],
    });

    const shape1 = await createTriangle1(
        model.heightBase,
        model.scale1,
        model.heightMid1
    );
    const shape2 = await createTriangle1(
        model.heightBase,
        model.scale2,
        model.heightMid2
    );

    shapesToClean.push(shape1, shape2);

    const shape2Rot = await bitbybit.occt.transforms.rotate({
        shape: shape2,
        angle: 180,
        axis: [0, 1, 0],
    });
    shapesToClean.push(shape2Rot);

    const points1 =
        await bitbybit.occt.shapes.wire.divideWireByEqualDistanceToPoints({
        shape: triangleFrame1,
        nrOfDivisions: 9,
        removeStartPoint: true,
        removeEndPoint: false,
        });

    points1.push([0, 0, 0]);

    const points2 =
        await bitbybit.occt.shapes.wire.divideWireByEqualDistanceToPoints({
        shape: triangleFrame2,
        nrOfDivisions: 6,
        removeStartPoint: true,
        removeEndPoint: false,
        });

    const triangles1 = await bitbybit.occt.transforms.translateShapes({
        shapes: points1.map(() => shape1),
        translations: points1,
    });
    shapesToClean.push(...triangles1);

    const triangles2 = await bitbybit.occt.transforms.translateShapes({
        shapes: points2.map(() => shape2Rot),
        translations: points2,
    });
    shapesToClean.push(...triangles2);

    const triangleBase = await bitbybit.occt.shapes.wire.createNGonWire({
        nrCorners: 3,
        radius: 12,
        center: [0, -model.heightBase, 0],
        direction: [0, 1, 0],
    });
    shapesToClean.push(triangleBase);

    const extrusion = await bitbybit.occt.operations.extrude({
        shape: triangleBase,
        direction: [0, model.heightBase * 2, 0],
    });
    shapesToClean.push(extrusion);

    const shell = await bitbybit.occt.shapes.shell.sewFaces({
        shapes: [extrusion, ...triangles1, ...triangles2],
        tolerance: 1e-7,
    });
    shapesToClean.push(shell);

    finalShape = await bitbybit.occt.shapes.solid.fromClosedShell({
        shape: shell,
    });
    shapesToClean.push(finalShape);

    const solidRot = await bitbybit.occt.transforms.rotate({
        shape: finalShape,
        angle: 15,
        axis: [0, 1, 0],
    });
    shapesToClean.push(solidRot);

    const options = new Bit.Inputs.Draw.DrawOcctShapeOptions();
    options.edgeColour = '#000000';
    options.edgeWidth = 6;
    const material = new THREEJS.MeshPhysicalMaterial({ color: 0x7f7f7f });
    material.polygonOffset = true;
    material.polygonOffsetFactor = 2;
    material.shininess = 1;
    material.metalness = 0.4;
    material.roughness = 0.2;
    options.faceMaterial = material;
    const group = await bitbybit.draw.drawAnyAsync({
        entity: solidRot,
        options,
    });
    group.children[0].children.forEach((child) => {
        child.castShadow = true;
        child.receiveShadow = true;
    });

    current.group?.traverse((obj) => {
        scene?.remove(obj);
    });

    current.group = group;
};

const start = async () => {
    createGui();
    createShape();
};

async function createTriangle1(heightBase, scale, heightMid) {
    let useScale = scale;
    if (scale === 0) {
        useScale = 0.0001;
    }
    const midScale = (1 - useScale) / 2 + useScale;
    const triangleBaseOne = await bitbybit.occt.shapes.wire.createNGonWire({
        nrCorners: 3,
        radius: 3,
        center: [0, heightBase, 0],
        direction: [0, 1, 0],
    });
    shapesToClean.push(triangleBaseOne);

    const triangleMidOne = await bitbybit.occt.shapes.wire.createNGonWire({
        nrCorners: 3,
        radius: 3 * midScale,
        center: [0, heightMid, 0],
        direction: [0, 1, 0],
    });
    shapesToClean.push(triangleMidOne);

    const triangleCoreOne = await bitbybit.occt.shapes.wire.createNGonWire({
        nrCorners: 3,
        radius: 3 * useScale,
        center: [0, 0, 0],
        direction: [0, 1, 0],
    });
    shapesToClean.push(triangleCoreOne);

    const triangleBaseDown = await bitbybit.occt.shapes.wire.createNGonWire({
        nrCorners: 3,
        radius: 3,
        center: [0, -heightBase, 0],
        direction: [0, 1, 0],
    });
    shapesToClean.push(triangleBaseDown);

    const triangleMidDown = await bitbybit.occt.shapes.wire.createNGonWire({
        nrCorners: 3,
        radius: 3 * midScale,
        center: [0, -heightMid, 0],
        direction: [0, 1, 0],
    });
    shapesToClean.push(triangleMidDown);

    const loftOptions = new Bit.Inputs.OCCT.LoftAdvancedDto();
    loftOptions.straight = true;
    loftOptions.shapes = [
        triangleBaseDown,
        triangleMidDown,
        triangleCoreOne,
        triangleMidOne,
        triangleBaseOne,
    ];

    return bitbybit.occt.operations.loftAdvanced(loftOptions);
}

start();

function disableGUI() {
    const lilGui = document.getElementsByClassName('lil-gui')[0];
    lilGui.style.pointerEvents = 'none';
    lilGui.style.opacity = '0.5';
}

function enableGUI() {
    const lilGui = document.getElementsByClassName('lil-gui')[0];
    lilGui.style.pointerEvents = 'all';
    lilGui.style.opacity = '1';
}

function createGui() {
    const gui = new GUI();
    current.gui = gui;
    gui.$title.innerHTML = '3D Print THREEJS Christmas Toy';

    gui
        .add(model, 'scale1', 0, 0.9, 0.01)
        .name('Scale 1')
        .onFinishChange((value) => {
        model.scale1 = value;
        updateShape();
        });

    gui
        .add(model, 'scale2', 0, 0.9, 0.01)
        .name('Scale 2')
        .onFinishChange((value) => {
        model.scale2 = value;
        updateShape();
        });

    gui
        .add(model, 'heightBase', 0.05, 2, 0.01)
        .name('Base Height')
        .onFinishChange((value) => {
        model.heightBase = value;
        updateShape();
        });

    gui
        .add(model, 'heightMid1', 0.05, 1, 0.01)
        .name('Height Middle 1')
        .onFinishChange((value) => {
        model.heightMid1 = value;
        updateShape();
        });

    gui
        .add(model, 'heightMid2', 0.05, 1, 0.01)
        .name('Height Middle 2')
        .onFinishChange((value) => {
        model.heightMid2 = value;
        updateShape();
        });

    gui.add(model, 'downloadSTL').name('Download STL');
    gui.add(model, 'downloadStep').name('Download STEP');
}

function showSpinner() {
    const element = document.createElement('div');
    element.id = 'spinner';
    element.className = 'lds-ellipsis';
    element.innerHTML = `
        <div></div>
        <div></div>
        <div></div>
    `;

    document.body.appendChild(element);
}

function hideSpinner() {
    const el = document.getElementById('spinner');
    if (el) {
        el.remove();
    }
}

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Runner Example - IO from Rete editor</title>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <link rel="stylesheet" href="styles.css" />
    <script type="importmap">
      {
        "imports": {
          "three": "https://cdn.jsdelivr.net/npm/three@v0.176.0/build/three.module.js",
          "three/addons/controls/OrbitControls": "https://cdn.jsdelivr.net/npm/three@v0.176.0/examples/jsm/controls/OrbitControls.min.js"
        }
      }
    </script>
    <script type="module">
      import * as THREEJS from 'three';
      import { OrbitControls } from 'three/addons/controls/OrbitControls';
      window.THREEJS = THREEJS;
      window.OrbitControls = OrbitControls;
    </script>
    <script
      defer
      src="https://cdn.jsdelivr.net/gh/bitbybit-dev/bitbybit-assets@0.20.4/runner/bitbybit-runner-lite-threejs.js"
    ></script>
    <script type="module" src="script.js"></script>
  </head>
  <body>
    <div class="logo">
      <a href="https://app-store.bitbybit.dev">
        <img
          src="https://bitbybit.dev/assets/logo-gold-small.png"
          width="50px"
          height="50px"
        />
      </a>
      <div>
        Made with
        <a target="_blank" href="https://bitbybit.dev">bitbybit.dev</a> &
        <a target="_blank" href="https://threejs.org">threejs.org</a>
      </div>
      <div>
        Source code on
        <a
          href="https://github.com/bitbybit-dev/app-examples/blob/main/runner/threejs/lite/threejs-logo/index.html"
          >github</a
        >
      </div>
      <div>
        Code on
        <a
          target="_blank"
          href="https://codepen.io/matas-bitbybit-dev/pen/yyBebgr"
          >CodePen</a
        >
        <a
          target="_blank"
          href="https://stackblitz.com/edit/stackblitz-starters-fhck8j?file=script.js"
          >StackBlitz</a
        >
        <a
          target="_blank"
          href="https://jsfiddle.net/matas_bitbybitdev/qmyLhre3/5/"
          >JSFiddle</a
        >
      </div>

      <div>Powered by bitbybit runner for ThreeJS</div>
    </div>
    <canvas id="myCanvas"></canvas>
    <img
      class="bottom-img"
      src="https://app.bitbybit.dev/assets/homepage/lg/parametric-design-bottom.png"
    />
  </body>
</html>

This configurator can even save STL and STEP files, allowing you to manufacture a physical model!

What's Next?

The Bitbybit Runner technology opens up vast possibilities. While this is an evolving tool, we're excited about its potential. We encourage you to experiment, provide feedback, and let us know how you're using it. More documentation, tutorials, and potentially a YouTube course are planned for the future.