Prefabs Overview

View as MarkdownOpen in ChatGPTOpen in Claude

A prefab is a high-level object that represents a set of rendering and SDK features.

Prefabs are divided into several types:

• On Face - prefabs that depend on a face.
• Makeup - prefabs that represent makeup features and also depend on a face.
• Top Level - prefabs that affect the entire screen and are not attached to a face.
• On Hands - prefabs that apply effects to hands.
• Sprites - prefabs that represent simple 2D sprites.
• Sounds - prefabs that represent audio.

Example prefab configuration:

{
    "scene": "effect name",
    "version": "2.0.0",

    "camera": {},
    // Top level prefabs
    "background": {
        // ...
    },
    "foreground": {
        // ...
    },
    "lut": {
        // ...
    },
    "lights": {
        // ...
    },
    "msaa": {
        // ...
    },
    // On Face
    "faces": [
        {
            // first face
            "face_prefab1": {
                //...
            },
            "makeup_prefab1": {
                //...
            }
            // ...
        },
        {
            // second face
        }
        // ..
    ],
    // Sounds
    "sounds": [
        {
            "sound_prefab1": {
                //...
            },
            "sound_prefab2": {
                //...
            }
            // ...
        }
    ],
    // Sprites
    "sprites": [
        {
            "sprite_prefab1": {
                //...
            },
            "sprite_prefab2": {
                //...
            }
            // ...
        }
        // ...
    ]
}

Where:

• scene - the name of your effect.
• version - the version of this configuration file. Always set it to 2.0.0. Earlier versions are intended for complex legacy effects.
• camera - indicates that the camera feed will be rendered on the screen.
• faces - an array of JSON objects describing the features to place on each face. For each face, define a JSON object whose keys are prefab names and whose values are the parameters for those prefabs.
• top_level_prefab - one of the top-level prefabs.
• sprites - an array of JSON objects describing sprite features.
• sounds - an array of JSON objects describing sound features.

tip

You can create an effect with any set of prefabs.

tip

You can change an effect at runtime by calling the reload_config() or reloadConfig() method:

C++

constexpr auto new_config = R"(
    {
        "camera" : {},
            "background" : {
            // ...
        }
    }
)";
effect_player->effect_manager()->reload_config(new_config);

Java

import com.banuba.sdk.player.Player

    // ...

    val newConfig =
        "" "
{
    "camera" : {},
               "background" : {
        // ...
    }
}
"" ";
    player.effectPlayer.effectManager()
        .reloadConfig(newConfig)

Swift

import BanubaEffectPlayer

// ...
let newConfig = """
{
  "camera": {},
  "background": {
      // ...
  }
}
""";
player.effectPlayer?.effectManager().reloadConfig(newConfig)

JavaScript

const new_config = 
`{
    "camera": {},
    "background": {
      // ...
    }
}`
player._effectManager.reloadConfig(new_config)

Update prefabs with JavaScript

Use evalJs() (eval_js() in C++) on the loaded effect to run JavaScript in that effect. For example, change one prefab's settings without submitting a new configuration through reloadConfig().

The prefab must already be included in the loaded configuration so that its assets and JavaScript instance exist. Call evalJs() after the effect has been loaded and applied.

Prefab names, classes, and instances

To map a prefab name to its JavaScript class name, remove the underscores and capitalize the first letter of each word. Keep the other letters unchanged:

Prefab name in JSON	JavaScript class	Instance for face index 0
eyes_whitening	EyesWhitening	bnb_eyes_whitening0
makeup_lipstick	MakeupLipstick	bnb_makeup_lipstick0
makeup_lipsgloss	MakeupLipsgloss	bnb_makeup_lipsgloss0

The class is exported by the prefab's script, for example:

const { MakeupLipstick } = require("bnb_prefabs/makeup_lipstick/scripts/index.js")

To update a configured prefab, use its existing instance. Its name is bnb_ followed by the JSON prefab name and, for indexed prefabs, the zero-based index from faces, sprites, or sounds. Top-level prefabs have no index suffix, for example bnb_background.

Short examples

With eyes_whitening configured in faces[0], set its strength to 0.5:

C++

current_effect->eval_js("bnb_eyes_whitening0.strength(0.5)", nullptr);

Java

mCurrentEffect.evalJs("bnb_eyes_whitening0.strength(0.5)", null);

Swift

currentEffect?.evalJs("bnb_eyes_whitening0.strength(0.5)", resultCallback: nil)

JavaScript

await effect.evalJs("bnb_eyes_whitening0.strength(0.5)")

To apply several settings together, call setPrefabSettings() with the same parameter object used in JSON. Include all required parameters for that prefab; this method reapplies the settings rather than merging a partial object:

await effect.evalJs(`bnb_makeup_lipstick0.setPrefabSettings({
    color: "0.88 0.47 0.61",
    finish: "shimmer",
    coverage: "high"
})`)

note

Colors are represented as three- or four-component strings. Each component is a value in the range [0, 1] or [0, 255], and components are separated by spaces. For example, 1 0 0 1 represents red. HTML-style hex strings are also accepted. For example, #00FF00 represents green; an alpha value of FF is assumed when omitted.