Last reviewed 31 Jul 2026
Applies to
Banter VR JavaScript SDK Physics VR interaction
Difficulty Intermediate

Build Physics and Grabbable Objects in Banter

A Banter physics object normally combines a visible component, a collider, and BanterRigidbody. A handheld object adds BanterGrababble or a grab handle, while BanterHeldEvents provides controller input while the object is held.

Interactive Object Stack

Build the object in layers so its appearance, collision shape, physical movement, and grab behaviour can be checked separately.

  1. Create a GameObject and add its visible geometry or loaded model.
  2. Add a collider that matches the usable physical shape.
  3. Add a rigidbody for simulation, then add the Banter grab component for hand interaction.

Create a Basic Physics Object

The following structure creates a sphere with collision and gravity:

const ball = new BS.GameObject({
  name: "PhysicsBall",
  localPosition: new BS.Vector3(0, 1.5, 2)
});

ball.AddComponent(new BS.BanterSphere({ radius: 0.25 }));
ball.AddComponent(new BS.SphereCollider({ radius: 0.25 }));
ball.AddComponent(new BS.BanterRigidbody({
  mass: 1,
  useGravity: true,
  isKinematic: false
}));

The visual radius and collider radius are separate values. Keep them aligned unless the interaction intentionally needs a larger or smaller collision volume.

Pick the Collider Shape

The official API provides:

Collider Best match
BoxCollider Boxes, panels, rectangular props, and simple bounds.
SphereCollider Balls and round interaction zones.
CapsuleCollider Tall rounded objects and capsule-shaped bounds.
MeshCollider Collision that follows the object's mesh.

The Banter reference describes mesh collision as more expensive. It also states that a mesh collider must be convex for rigidbody interaction.

Use isTrigger: true when the volume should detect entry and exit without producing a normal physical collision response.

Configure BanterRigidbody

BanterRigidbody controls simulated movement. Its documented settings include:

  • mass
  • linear and angular drag
  • gravity
  • kinematic state
  • centre of mass
  • velocity and angular velocity
  • collision-detection mode
  • frozen position or rotation axes

The component exposes methods for applying force, relative force, force at a position, torque, explosion force, kinematic movement, and sleep state.

const rb = ball.GetComponent(BS.CT.BanterRigidbody);
rb.AddForce(
  new BS.Vector3(0, 5, 0),
  BS.ForceMode.Impulse
);

Use the official ForceMode reference to distinguish continuous force, impulse, velocity change, and acceleration.

Add Collision and Trigger Events

Add BanterColliderEvents when the GameObject must emit:

  • collision-enter
  • collision-exit
  • trigger-enter
  • trigger-exit
ball.AddComponent(new BS.BanterColliderEvents());

ball.On("collision-enter", (event) => {
  console.log(event.detail);
});

The collider defines the physical or trigger volume. BanterColliderEvents exposes the related events to the script.

Make the Object Grabbable

The Banter API spells its main grab component BanterGrababble. Use the API spelling exactly:

ball.AddComponent(new BS.BanterGrababble({
  grabType: BS.BanterGrabType.Default,
  grabRadius: 0.01
}));

BanterGrabHandle provides a simpler grab point. This is useful when the player should grab a specific part of a larger object.

Handle Input While Held

BanterHeldEvents handles trigger, button, and thumbstick input while an object is held. Its settings include sensitivity, fire rate, automatic firing, and individual input-blocking options for each hand.

Use held-input blocking only for controls that the object consumes. Restore normal input when the held interaction ends.

Surface Friction

BanterPhysicMaterial exposes dynamic and static friction:

ball.AddComponent(new BS.BanterPhysicMaterial({
  dynamicFriction: 0.4,
  staticFriction: 0.6
}));

Use physical material values to make surfaces slide or resist movement without replacing the collider or rigidbody.

Common Questions

Why does my Banter object fall through the floor?

Check that the object and floor have appropriate colliders, that the collider sizes match the geometry, and that the object's rigidbody and collision-detection settings match its movement.

Why do my collision event callbacks never run?

Add BanterColliderEvents to the GameObject and confirm the object has a collider configured for the event you expect.

Why is BanterGrabbable not recognized?

The current API name is spelled BanterGrababble. Use that exact class name from the official reference.

Official References

Related Navigation