All Components and Hooks

The main provider component that sets up VIVERSE authentication and physics context. Must wrap your entire application or the parts that use VIVERSE features.

Props:

Example:

<Viverse loginRequired={true} clientId="your-app-id">
  <YourGame />
</Viverse>

Creates a simple character controller with physics based on three-mesh-bvh, walking, running, jumping animations, and camera controls. Automatically uses the active VIVERSE avatar if authenticated.

Props: See SimpleCharacter Options section below for complete details.

Example:

<SimpleCharacter walk={{ speed: 3 }} run={{ speed: 6 }} jump={{ speed: 10 }}>
  {/* Optional child components */}
</SimpleCharacter>

Provides physics context for collision detection. Usually wrapped automatically by <Viverse>, but can be used standalone.

Props:

Adds visible children as static (non-moving) or kinematic (moving) objects as obstacles to the physics world.

Props:

Example:

<BvhPhysicsBody>
  <mesh>
    <boxGeometry />
    <meshStandardMaterial />
  </mesh>
</BvhPhysicsBody>

Adds visible children as sensors that detect player intersection and trigger callbacks (does not add obstacles).

Props:

Example:

<BvhPhysicsSensor onIntersectedChanged={(intersected) => console.log('currently intersected', intersected)}>
  <mesh visible={false}>
    <boxGeometry />
  </mesh>
</BvhPhysicsSensor>

A quick prototyping component that renders a textured box with the prototype material.

Props:

Example:

<PrototypeBox position={[0, 1, 0]} scale={[2, 1, 3]} color="red" />

Provides the active character model context so that animation and bone utilities can target the same model instance. Wrap any content that uses <CharacterAnimationAction>, <AdditiveCharacterAnimationAction>, <CharacterAnimationLayer>, or <CharacterModelBone>.

Props:

Example:

const model = useCharacterModelLoader({ url: 'avatar.vrm', castShadow: true })

return (
  <CharacterModelProvider model={model}>
    <RunTimeline>
      <CharacterAnimationAction url="idle.glb" />
    </RunTimeline>
    <primitive object={model.scene} />
  </CharacterModelProvider>
)

Defines a logical animation layer (e.g., "lower-body", "upper-body"). All nested animation actions inherit this layer unless they provide their own layer prop. Layers allow to manage animations when managing e.g. additive animations or animations with masks.

Props:

Example:

<RunTimeline>
  <CharacterAnimationLayer name="lower-body">
    <CharacterAnimationAction url="walk.glb" mask={lowerBodyMask} />
  </CharacterAnimationLayer>
  <CharacterAnimationLayer name="upper-body">
    <AdditiveCharacterAnimationAction
      referenceClip={{ url: 'aim-forward.glb' }}
      url="pistol-idle.glb"
      mask={upperBodyMask}
    />
  </CharacterAnimationLayer>
  <primitive object={model.scene} />
  {/* ...lights, environment... */}
  {/* masks can be created with @pmndrs/viverse animation masks */}
</RunTimeline>

Loads and plays a clip on the active character model, integrating with @react-three/timeline for lifecycle and transitions. Supports masking, cross-fading, syncing, and layering. The ref exposes the underlying Three.js AnimationAction.

Props:

Example:

<CharacterAnimationAction url="idle.glb" />

Convenience wrapper around <CharacterAnimationAction> that plays an additive version of the clip, using a provided reference pose/clip (e.g., aim offsets layered over locomotion).

Props:

Example:

<AdditiveCharacterAnimationAction
  referenceClip={{ url: 'aim-forward.glb' }}
  url="pistol-reload.glb"
  mask={upperBodyMask}
/>

Component for placing content inside the character model at specific bones.

Props:

<SimpleCharacter>
  <CharacterModelBone bone="rightHand">
    <SwordModel />
  </CharacterModelBone>
</SimpleCharacter>

Lightweight media-query based mobile detection. It subscribes to @media (hover: none) and (pointer: coarse).

import { useIsMobile } from '@react-three/viverse'

function MobileOnlyUI() {
  const isMobile = useIsMobile()
  return isMobile ? <div>Shown on mobile</div> : null
}

Actions allow to decouple specific user inputs from game/business logic. One action can be connected to multiple inputs via Action bindings (keyboard, mouse/touch, on-screen controls). For background on actions vs. action bindings and how to create custom ones, see the Actions tutorial: Create and use actions. We provide several easy to use hooks to setup default action bindings for general use cases such as pressing a button or specific use case such as locomotion using a keyboard.

useKeyboardActionBinding(jumpAction, { keys: ['Space'] })

usePointerButtonActionBinding(fireAction, { buttons: [0] }) // left mouse / primary touch

usePointerCaptureRotateZoomActionBindings({ rotationSpeed: 1000, zoomSpeed: 1000 })

usePointerLockRotateZoomActionBindings({ lockOnClick: true })

useKeyboardLocomotionActionBindings({ requiresPointerLock: false })

useScreenJoystickLocomotionActionBindings({ deadZonePx: 8, runDistancePx: 40 })

The SimpleCharacter component can be configured with a variety of props but also supports all the default group props, such as position, rotation, and scale.

Allows to configure whether the users vrm avatar should be displayed as the character model.

An array of action binding classes to instantiate for handling controls

Available Action Binding Classes provided by @pmndrs/viverse:

The SimpleCharacter uses the following animations walk, run, idle, jumpForward, jumpUp, jumpLoop, jumpDown each with the following options:

The <prototypeMaterial> component provides a textured material for prototyping using kenney.nl's prototype texture.

// As JSX element
<mesh>
  <boxGeometry />
  <prototypeMaterial color="blue" />
</mesh>