Skip to main content

The GUI: buttons, sliders and text over the scene

A script cannot reach the page around the editor, so it builds its interface inside the 3D view, with BabylonJS's GUI. The same interface runs wherever the script runs, in the editor, in a runner on another website, or in an app.

How a GUI is put together​

  1. A layer to draw on. advancedDynamicTexture.createFullScreenUI covers the whole view; createForMesh wraps a layer onto a mesh, for a screen inside the scene.
  2. Containers arrange controls: a stackPanel stacks them vertically or side by side, and a container holds any controls you add with addControls.
  3. Controls: textBlock, button, slider, checkbox, radioButton, colorPicker, inputText and image, each created with its size, colours and text, and each with getters and setters to change it later.

Here a full-screen layer gets one line of text:

Bitbybit Platform

A title over the 3D view in Rete

rete logoRete
Script Source (rete)
{
  "id": "rete-v2-json",
  "nodes": {
    "screen": {
      "id": "screen",
      "name": "bitbybit.babylon.gui.advancedDynamicTexture.createFullScreenUI",
      "customName": "full screen ui",
      "async": false,
      "drawable": false,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "name": "fullscreen",
        "foreground": true,
        "adaptiveScaling": false
      },
      "inputs": {},
      "position": [
        40,
        40
      ]
    },
    "title": {
      "id": "title",
      "name": "bitbybit.babylon.gui.textBlock.createTextBlock",
      "customName": "text block",
      "async": false,
      "drawable": false,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "name": "textBlockName",
        "text": "Made with bitbybit",
        "color": "#f0cebb",
        "fontSize": 48
      },
      "inputs": {},
      "position": [
        40,
        420
      ]
    },
    "controls": {
      "id": "controls",
      "name": "bitbybit.lists.createList",
      "customName": "create list",
      "async": false,
      "drawable": false,
      "data": {},
      "inputs": {
        "listElements": {
          "connections": [
            {
              "node": "title",
              "output": "result",
              "data": {}
            }
          ]
        }
      },
      "position": [
        460,
        420
      ]
    },
    "add": {
      "id": "add",
      "name": "bitbybit.babylon.gui.container.addControls",
      "customName": "add controls",
      "async": false,
      "drawable": false,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "clearControlsFirst": true
      },
      "inputs": {
        "container": {
          "connections": [
            {
              "node": "screen",
              "output": "result",
              "data": {}
            }
          ]
        },
        "controls": {
          "connections": [
            {
              "node": "controls",
              "output": "list",
              "data": {}
            }
          ]
        }
      },
      "position": [
        880,
        40
      ]
    }
  },
  "modules": {}
}

Reacting to the person​

Controls report what happens to them through BabylonJS observables: a button's click, a slider's new value, a checkbox ticked. In TypeScript, add a function to the observable, such as onValueChangedObservable on a slider, and rebuild what depends on it. In Rete, the flow components listen to observables and GUI buttons; in Blockly, the time category's observable block does.

Every function​

