Skip to main content

Block Settings

This block is deprecated

Nothing you have already built stops working, and every setting on this page still does what it says. Do not start anything new here. The "BITBYBIT RUNNER" Block explains what to build instead.

Every setting on the BITBYBIT RUNNER (legacy) block, kept for the setups that already use it. The block runs a parametric script that generates geometry from a shopper's input, and you find its settings in the theme editor after adding it to a template.

Your script holds the logic, so most settings stay global, set once on the block. Any text setting can be linked to a product metafield to differ per product: usually the script itself, and the camera to frame each product.

Script Configuration Settings​

All three settings below put JavaScript on your product page, where it runs in every shopper's browser with the same reach as your theme's own scripts. Put in only code that you or your developer wrote and checked.

Inline Script​

The script itself, embedded in the theme block.

  1. Create your design in one of the bitbybit.dev editors: Blockly, Rete or TypeScript.
  2. Open More and choose Export to runner.
  3. Choose Copy minified. The dialog's first button copies the bare code, for a Composer script, which this field cannot run.
  4. Paste it into this field.

An inline script needs no extra request and no outside hosting. It takes precedence: when it is filled in, Public Script URL is ignored. With neither, the block runs a small built-in sample.

Public Script URL​

Loads your script from a text file on the web instead, the file Download minified saves in Export to runner. If the block's field is empty, it reads the product's 3D Bits Script Public Url metafield, and that is also how the app embed runs a published script project.

Use it for a script too large to embed comfortably, or one you want to update without touching the template, though the file may be cached. Whoever can change the file at that address changes what runs on your store, so keep it under Content then Files in your own Shopify admin. Public Script URL covers hosting and CORS.

Execute JavaScript​

Default: dispose(previousMeshes);const res = await runner.executeScript(script, inputs);update(previousMeshes, (res && res.meshes) ? res.meshes : []);

The code that runs each time the inputs change. This is an advanced setting that most people never need to touch. The default disposes the previous meshes, runs your script with the current inputs, and shows the new meshes in their place.

Your code is wrapped in an async function that receives exactly these seven arguments:

  • runner - the Bitbybit runner instance
  • script - your parametric script
  • inputs - the current variant selections and form values
  • previousMeshes - the meshes from the previous run
  • context - the 3D scene and the Bitbybit libraries, described below
  • dispose(meshes) - cleans meshes up from memory
  • update(previousMeshes, newMeshes) - replaces the contents of previousMeshes with newMeshes

The scene and the libraries are reached through context: context.bitbybit, context.Bit, context.scene, context.engine, context.BABYLON and context.GUI.

Write context.scene, not scene

scene, engine, BABYLON, GUI, bitbybit and Bit are not variables of their own. Writing scene.getMeshByName(...) throws a ReferenceError, which is caught and logged to the browser console as "Error executing custom JavaScript:" - the configurator then shows no new geometry, with nothing on the page to say why. Prefix all six with context..

Change it if you need to keep some meshes between runs, animate a change, or add your own error handling or logging. The field holds a single line, so write code that still works with its lines run together: end every statement with a semicolon and leave out // comments. Use single quotes for strings, as a double quote or a backslash stops the block from loading at all. The two examples below follow these rules. Test thoroughly: incorrect code here can break the configurator entirely.

Example: Preserve Background Meshes​

const dynamicMeshes = previousMeshes.filter(m => m.metadata?.dynamic);
const keptMeshes = previousMeshes.filter(m => !m.metadata?.dynamic);
dispose(dynamicMeshes);

const res = await runner.executeScript(script, inputs);
const newMeshes = (res && res.meshes) ? res.meshes : [];

newMeshes.forEach(m => {
if (!m.metadata) m.metadata = {};
m.metadata.dynamic = true;
});

update(previousMeshes, [...keptMeshes, ...newMeshes]);

Example: Add Fade Transition​

const oldMeshes = [...previousMeshes];
oldMeshes.forEach(m => {
context.BABYLON.Animation.CreateAndStartAnimation(
'fadeOut', m, 'visibility', 30, 15, 1, 0, 0
);
});

const res = await runner.executeScript(script, inputs);
const newMeshes = (res && res.meshes) ? res.meshes : [];

newMeshes.forEach(m => {
m.visibility = 0;
context.BABYLON.Animation.CreateAndStartAnimation(
'fadeIn', m, 'visibility', 30, 15, 0, 1, 0
);
});

