Physics

Preparing for Use

In order to enable physics on the scene, please use the Enable Physics checkbox in the Physics panel under the scene tab in Blender.

_images/scene_interface_phys_enable.png

Static Physics Type

Can be used to limit the movement of other objects, for example to detect collisions with a landscape, walls and so on. In the physics settings of such an object the Static value (set by default) should be selected for the Physics Type option.

_images/physics_panel_static.png

One or multiple physics materials can be assigned to a mesh. Under the Material tab the Special: Collision panel must be activated.

_images/material_panel_physics.png

The Ghost option excludes the material from physical interactions but still notifies the application about the contact with it. An example - detecting that the character is located on a vertical ladder.

_images/water_tower.png

The Collision ID field is intended for detecting collisions with specific materials and can be left empty. An example of Collision ID usage is detecting the landscape surface a character is located on - grass, sand, wooden coating and so on.

The Margin field allows to customize the width of the zone where mesh reacts on collisions. This option improves physical collisions simulation stability.

Also, there are material physics settings in this panel. The following settings are supported: Friction, Elasticity.

The Collision Group field corresponds to the physics group which the material belongs to. The Collision Mask field defines all physics groups with which this material will interact.

Dynamic Physics Type

Intended for rigid body movement simulation.

_images/physics_dynamic.png

The Object Physics checkbox must be enabled under the object’s Physics panel. The Collision ID field is intended for detecting collisions with a specific object (for example, for detecting proximity of a FPS character to different items) and can be left empty.

In the physics settings of such an object the Rigid Body (with rotations) or Dynamic (without rotations) values can be selected for the Physics Type option. In the Collision Bounds settings the collider type can be selected - the supported types are: Box, Capsule, Sphere, Cylinder, Cone. Also, the following physics parameters can be set: Mass, Damping - for Translation and Rotation.

The Collision Group field corresponds to the physics group which the object belongs to.

The Collision Mask field defines all physics groups with which this object will interact.

_images/physics_panel_dynamic.png

Friction and Elasticity are supported for the material of such an object. When multiple materials are used on a single mesh, the physics parameters are taken from the first of them.

For the camera object the Physics Type = Dynamic parameter must be used, and the Object Physics checkbox must be enabled.

Constraints

Physical constraints are used for limiting the objects’ degrees of freedom.

_images/physics_constraints.png

Adding a physical constraint (Rigid Body Joint) to the object can be performed on the Object Constraints panel. The supported types (Pivot Type) are: Ball, Hinge, Cone Twist, Generic 6 DoF. A physical constraint can be added to one of the two interacting objects, while the other object acts as a Target. Both objects can have a static and/or dynamic physics type. In constraints (except Ball) the translation and rotation limits can be set up.

_images/physics_constraints_panel.png

Wheeled Vehicles

The model of a vehicle must consist of 6 separate objects - a chassis, 4 wheels and a steering wheel. The chassis’ mesh center should correspond to the mass center. The centers of the wheels’ and the steering wheel’s meshes should be located on the rotation axes. The steering wheel should be oriented in the local space of coordinates - X - the rotation axis, Y - to the right and Z - upwards. The object can have any names.

_images/physics_vehicle_wheeled.png

For all 6 objects: select the Part, specify the same id in the Vehicle Name field, select the right object type - Chassis, Steering Wheel, Back Right Wheel and so on. The Suspension Rest Length setting is also available for the wheels.

It is necessary to specify a realistic mass for the chassis (because the default value is only 1 kg). To do this go to the physics settings, choose the Rigid Body value for the Physics Type option and specify the required value (for example, 1000 kg) in the Mass field.

Chassis Settings

Force Max
Maximum driving force of the vehicle.
Brake Max
Maximum braking coefficient.
Suspension Compression
Damping coefficient for suspension stretching.
Suspension Stiffness
Suspension stiffness coefficient.
Suspension Damping
Suspension damping coefficient.
Wheel Friction
Friction constant between the wheels and the surface. It should be around 0.8 for realistic vehicles. But it can be increased significantly to achieve a better control (1000 and more).
Roll Influence
Decreases the wheels’ torque decreasing the probability of the vehicle overturning (0 - no torque, 1 - real physics behavior).
Max Suspension Travel Cm
Maximum suspension travel in centimeters.

For the Steering Wheel it is necessary to specify the maximum steering angle (Steering Max) and the ratio between the turn of the steering wheel and the turn of the wheels (Steering Ratio). The maximum steering angle value is specified in revolutions. A single revolution equals to 360 degrees. Therefore, if Steering Max is equal to one and Steering Ratio is equal to 10, the maximum turn of the steering wheel will be 360 degrees and the maximum turn of the front wheels will be 36 degrees.

