Custom Scripts

While using the out-of-the-box toolset when creating configurators is encouraged, it is occasionally necessary to make use of custom scripts. Custom scripts may be added in the same manner as any other visual action, via the action drop down on a rule.

Example Use-Case

For a clearer understanding of a "complex" configuration requirement necessitating the use of custom script actions, consider the table below.

Within this configuration experience, the user may change the length, width, and height of the coffee table. Interact with the configurator by entering values for each of the attributes within the following limits: Height (Y): Min 24" - Max 48" Length (X): Min 60" - Max 96" Width (Z): Min 12" - Max 24"

Why is a custom script action necessary?

A custom script is required to perform mathematical operations on user-entered values. The table is being re-sized using a stretch operator that takes meters as its input. Mathematical operations must be performed on the user inputs to convert user inputs into required stretch distances.

Using a Custom Script

Choosing the custom script action type exposes a field for entry of the script, allowing for use of the client-side Threekit Player API. This will execute any time a change is made to the configuration attributes. Bear in mind that the script must be deterministic, it is not a stateful script. There is no capacity to accumulate something, the script must operate on the attributes that have been created.

The code placed within the field will be run on the front end by the browser, so it needs to be compatible across most browsers (polyfill with babel can be used for this purpose).

Sample Code

The sample code below is not meant to reflect coding best practices, it is meant to be readable for the purposes of this example. The Stretch Operator is used within this example.

const config = api.configurator.getConfiguration();

const tableMeshId = api.scene.find({from: api.instanceId, name: 'Table Mesh'});

// Set Dimensions (in inches) of mesh as uploaded into Threekit
const defaults = {
    height: 31.89,
    length: 72.05,
    width: 14.96
};

// User-defined values
const newHeight = config['Height (Y)'];
const newLength = config['Length (X)'];
const newWidth = config['Width (Z)'];

// Calculate Stretches in meters
const yStretch = (newHeight - defaults.height) * 0.0254 / 2;
const xStretch = (newLength - defaults.length)  * 0.0254 / 2;
const zStretch = (newWidth - defaults.width) * 0.0254 / 2;

// Note y-transform is equal to yStretch
const yTrans = yStretch;

// Set Stretches
api.scene.set({
        from: api.instanceId,
        name: 'Table Mesh',
        plug: 'PolyMesh',
        properties: { type: 'Stretch', axis: 1 },
        property: 'stretchDistance'
    }, 
        xStretch
);
api.scene.set({
        from: api.instanceId,
        name: 'Table Mesh',
        plug: 'PolyMesh',
        properties: { type: 'Stretch', axis: 2 },
        property: 'stretchDistance'
    }, 
        yStretch
);
api.scene.set({
        from: api.instanceId,
        name: 'Table Mesh',
        plug: 'PolyMesh',
        properties: { type: 'Stretch', axis: 3 },
        property: 'stretchDistance'
    }, 
        zStretch
);

// Set y-transform to preserve location of bottom of table
api.scene.set({
        from: api.instanceId,
        name: 'Table Mesh',
        plug: 'Transform',
        property: 'translation',
    }, { 
        x: 0, 
        y : yTrans, 
        z: 0
    }
);