BulletSim
From OpenSimulator
Contents |
BulletSim
BulletSim is the module for OpenSimulator that creates virtual world physics using the Bullet Physics Engine. This module provides high performance physics as well as physical vehicle performance compatible with Second Life.
Project Information
BulletSim/Functionality lists the possible physical operations, their implementation state and any notes on their use. This is particularly useful for vehicle operations.
Building
BulletSim Architecture
BSScene
Stuff on simulation stepper. Step events (pre-step event, post-step event).
Requirement for controlling physics engine modifications with taint system (regular taints, post-taint taints).
Detail logging system.
Parameter system.
BSPhysObject
Children classes of BSPrim and BSCharacter.
Terrain
Constraints
Bullet Implementations
BulletSim is a wrapper for the Bullet physics engine. The interface from the virtual world adapting BulletSim to the physics engine is described by the abstract class BSAPITemplate. There are two instances of this class, BSAPIXNA and BSAPIUnman.
BSAPIUnman contains the connection to the unmanaged DLL/SO that is the C++ version of the Bullet physics engine. The sources and build instructions are available at git://opensimulator.org/git/opensim-libs/trunk/unmanaged/BulletSim.
BSAPIXNA is the connection to a C# version of Bullet the sources of which are hosted at https://code.google.com/p/bullet-xna/.
The selection of physics engine happens at region start time. It is specified per simulator with the following INI settings:
[Startup]
physics = BulletSim
[BulletSim]
BulletEngine = BulletUnmanaged ; The default
; BulletEngine = BulletXNA ; uncomment this line for C# version of Bullet
Managed/Unmanaged Interface
Linksets
"Actor" Architecture and the Actors
Each BulletSim physical object can have any number of "actors" attached to it. The actors register for simulation events (usually to be called before each simulation step) and change the physical parameters of the object. The currently implemented actors are:
- BSActorAvatarMove: controls movement and stairs walking of avatars;
- BSActorHover: implements vertical hovering for objects and avatars;
- BSActorLockAxis: applies a constraint to physical objects to lock one or more angular axis movement;
- BSActorMoveToTarget: moves a physical object to a location;
- BSActorSetForce: applies a continuous force to a physical object;
- BSActorSetTorque: applies a continuous torque to a physical object;
- BSDynamic (name will change): implements SecondLife(r) vehicle model.
Vehicles
See also the archived page: Vehicles
BulletSim Script Extension Functions
The physics extension interface is used by BulletSim to implement many new physics functions. The mod_invoke interface must be enabled for these functions to work.
Avatar Walking Up Stairs
The avatar movement actor include special checks to allow avatars to move up stepped objects (think stairs). The code works by checking for collisions close to the avatar's feet and, if trying to walk forward and not flying, pushing the avatar up to get over the object. This is a different algorithm than ODE which relies on the curvature of the avatar's capsule to move up and over low obstacles.
There are seven INI parameters that control stairs:
| AvatarStepHeight | The maximum height of a step. If the avatar collides with something of less than this height, it will be considered a step and the avatar will consider moving up to get over it; |
| AvatarStepAngle | The maximum angle of the collision surface to consider it a step. If set to zero, for instance, the step faces must be perfectly vertical before it would be considered a step surface. Typical value is 0.3f which allows some step variability; |
| AvatarStepGroundFudge | A small fudge factor subtracted from the computed base of the avatar when checking if the collision is close to the avatar's feet. The base of the avatar computation can be a little high (above the ground) so this factor allows comparing lower for the step. This can prevent small bumps on the ground being too small to be considered a step (which causes the bump to act like a wall); |
| AvatarApproachFactor | The angle the step must be approached. This is the radians of the angle between the avatar and the colliding step surface. This prevents walking up things when approached from a wide angle. The default of 0.6 is about a 45 degree approach angle. Setting this down to 0.3, for instance, requires the avatar to be walking nearly directly into the step to get the up actions. |
| AvatarStepUpCorrectionFactor | A multiplication factor for changing the avatar's position to get over the step. The height of the collision with the step is multiplied by this factor and that number is added to the avatar's Z coordinate. This moves the avatar up in relation to the step. If this factor is less than zero, the AvatarStepHeight is used. |
| AvatarStepForceFactor | A force factor to push the avatar up to get over the step. An up force of the step collision height times the avatar mass times this factor is applied to the avatar. These last two factors can be used in combination for moving the avatar when a step is collided with. |
| AvatarStepSmoothingSteps | when an avatar walks up the steps, collisions go on and off as the steps are hit and moved over. This is the number of simulator ticks (about 10 per second) that walking up steps will still be performed after the last step collision is sensed. This smooths out the action a little. |
The default values are:
[BulletSim]
AvatarStepHeight = 0.6
AvatarStepGroundFudge = 0.1
AvatarStepApproachFactor = 0.6
AvatarStepUpCorrectionFactor = 1.0
AvatarStepForceFactor = 2.0
AvatarStepSmoothingSteps = 1
Other Notes
Adjusting Avatar Height
As of May 13, 2013, BulletSim uses the Bullet capsule shape to approximate a standing avatar. One oddity of the capsule is its height which doesn't scale nicely in the way OpenSimulator would like. To fix this, several adjustment parameters are available to correct the avatar capsule height so that an avatar properly appears to be standing on the ground rather than floating over or sunk into the ground.
These parameters are:
| INI variable | Default | Description |
|---|---|---|
| AvatarHeightMidFudge | 0.0 | This is a fudge factor added to the 50% avatar height (about 1.87 meters). This number is added to the total height so adjusting this number moves the whole capsule up and down by roughly this distance. |
| AvatarHeightLowFudge | 0.0 | This factor is added to the height at the low end of the height scale ("0%" height which is about 1.62 meters). This number is scaled proportionally from the mid height to the low height. Adjusting this number adjusts the height of the capsule for small shapes. |
| AvatarHeightHighFudge | 0.0 | This is similar to AvatarHeightLowFudge but it is applied to the high end of height ("100%" height which is about 2.12 meters). It is also added proportionally from the mid height to the large height. |