On this stage you can export and load the scene into the engine. We recommend to create a road surface with a physics material. To choose the controlled object press the Q key in the Viewer and select the chassis. Use the W, A, S, D keys as controls.

We can additionally tweak the Damping of Translation and Rotation. This will influence the speed and inertia of the vehicle.

The friction and elasticity of the road surface material do not influence the vehicle’s behavior.

Floating Objects

_images/physics_floater.png

In order for the object to float on the water surface (an object with the Water material), it is necessary to enable the Floater panel. There are two types of floating objects: Main Body - the floating object itself and Bob - an auxiliary bob-object onto which the buoyancy will be acting. A floating object can have an unlimited number of Bob objects. This can be both meshes or Empty objects.

All objects that are part of the same floating object must have the same name in the Floater Name field.

Floating Object Settings

Floating Factor
Buoyancy coefficient.
Water Linear Damping
Linear velocity damping when the object is on the water surface (or under water). When the object is not in water, the physics settings are used.
Water Rotation Damping
Rotation damping when the object is on the water surface (or under water). When the object is not in water, the physics settings are used.

Floating Vehicles aka Watercrafts

_images/physics_boat.png

Watercrafts use some parameters from the Vehicle settings and all the settings which are similar to Floater setting. It is necessary to set the Part type Hull on the main object. Similar to a floating object a watercraft requires auxiliary Bob objects.

Watercraft Settings

Force Max
Maximum driving force of the vehicle.
Brake Max
Maximum braking coefficient.
Floating Factor
Buoyancy coefficient.
Water Linear Damping
Linear velocity damping when the object is on the water surface (or under water). When the object is not in water, the physics settings are used.
Water Rotation Damping
Rotation damping when the object is on the water surface (or under water). When the object is not in water, the physics settings are used.

Characters

_images/physics_character_object_example.png

This feature can be activated by clicking the Character check-box in the title of the eponymous tab on the Physics panel.

From the engine standpoint, the character itself is a proper physical object that can collide with other physical objects or be influenced by physical forces such as gravity and buoyant force.

Character object can be easily controlled using several API methods with a character keyword in their names. All such methods reside in the physics API module.

Character Settings

_images/physics_character_settings.png

All the settings listed here become available after activating the Character tab.

Walk Speed

This parameter sets the speed of a character walking (measured in meters per second). The lowest possible value of this parameter is zero, while the highest is 10.

Its default value is 4.

Run Speed

This is the speed of the character running (measured in meters per second). Its value can vary from zero to 20.

This parameter is set to 8 by default.

Step Height

This is the maximum height of an obstacle that character can overstep (in meters). The value of this parameter can vary from zero to 1.

Default value of this parameter is 0.250.

Jump Strength

This parameter sets the strength of the character jumping. Its minimum value is zero, while its maximum value is 50.

Set to 5 by default.

Waterline

This parameter sets up the waterline for the character object. The waterline is measured from the center of the physical shape of the object (not the object’s mesh). If an object is submerged into the water below this line, it will float. Its value can vary from -2 to 2.

It is set to zero by default.

Basic Character

Blend4Web engine has an option to quickly set up a user-controlled first-person character. Such character will only have very basic functionality, but can be set up without any programming.

To set up a basic character, follow these steps:

  1. Select an object you intend to use as a character.
  2. Enable physics for the selected object and set physics type to Dynamic or Rigid Body.
  3. Enable Character option for the object.
  4. Create a new Camera or select an existing one and set its type to Eye.

Now a basic character with an attached camera will be present in your scene.

The character can be controlled in mostly the same way as a regular Eye type camera:

  • WASD keys move the character.
  • Camera angles are controlled by arrow keys or moving the mouse while holding its left button.
  • Pressing the C key toggles fly mode (enabled by default).

Note

Only one basic character can be present in the scene. If a scene has multiple characters, the engine will use the first of them as the basic character and ignore the others.

Controlling Characters with API

Basic character described above can only provide generic functionality. If you need more control over character behavior, you should use methods from the fps module.

The most important of them is the enable_fps_controls() method which, as its name suggests, is used to initialize characters in the scene. It can be used as follows:

var m_fps = require("fps");

m_fps.enable_fps_controls();

This method should be used at the start of the application (in the load_cb function) to enable character controls.

Note

This method may conflict with the enable_camera_controls() method which is used to enable basic character described in the previous section. These two methods should not be used simultaneously.

The method also has the following optional parameters:

character sets the character object. The link to the character can be retrieved by calling the get_first_character() method. Should be used if more then one character is present in the scene.

element specifies the HTML element to which the method adds listeners.

