Behaviors - michal-repo/three-mesh-ui GitHub Wiki

Behavior

Behaviors are reuseable pieces of code from three-mesh-ui/examples primarily aiming development and/or presentation purposes.

They are located in three-mesh-ui/examples folder, so feel free to use them if they fit your need.

Some behaviors from three-mesh-ui/examples:

  • Helpers: Behaviors that can help you during development
    • BoxLayoutBehavior: Visually displays margins, borders, paddings and innerSize over a Box element.
    • BoxAnchorBehavior: Visually displays anchors of a Box element.
  • Size:
    • BestFitBehavior: Automatically adapts the fontSize of a Text element in order to ensure that the rendered text, doesn't overflow its box.
  • Geometry:
    • BoundsUVBehavior: Copy and reports UV from another Object3D
  • Input: Behaviors that can help for input and interactions
    • PhysicalKeyboardFeederBehavior: Transpose physical keyboard inputs into a Text content property.
    • KeyboardSynchronizerBehavior: Trigger virtual keyboard states from physical keyboard inputs.

How to use a behavior?

Behaviors usually requires a target upon construction then requires an .attach() call in order to start acting.

When we don't need a behavior to act anymore, simply .detach.() it.

When we don't need a behavior at all, lets .clear() it before nullifying it.

// Import the existing example behavior
import BoxLayoutBehavior from 'three-mesh-ui/examples/behaviors/helpers/BoxLayoutBehavior';

const myBlock = new ThreeMeshUI.Block( {
  width: 0.1,
  height: 0.1,
  margin: [ 0.1, 0.05 ],
  padding: "0.1 0 0 0.1",
  offset: 0.001,
});

// target of the following behavior is myBlock
const myBehavior = new BoxLayoutBehavior( myBlock );

// [...]
// start acting this behavior
myBehavior.attach();

// [...]
// stop acting this behavior
myBehavior.detach();

// [...]
// remove a stopped behavior
myBehavior.clear();
myBehavior = null;

Developing behaviors

Starts by extending the ThreeMeshUI.Behavior abstract class and implementing those abstract methods.

It should looks like this:

import { Behavior } from 'three-mesh-ui';

class CustomBehavior extends Behavior{

    constructor( uiElement ) {
        super( uiElement );
    }
    
    // Implements abstract methods
    attach() { }
    detach() { }
    act() { }

}

Then this is also important to note that currently there is 3 kind of behaviors types:

  1. AfterUpdate ones: Behaviors that rely on afterUpdate calls. Those may be easiest to understand. Those behaviors only acts after each afterUpdate calls. We can rely on BoxAnchorsBehavior source code to provide a sample.
  2. AlteredProperties ones: Behaviors that would swap, replace, tweak existing properties. Those behavior requires a minimal knowledge of the 7.x.x structure. We can rely on BestFitBehavior source code to provide a sample.
  3. Others: let's be creative