FunctionWhat it does
advancedDynamicTexture.createForMeshCreates a GUI texture wrapped onto a mesh, so controls added to it appear on the mesh's surface in the scene; the mesh needs texture coordinates, a plane being the usual choice.
advancedDynamicTexture.createFullScreenUICreates the full-screen layer that GUI controls are added to, drawn over the whole canvas in front of the scene when foreground is true; adaptiveScaling scales the layer with the screen's pixel density.
button.createSimpleButtonCreates a button with a text label, text color, background and font size; sizes are pixel strings or fractions of the parent, and a size left out is chosen by the engine.
button.getButtonTextReads the label currently shown on a button.
button.setButtonTextChanges the label shown on a button to the given text.
checkbox.createCheckboxCreates a checkbox that starts checked or not; checkSizeRatio is how much of the square the inner mark fills.
checkbox.createCheckboxObservableSelectorPasses through the name of a checkbox event, its checked state changing, as a typed selector for code that subscribes to checkbox events by name.
checkbox.getBackgroundReads the background color of a checkbox's square.
checkbox.getCheckSizeRatioReads how much of a checkbox's square its inner mark fills.
checkbox.getIsCheckedReads whether a checkbox is currently checked, true for on.
checkbox.setBackgroundSets the background color of a checkbox's square, as a CSS color.
checkbox.setCheckSizeRatioSets how much of a checkbox's square its inner mark fills, from 0 to 1.
checkbox.setIsCheckedChecks or unchecks a checkbox, which fires its checked changed event like a click would.
colorPicker.createColorPickerCreates a color picker starting at defaultColor; size sets both its width and height, as a pixel string or a fraction, and defaults to 300 pixels.
colorPicker.createColorPickerObservableSelectorPasses through the name of a color picker event, its value changing, as a typed selector for code that subscribes to color picker events by name.
colorPicker.getColorPickerSizeReads the size of a color picker, its width and height together.
colorPicker.getColorPickerValueReads the color a color picker currently holds, as a hex string.
colorPicker.setColorPickerSizeSets the width and height of a color picker together, as a pixel string or a fraction of the parent.
colorPicker.setColorPickerValueMoves a color picker to a hex color, which fires its value changed event like a user pick would.
container.addControlsAdds controls to a container in the given order; with clearControlsFirst true the container is emptied first, so the order is exactly the list's.
container.getBackgroundReads the background color of a container as a CSS color string.
container.getIsReadonlyReads whether a container and its children are read-only.
container.setBackgroundSets the background color of a container as a CSS color; an eight-digit hex such as #00000055 makes it translucent.
container.setIsReadonlyMakes a container and everything in it read-only or editable again.
control.changeControlAlignmentSets where a control sits inside its parent: left, center or right, and top, center or bottom.
control.changeControlPaddingSets the space kept clear around a control inside its parent, per side; a side left out keeps its padding.
control.cloneControlMakes a copy of a control with all its settings, names it and adds it to container when one is given; host is the GUI texture the copy belongs to.
control.createControlObservableSelectorPasses through the name of a control event, such as a pointer click or pointer enter, as a typed selector for code that subscribes to control events by name.
control.getColorReads the main color of a control as a CSS color string.
control.getControlByNameFinds a control by its name inside a container, searching its children too.
control.getFontSizeReads the font size of a control's text, as a string such as 24px or a number of pixels.
control.getHeightReads the height of a control, as a pixel string or a fraction of the parent.
control.getIsEnabledReads whether a control is enabled rather than dimmed and inactive.
control.getIsReadonlyReads whether a control ignores input while still being shown normally.
control.getIsVisibleReads whether a control is shown rather than hidden.
control.getWidthReads the width of a control, as a pixel string or a fraction of the parent.
control.setColorSets the main color of a control, the text color of a button or text block and the fill color of a slider or checkbox, as a CSS color.
control.setFontSizeSets the font size of a control's text, as a number of pixels or a string such as 24px.
control.setHeightSets the height of a control, as a pixel string such as 40px or a fraction of the parent from 0 to 1.
control.setIsEnabledEnables or disables a control; a disabled control is drawn dimmed and ignores input.
control.setIsReadonlyMakes a control read-only or editable again; a read-only control is shown normally but ignores input.
control.setIsVisibleShows or hides a control; a hidden control keeps its place in a stack panel's layout.
control.setWidthSets the width of a control, as a pixel string such as 200px or a fraction of the parent from 0 to 1.
image.createImageCreates an image control that loads its picture from url; sizes are pixel strings or fractions of the parent, and a size left out is chosen by the engine.
image.getSourceUrlReads the URL an image control loads its picture from.
image.setSourceUrlChanges the picture an image control shows by giving it a new URL to load.
inputText.createInputTextCreates a text field holding text, showing placeholder while it is empty, in the given colors; sizes are pixel strings or fractions of the parent.
inputText.createInputTextObservableSelectorPasses through the name of a text field event, its text changing, as a typed selector for code that subscribes to text field events by name.
inputText.getBackgroundReads the background color of a text field.
inputText.getPlaceholderReads the hint a text field shows while it is empty.
inputText.getTextReads the text a text field currently holds, as typed by the user.
inputText.setBackgroundSets the background color of a text field, as a CSS color.
inputText.setPlaceholderSets the hint a text field shows while it is empty.
inputText.setTextReplaces the text a text field holds, which fires its text changed event like typing would.
radioButton.createRadioButtonCreates a radio button in a group; checking one radio button unchecks the others of the same group.
radioButton.createRadioButtonObservableSelectorPasses through the name of a radio button event, its checked state changing, as a typed selector for code that subscribes to radio button events by name.
radioButton.getBackgroundReads the background color of a radio button's circle.
radioButton.getCheckSizeRatioReads how much of a radio button's circle its inner dot fills.
radioButton.getGroupReads the group a radio button belongs to.
radioButton.setBackgroundSets the background color of a radio button's circle, as a CSS color.
radioButton.setCheckSizeRatioSets how much of a radio button's circle its inner dot fills, from 0 to 1.
radioButton.setGroupMoves a radio button to a group; only one radio button of a group can be checked at a time.
slider.changeSliderThumbRestyles the thumb of a slider: round or square, its color and width, whether it stays inside the track and whether it is shown at all.
slider.createSliderCreates a slider that picks a number from minimum to maximum in multiples of step, starting at value.
slider.createSliderObservableSelectorPasses through the name of a slider event, its value changing, as a typed selector for code that subscribes to slider events by name.
slider.getBackgroundColorReads the color of the unfilled part of a slider's track.
slider.getBorderColorReads the color of the line around a slider's track.
slider.getDisplayThumbReads whether a slider shows its thumb or only the track.
slider.getIsThumbCircleReads whether a slider's thumb is round rather than square.
slider.getIsThumbClampedReads whether a slider's thumb stays inside the track at the ends instead of overhanging it.
slider.getIsVerticalReads whether a slider runs bottom to top rather than left to right.
slider.getMaximumReads the largest value a slider can reach.
slider.getMinimumReads the smallest value a slider can reach.
slider.getStepReads the increment a slider moves in, 0 meaning smooth movement.
slider.getThumbColorReads the color of a slider's thumb as a CSS color string.
slider.getThumbWidthReads the width of a slider's thumb, as a pixel string or a fraction.
slider.getValueReads the current value of a slider, between its minimum and maximum.
slider.setBackgroundColorSets the color of the unfilled part of a slider's track, as a CSS color.
slider.setBorderColorSets the color of the line around a slider's track, as a CSS color.
slider.setMaximumSets the largest value a slider can reach, the value at its right or top end.
slider.setMinimumSets the smallest value a slider can reach, the value at its left or bottom end.
slider.setStepSets the increment a slider moves in, so 1 gives whole numbers only and 0 lets it move smoothly.
slider.setValueMoves a slider to a value, which fires its value changed event like a user drag would.
stackPanel.createStackPanelCreates a panel that stacks its children vertically, or horizontally when isVertical is false, with spacing pixels between them.
stackPanel.getHeightReads the height of a stack panel, as a pixel string or a fraction.
stackPanel.getIsVerticalReads whether a stack panel stacks its children top to bottom.
stackPanel.getSpacingReads the gap in pixels between the children of a stack panel.
stackPanel.getWidthReads the width of a stack panel, as a pixel string or a fraction.
stackPanel.setHeightSets the height of a stack panel, as a pixel string or a fraction of the parent; a vertical panel sizes its height from its children instead.
stackPanel.setIsVerticalSwitches a stack panel between stacking its children top to bottom, when true, and left to right.
stackPanel.setSpacingSets the gap in pixels between the children of a stack panel.
stackPanel.setWidthSets the width of a stack panel, as a pixel string or a fraction of the parent; a horizontal panel sizes its width from its children instead.
textBlock.alignTextSets where the text sits inside its block: left, center or right, and top, center or bottom.
textBlock.createTextBlockCreates a block of text with a color and font size; sizes are pixel strings or fractions of the parent, and a size left out is chosen by the engine.
textBlock.createTextBlockObservableSelectorPasses through the name of a text block event, its text changing, as a typed selector for code that subscribes to text block events by name.
textBlock.getLineSpacingReads the extra space between the lines of a text block.
textBlock.getOutlineWidthReads the width of the outline around a text block's letters, 0 meaning none.
textBlock.getResizeToFitReads whether a text block resizes itself to fit its text.
textBlock.getTextReads the text a text block currently shows.
textBlock.getTextHorizontalAlignmentReads where the text sits horizontally in its block, as the engine's number for left, center or right.
textBlock.getTextVerticalAlignmentReads where the text sits vertically in its block, as the engine's number for top, center or bottom.
textBlock.getTextWrappingReads how a text block handles text wider than itself.
textBlock.setLineSpacingSets the extra space between the lines of a wrapped text block, as pixels or a string such as 4px.
textBlock.setRsizeToFitLets a text block grow or shrink to fit its text, when true, instead of keeping its set size.
textBlock.setTextChanges the text a text block shows to the given text.
textBlock.setTextOutlineDraws an outline around the letters of a text block, outlineWidth pixels wide in outlineColor, which keeps text readable over a busy scene; 0 removes it.
textBlock.setTextWrappingSets how a text block handles text wider than itself: wrap onto new lines when true, clip when false, or one of the engine's wrapping modes such as ellipsis.