motion_cb specifies the callback function that is called when character changes its direction.

gamepad_id specifies the ID of the gamepad plugged to the system.

forward_sens, backward_sens, right_sens, left_sens, jump_sens, fly_sens - these parameters are used to set arrays of sensor types for specific character action like walking in different directions, jumping and so on.

rotation_cb specifies the callback function that is called when a character or camera rotates.

lock_camera - setting this parameter to true will parent the scene camera to the character.

Other important methods are set_cam_sensitivity() and set_cam_smooth_factor(). The first one of them sets the sensitivity of the camera (defined by a numeric value in the range from zero to 100). The second method defines how smooth the camera moves (defined by a value in the range from 0 to 1.0).

Character States

Character states are constant values that represent current behavior of the character (does it currently walk or fly or do anything else). Every character present in a scene always have one and only one state.

Available character states:

CS_CLIMB - a character is climbing.

CS_FLY - a character is flying.

CS_RUN - a character is running.

CS_STAY - a character does not move.

CS_WALK - a character is walking.

Current state of a specific character can be retrieved using the get_character_state() method, while a specific state can be assigned to a character with the switch_state() method. The following example shows how these two methods can be used:

var m_fps = require("fps");

var current_state = m_fps.get_character_state();

if (current_state == m_fps.CS_FLY)
    m_fps.switch_state(m_fps.CS_WALK);

Action Binding

The fps module also provides means for binding various actions to character events. The bind_action() method is used for this:

var m_fps = require("fps");
var m_ctl = require("controls");

var action_cb = function(value) {
    console.log("Q key pressed.");
}

m_fps.bind_action(m_fps.AT_PRESSED, [m_ctl.KEY_Q], action_cb);

This method features the following parameters:

  • the first parameter is the type of action:

    AT_CONTINUOUS - an input type that detects a continuous user action such as mouse movement, keyboard key held down, gamepad stick tilt etc.

    AT_PRESSED - this input type detects a discrete user action, e.g. pressing a button.

    AT_RELEASED - an input type that detects button (mouse, gamepad or keyboard) being released.

  • the second parameter defines an array of sensor types (such as keyboard keys, gamepad buttons or mouse actions).

  • action_cb is a callback function that will be called each time user performs action defined by the first parameter.

Use in Applications

The physics system is implemented in the uranium.js module and loaded separately from the engine’s main code. The uranium.js module itself is a modification of the Bullet physics engine, which is ported to work in browsers. In order to activate the physics system, it is enough to put the uranium.js and uranium.js.mem files in the same directory as the source code of the application.

Another way is to explicitly specify the loading path of the uranium.js module by using the following API method:

m_config.set("physics_uranium_path", ".../uranium.js");

Note

When applications are developed within the SDK, the path to the physics engine is detected automatically.

If your application does not use physics, we recommend you to turn off the Enable Physics flag in the Physics panel under the scene tab in Blender. It is also possible to forcibly disable loading of the uranium.js module by calling the following method before initialization of the engine:

m_config.set("physics_enabled", false);

Physics subsystem is implemented in the “uranium” module and is loaded independently from the main engine code. The “uranium” module is a modification of the Bullet physics engine ported to work in web browsers.

Blend4Web physics engine comes in two variations: the one compiled using WebAssembly (uranium_wasm.js and uranium_wasm.wasm files) is used by default, while the other version, compiled with asm.js (uranium.js and uranium.js.mem) can be used as a fallback. The WebAssembly version is smaller in size, can be initialized quicker and using it might improve the stability and performance of the application. However, at the moment not every browser supports WebAssembly, so, if this technology is not available, the asm.js version of the physics engine is used instead.

By default, physics engine is plugged in if the scene contains objects with physics enabled. You can manually disable physics by setting the Enable Physics option on the Scene -> Physics panel to OFF. You can also uncheck the Use Physics flag on the project configuration page in the Project Manager to exclude physics engine files from the build version of your project.

Note

Physics is not supported in WebPlayer HTML type projects and in the scenes exported into HTML.

Several flags for configuring physics engine are available in the init() method that is used to initialize the application:

physics_enabled - load physics engine to use physics in the application. Set to true by default.

physics_uranium_path - the relative path to the folder containing the physics engine files (the uranium_wasm.js, uranium_wasm.wasm, uranium.js and uranium.js.mem files). Use this parameter if you need to place physics engine files in a custom location.

physics_use_wasm - if this paraemter is set to true, WebAssembly version is used. If it is set to false, the asm.js version is used instead. Default value is true.

physics_use_workers - calculate physics in a separate thread using a worker (if this parameter is set to true), or in the main thread (if it is set to false). Default value is true.