setTimeout(() => dispose(oldMeshes), 500);
update(previousMeshes, newMeshes);

Geometry Kernel Options​

The kernels are the engines your script builds shapes with. Enabling all three increases loading time noticeably, so only enable the ones your script actually uses. When a script fails to run, a kernel it needs being switched off is the first thing to check.

Enable OCCT​

Default: true

OpenCascade Technology (OCCT) is a professional-grade CAD kernel, the one FreeCAD is built on, for precise boundary-representation solids. It handles boolean operations, freeform surfaces, fillets and chamfers, and is the right kernel for most parametric configurators.

It is computationally intensive, and complex operations can take seconds, so keep Show Spinner on. The OCCT tutorials teach it.

Enable JSCAD​

Default: false

JSCAD is an open-source constructive solid geometry kernel, which builds shapes by combining simple primitives with boolean operations. It has fewer features than OCCT and suits simpler shapes. You can enable it beside OCCT, and a script can then use both.

Enable Manifold​

Default: false

Manifold is a constructive solid geometry kernel with robust booleans that produces watertight meshes, which suits 3D printing. Reach for it when booleans on meshes fail in JSCAD.

Advanced Features​

Enable Key Event Listeners​

Default: false

Listens for the keyboard, so a script that reacts to key presses receives them. A typical product configurator does not need this. Enable it for something closer to a game or a walkthrough, and test that it does not get in the way of ordinary page navigation.

Fonts to Include​

Default: ["Roboto"]

Which fonts to load for 3D text, as a JSON array. They are loaded for the OCCT kernel, and text made from them is geometry that can be combined with other shapes.

["Roboto", "RobotoSlab", "Orbitron"]

You can list any of Aboreto, Bungee, IndieFlower, Lugrasimo, Orbitron, Roboto, RobotoSlab, Silkscreen, Tektur and Workbench. Each font adds load time, so include only the ones your script uses. Anything that is not a valid JSON array of names loads no fonts at all.

Scripts can also load fonts of their own. You must have the rights to use a custom font, and test it: a font with self-intersections or other geometric problems may fail to turn into a valid solid.

Settings shared with other blocks​

Each of these is documented once, in Common Settings. This is what is particular to the RUNNER block.

SettingOn this block
Runner CDN LinkAlways the full runner, as this block runs scripts.
Camera positionDefaults to [30, 10, 30], further back than the VIEWER block, because generated geometry often spans a larger area.
Camera targetDefaults to [0, 15, 0], a point above the origin.
Background ColorDefaults to #ffffff.
Show SpinnerShows on every run. Computation can take seconds, especially for complex OCCT operations or the first start of a kernel, so keep it on.
Receive Input Names As VariantsYour script reads inputs by name, so keep it on for names that stay put.
Input Collection ModeUse All Inputs only if your script reads hidden fields.
Enable Debug ModePrints the inputs as JSON, which settles whether your script should read inputs.Length or inputs.length.
Disable Inputs When ComputingEnable it only if shoppers change inputs faster than a slow script can finish.
Try to Prepend, Prepend With Query Selector, Remove Children Before PrependCommonly used to put the canvas in the product media gallery.
Show Fullscreen ButtonKeep it on, as shoppers examine generated geometry closely.

How Variants Work with RUNNER​

With the VIEWER block you configure how choices affect the model in Composer. With RUNNER your script holds that logic, reading each field on the page by name:

const inputs = Bit.getBitbybitRunnerInputs();

if (inputs.Length === "25 m") {
// Generate the largest boat
}

// Names with spaces need brackets
const boatName = inputs["Boat name"];

That is why RUNNER takes more setup: you are programming the configurator's behaviour rather than configuring it.

Common Issues​

Start with Enable Debug Mode to see the input values, and the browser console for errors. A script failing here is logged there, and the page does not show it.

The script does not run: check that Inline Script or Public Script URL is set, and that the kernels it needs are enabled.

The canvas is in the wrong place: review Try to Prepend and its selector, and try with it off to see the default position.

Inputs are not detected: try Input Collection Mode on All Inputs, and check that Receive Input Names As Variants matches what your script reads.

It is slow: disable the kernels you do not use and simplify the script. Disable Inputs When Computing keeps shoppers from stacking changes on top of a slow run.

Verified against the product in November 2026