Parameters

This page describes our legacy parameter system which has been superseded by our new tag based parameter system.

Whilst all the features of the parameter system described here still work as explained, this is considered obsolete and should not be used anymore in new projects.

Which parameters are built-in?

All built in parameters and the expected types of their values are exported & explained in the Parameter class.

Custom parameters

Custom parameters give you the possibility to add your own parameters and implementations to your project. Let's explain the functionality with an example. Let's say we want to change the color of a light bulb with a parameter called "wattage". First, we have to declare the parameter for a Variant.

{
scene: { /* ... */ },
setup: { /* .. */ },
variants: {
'MyLightBulb': {
/* ... */
parameterDeclaration: {
'wattage': {
'type': 'select',
'options': ['1W', '20W', '100W'],
'default': '1W'
}
}
/* ... */
}
}
}

Next we have to implement what is happening, if the parameter changes. Therefore, we must implement a ParameterObserver (which is a callback function) and register it on a Variant or Element, wherever we want the parameter to be scoped. Let's say we have a VariantInstance called "MyLightBulbInstance" which Variant defines an Element called "Filament". We want to change the color of the "Filament".

const my_instance = await viewer.variantInstances.get('MyLightBulbInstance');
const light_bulb = my_instance.variant;
light_bulb.addParameterObserver('wattage', async (variant, oldValue, newValue) => {
const element = await variant.getElement('Filament');
let color = Color3.FromHexString('#aaaaaa');
switch (newValue) {
case '20W':
color = Color3.FromHexString('#33ff00');
break;
case '100W':
color = Color3.FromHexString('#ffffff');
break;
}
element.nodes.forEach(node => (node.color = color));
});

The ParameterObserver is not called if the value does not change. Now we can commit the parameter which in turn calls our code above.

const variant = await viewer.variantInstances.get('MyLightBulbInstance');
variant.commitParameter('wattage', '20W');

What else can I do? How to use parameter with string substitution.

You can even use string substitutions in the Specification. This is best explained extending the example.

{
scene: { /* ... */ },
setup: { /* ... */ },
parameters: {
'SocketVisibility': 'false',
'FilamentColor': '#ff33aa'
},
variants: {
'MyLightBulb': {
/* ... */
parameterDeclaration: {
'SocketVisibility': { type: 'boolean' },
'FilamentColor': { type: 'string' }
},
parameters: {
'Socket.visible': '${SocketVisibility}',
'Filament.color': '${FilamentColor}'
}
}
}
}

The string "${SocketVisibility}" will be substituted with the value of the committed parameter "SocketVisibility". The substitutions "live" across the whole Specification and are designed to function as helpful syntax sugar if the inheritance model is not sufficient. You can even use these substitutions when calling commitParameters or commitParameters at runtime. Here's an example.

const light_bulb_instance = await viewer.variantInstances.get('MyLightBulbInstance');
light_bulb_instance.variant.commitParameter('SocketVisibility', true);

// commit the whole `ParameterBag`
light_bulb_instance.variant.commitParameters({
SocketVisibility: true,
FilamentColor: '(50, 255, 255)',
});

Generated using TypeDoc