How can we apply physics to an effect in Banuba?

The guide below will cover the process:

Download the template filter: custom_physics
Download the required resources: resources

The guide will show you how to assemble a earrings based effect in MAYA, since in terms of axes (x-axis, y-axis, z-axis) positioning and spatial coordinate values, the Banuba engine is most similar to this suite. However, this process can be repeated in any 3D graphics suite that you prefer.

To properly position the earrings, the Working Units are set to centimeters

You can also use the head_base.fbx geometry from the resources correctly relative to the head.

For the geometry in the scene, make sure to use the following material names:

material_1, material_2, material_3, material_4.

Textures should support PBR shading and should be named according to each material as:

  • material_1_Base_Color.png
  • material_1_Metallic.png
  • material_1_Roughness.png
  • material_1_Normal.png

For gemstones, we’ll use with a special shader so use these names of materials:

diamond_1, diamond_2, diamond_3, diamond_4.

Textures should support PBR shading and should be named according to each material as:

  • diamond_1_Base_Color.png
  • diamond_1_Metallic.png
  • diamond_1_Roughness.png

The transparency of materials is stored in the Base_Color texture in the alpha channel.
For geometry with physics, it’s necessary to create a deformation rig using a bone system and bind it to the geometry through skinning.

Before skinning, it’s essential to reset the scale transformation on the bones and geometry.

If the scale on the bones and geometry differs from one, it can lead to artifacts on the surface and in the physical simulation behavior.

The position of the bones in the chain is best made elongated in a line and in the direction of gravity, in my case vertically from top to bottom. The placement of the bones themselves should be chosen directly at the point of the connection between two parts of the object.

From our experience, it’s better to avoid too many bones in a chain, and if possible, it’s better to combine several neighboring chain parts under one bone. At the end of the chain, you should add an additional bone which will not be directly connected to the object through skinning, but we will assign weight to this bone, and it will participate in physical behavior calculations. We usually add the suffix _end to the names of such bones.

Bone names should be clear, as we will adjust physical behavior by setting weights on the bones. For example, for the left and right earrings, I chose the following structure and bone names:

Since in our example we’re exporting the left and right earrings separately, We need to give different names even to identical materials from different parts. For instance, for the right earring geo_earringR for metal, we named the material material_1, and for the gem, diamond_1. For the left earring geo_earringL, we named it material_2 and diamond_2, respectively.

Before exporting, make sure to check the scale transformation. Export the right earring geo_earringR along with the deformation rig to object_1.fbx and the left earring geo_earringL with its rig to object_2.fbx.

Now you need to convert the geometry from the FBX format to the internal BSM2 format. To do this, download the converter fbx_bsm2. To convert the geometry for physics in the command line, use the parameters -hierarchy and -last_bones. The command will look similar to the following:

D:_Banuba_Tools\fbx_bsm2>fbx_bsm2 -hierarchy -last_bones object_1.fbx

Bone_R_002 → Bone_R_001
Bone_R_003 → Bone_R_002
Bone_R_004 → Bone_R_003
Bone_R_end → Bone_R_004
Materials (2):

Animations (1):
Take 001 [0.966667s]

Here, we will need the names of the bones and the order of materials in the file.
You can simply drag and drop the FBX file onto fbx_bsm2_physics.bat.
As a result, you should get object_1.bsm2. Do the same with the second file, object_2.fbx.

Save both resulting files in a subdirectory of the effect called meshes, and save the textures in a subdirectory named images.

Next, you need to edit the config.json file in the root folder of the effect. For convenience, it can be divided into several blocks.
The part with textures is called images and in our effect, it is located from lines 59 to 235

You will need to edit this part if for some reason you need to change the texture name. To do this, you will need to change the texture name in this block, as well as in the materials block.

Next, let’s look at the materials block, which in my effect is located from lines 236 to 810. It consists of several sub-blocks, each corresponding to a specific material. These blocks describe the textures used, shaders, and other surface parameters. If we change the texture name in the images block, the name also needs to be changed here.

Here you can change parameters such as:

  • blend - blending mode (“off”, “alpha”, “premul_alpha”, “screen”, “add”, “multiply”, “coverage”, “min”, “max”)
  • ztest - enable/disable depth test, default true
  • zwrite - enable/disable depth write, default true
  • colorwrite - enable/disable color write, default true
  • backfaces - if false will cull backfaces, default false

If there’s no need to change the texture names and material settings, the step of editing the previous blocks, images, and materials can be skipped. We are more interested in the blocks where the physics is set for each separate file.
In our file, they are located for object_2 from lines 895 to 954, and for object_1 from lines 955 to 1014.

Let’s consider the setup of this block using one example. Here, if needed, we can change the geometry file name in the parameter:
“mesh”: “meshes/object_1.bsm2”,

Next, you need to take the order of materials we obtained when converting the file.
Or open this BSM2 file in any HEX Editor. For instance, I use HEX Editor Neo and locate the place where the names of the materials used in the file are recorded. In our case, the first is “material_1”, and the second is “diamond_1”.

These materials should be listed in the same order in the config.json file:


Then, in the physics block, we write down the bones of our rig and set a weight value for them. This value is reciprocal, i.e., one divided by this value. Thus, the higher the value, the lesser the bone’s weight. If you set a weight value of 0, then such a bone attaches to the head’s movement. Typically, a value of 0 is set for the first or several initial bones in the hierarchy chain.
From experience, the physics behavior is more natural if the weight decreases down the bone chain

Then, apply friction to physics simulation:
“damping”: 0.98,

Additionally, there’s an option to create a collision sphere that will interact with the objects. For that you need the x y z coordinates of the center of the sphere and its radius:

Next, we indicate the value of gravity, in our case, it’s -1000 along the Y-axis.

And finally, there’s an option to change the position and rotation of the object in radians, but I do not recommend using scale for objects with physics as this might lead to undesired behavior: