Viverse

https://pmndrs.github.io/viverse
Admin
Viverse is a project by Poimandres, likely related to 3D or virtual experiences, as suggested by the...
Tokens:17,976
Snippets:75
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Viverse First Person Scene Setup

Source: https://pmndrs.github.io/viverse/tutorials/first-person

A complete example of setting up a Viverse scene with first-person controls, including Sky, lighting, SimpleCharacter, and physics.

```jsx
import { Sky } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'
import {
  Viverse,
  SimpleCharacter,
  BvhPhysicsBody,
  PrototypeBox,
  FirstPersonCharacterCameraBehavior,
  PointerLockInput,
  LocomotionKeyboardInput,
} from '@react-three/viverse'

export default function App() {
return (
<Canvas
onClick={(e) => (e.target as HTMLElement).requestPointerLock()}
style={{ position: 'absolute', inset: '0', touchAction: 'none' }}
>
<Viverse>
<Sky />
<directionalLight intensity={1.2} position={[-10, 10, -10]} />
<ambientLight intensity={1} />
<SimpleCharacter
model={false}
input={[LocomotionKeyboardInput, PointerLockInput]}
cameraBehavior={FirstPersonCharacterCameraBehavior}
/>
<BvhPhysicsBody>
<PrototypeBox scale={[10, 1, 15]} position={[0, -0.5, 0]} />
</BvhPhysicsBody>
</Viverse>
</Canvas>
)
}
```

--------------------------------

### Install Dependencies with npm

Source: https://pmndrs.github.io/viverse/without-react/introduction

Installs the necessary packages for the project, including Three.js, @pmndrs/viverse, @pmndrs/uikit, @viverse/sdk, and Vite for development.

```bash
npm init -y
npm install three @pmndrs/viverse @pmndrs/uikit @viverse/sdk
npm install -D vite
```

--------------------------------

### Install Dependencies

Source: https://pmndrs.github.io/viverse/tutorials/simple-game

Installs the necessary libraries for building the game, including three.js, @react-three/fiber, @react-three/viverse, and @react-three/drei.

```bash
npm install three @react-three/fiber @react-three/viverse @react-three/drei
```

--------------------------------

### Install VIVERSE CLI

Source: https://pmndrs.github.io/viverse/tutorials/publish-to-viverse

Installs the official VIVERSE command-line interface globally using npm.

```bash
npm install -g @viverse/cli
```

--------------------------------

### Install Viverse Toolkit

Source: https://pmndrs.github.io/viverse/getting-started/index

Installs the necessary packages for using the Viverse toolkit with Three.js and React Three Fiber.

```bash
npm install three @react-three/fiber @react-three/viverse
```

--------------------------------

### Virtual Reality Example (WebXR)

Source: https://pmndrs.github.io/viverse/getting-started/examples

A virtual reality example using WebXR, enabling immersive experiences with VR headsets and controllers.

```javascript
import { VRButton, XR } from '@react-three/xr';
import { Canvas } from '@react-three/fiber';

function VRScene() {
  return (
    <>
      <VRButton />
      <Canvas>
        <XR>
          {/* VR content */}
        </XR>
      </Canvas>
    </>
  );
}
```

--------------------------------

### Simple Game Example (Vanilla Three.js)

Source: https://pmndrs.github.io/viverse/getting-started/examples

A simple game example using vanilla Three.js, demonstrating core Three.js functionalities without a specific React integration.

```javascript
import * as THREE from 'three';

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Game logic and rendering loop will follow
```

--------------------------------

### Installing @react-three/uikit

Source: https://pmndrs.github.io/viverse/tutorials/access-avatar-and-profile

Provides the npm command to install the `@react-three/uikit` library, which is necessary for creating 3D UI elements with an HTML-like syntax.

```bash
npm install @react-three/uikit

```

--------------------------------

### Simple Game Example (React Three Viverse)

Source: https://pmndrs.github.io/viverse/getting-started/examples

A basic game example demonstrating the use of @react-three/viverse. This snippet likely involves setting up a scene and player interactions.

```javascript
import React from 'react';
import { ViverseCanvas } from '@react-three/viverse';

function GameScene() {
  return (
    <ViverseCanvas>
      {/* Game elements will go here */}
    </ViverseCanvas>
  );
}

export default GameScene;
```

--------------------------------

### Augmented Reality Example (WebXR)

Source: https://pmndrs.github.io/viverse/getting-started/examples

An augmented reality example utilizing WebXR, likely involving camera feed and virtual object placement in a real-world environment.

```javascript
import { VRButton, ARButton, XR } from '@react-three/xr';
import { Canvas } from '@react-three/fiber';

function ARScene() {
  return (
    <>
      <ARButton />
      <Canvas>
        <XR>
          {/* AR content */}
        </XR>
      </Canvas>
    </>
  );
}
```

--------------------------------

### App Component Setup

Source: https://pmndrs.github.io/viverse/tutorials/simple-game

Sets up the main application component with a Canvas for rendering the 3D scene, including Viverse integration and camera configuration.

```javascript
import { Suspense } from "react"
import { Canvas } from '@react-three/fiber'
import { Viverse } from '@react-three/viverse'
import { Scene } from "./Scene"

export default function App() {
return (
<Canvas
style={{ position: "absolute", inset: "0", touchAction: "none" }}
camera={{ fov: 90, position: [0, 2, 2] }}
shadows
>
<Suspense fallback={null}>
<Viverse>
<Scene />
</Viverse>
</Suspense>
</Canvas>
)
}
```

--------------------------------

### Install Viverse Toolkit

Source: https://pmndrs.github.io/viverse/index

Installs the necessary packages for using Viverse with Three.js and React Three Fiber.

```bash
npm install three @react-three/fiber @react-three/viverse

```

--------------------------------

### Basic Three.js Setup and Render Loop

Source: https://pmndrs.github.io/viverse/without-react/introduction

Initializes a Three.js scene, camera, and renderer. It includes a render loop that updates the scene based on time delta and handles window resizing to maintain aspect ratio and pixel density.

```javascript
import {
  PerspectiveCamera,
  Scene,
  WebGLRenderer,
  Clock,
} from 'three'
// Create camera, scene, and renderer
const camera = new PerspectiveCamera(90)
camera.position.z = 1
camera.position.y = 1
const scene = new Scene()
const canvas = document.getElementById('root') as HTMLCanvasElement
const renderer = new WebGLRenderer({
  antialias: true,
  canvas,
  powerPreference: 'high-performance',
  alpha: true
})
const clock = new Clock()
clock.start()
// Basic render loop
renderer.setAnimationLoop(() => {
  const delta = clock.getDelta()
  renderer.render(scene, camera)
})
// Handle window resizing
function updateSize() {
  renderer.setSize(window.innerWidth, window.innerHeight)
  renderer.setPixelRatio(window.devicePixelRatio)
  camera.aspect = window.innerWidth / window.innerHeight
  camera.updateProjectionMatrix()
}
updateSize()
window.addEventListener('resize', updateSize)
```

--------------------------------

### Install @react-three/xr

Source: https://pmndrs.github.io/viverse/tutorials/augmented-and-virtual-reality

Installs the necessary package for adding XR capabilities to your project. This is a prerequisite for implementing AR and VR features.

```bash
npm install @react-three/xr

```

--------------------------------

### Basic VR App Setup with @react-three/viverse

Source: https://pmndrs.github.io/viverse/tutorials/augmented-and-virtual-reality

Sets up a basic VR application using @react-three/viverse and @react-three/xr. It configures the canvas for VR and includes the Scene component within the XR context.

```javascript
import { Canvas } from '@react-three/fiber'
import { Viverse } from '@react-three/viverse'
import { XR, createXRStore } from '@react-three/xr'
import { Scene } from './Scene'

const store = createXRStore({ offerSession: 'immersive-vr' })

export default function App() {
return (
  <Viverse>
    <Canvas
      style={{ position: "absolute", inset: "0", touchAction: "none" }}
      camera={{ fov: 90, position: [0, 2, 2] }}
      shadows
      gl={{ antialias: true, localClippingEnabled: true }}
    >
      <XR store={store}>
          <Scene />
      </XR>
    </Canvas>
  </Viverse>
)
}
```

--------------------------------

### Basic Viverse App with React Three Fiber

Source: https://pmndrs.github.io/viverse/getting-started/index

A fundamental example of setting up a Viverse application using React Three Fiber. It includes essential components like Sky, directionalLight, ambientLight, SimpleCharacter, and PrototypeBox within a Canvas.

```javascript
import { Sky } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'
import { Viverse, SimpleCharacter, BvhPhysicsBody, PrototypeBox } from '@react-three/viverse'
  
export default function App() {
return (
<Canvas shadows style={{ position: "absolute", inset: "0", touchAction: "none" }}>
<Viverse>
<Sky />
<directionalLight intensity={1.2} position={[-10, 10, -10]} castShadow />
<ambientLight intensity={1} />
<SimpleCharacter />
<BvhPhysicsBody>
<PrototypeBox scale={[10, 1, 15]} position={[0, -0.5, 0]} />
</BvhPhysicsBody>
</Viverse>
</Canvas>
)
}
```

--------------------------------

### App Component Setup with Viverse

Source: https://pmndrs.github.io/viverse/tutorials/access-avatar-and-profile

Sets up the main application canvas using React Three Fiber and integrates Viverse components, including a Sky, directional light, ambient light, a SimpleCharacter, and a PrototypeBox with physics.

```jsx
import { Sky } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'
import { Viverse, SimpleCharacter, BvhPhysicsBody, PrototypeBox } from '@react-three/viverse'
import { PlayerTag } from "./Playertag"

export default function App() {
return (
<Canvas shadows style={{ position: "absolute", inset: "0", touchAction: "none" }}>
<Viverse>
<Sky />
<directionalLight intensity={1.2} position={[-10, 10, -10]} castShadow />
<ambientLight intensity={1} />
<SimpleCharacter>
<PlayerTag />
</SimpleCharacter>
<BvhPhysicsBody>
<PrototypeBox scale={[10, 1, 15]} position={[0, -0.5, 0]} />
</BvhPhysicsBody>
</Viverse>
</Canvas>
)
}
```

--------------------------------

### Viverse App Setup with Character and Item

Source: https://pmndrs.github.io/viverse/tutorials/equipping-items

Sets up a Viverse canvas with a Sky, directional and ambient lights, a SimpleCharacter, and attaches a sword model to the character's right hand using CharacterModelBone. This code snippet illustrates the core functionality of equipping items.

```jsx
import { Sky } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'
import { Viverse, SimpleCharacter, BvhPhysicsBody, PrototypeBox, CharacterModelBone } from '@react-three/viverse'
  
export default function App() {
return (
<Canvas shadows style={{ position: "absolute", inset: "0", touchAction: "none" }}>
<Viverse>
<Sky />
<directionalLight intensity={1.2} position={[-10, 10, -10]} castShadow />
<ambientLight intensity={1} />
<SimpleCharacter>
<CharacterModelBone bone="rightHand">
<group
scale={0.5}
position-y={-0.02}
position-x={0.07}
rotation-z={-(0.2 * Math.PI) / 2}
rotation-x={-(1 * Math.PI) / 2}
>
{/* Blade */}
<mesh position={[0, 0.8, 0]} castShadow>
<boxGeometry args={[0.08, 1.9, 0.04]} />
<meshStandardMaterial color="#c0c0c0" metalness={0.9} roughness={0.1} />
</mesh>
{/* Handle */}
<mesh position={[0, 0.2, 0]} castShadow>
<boxGeometry args={[0.3, 0.04, 0.04]} />
<meshStandardMaterial color="#654321" metalness={0.1} roughness={0.8} />
</mesh>
</group>
</CharacterModelBone>
</SimpleCharacter>
<BvhPhysicsBody>
</BvhPhysicsBody>
</Viverse>
</Canvas>)
```

--------------------------------

### PrototypeMaterial Usage

Source: https://pmndrs.github.io/viverse/getting-started/all-components-and-hooks

Example of using the PrototypeMaterial component in JSX to apply a textured material to a mesh. It demonstrates setting the color and how to access material properties.

```jsx
<mesh>
  <boxGeometry />
  <prototypeMaterial color="blue" />
</mesh>
```

--------------------------------

### Provide App ID to VIVERSE Component (Vite)

Source: https://pmndrs.github.io/viverse/tutorials/publish-to-viverse

Integrates the VIVERSE component into your application, passing the App ID via environment variables. This example assumes usage with Vite.

```javascript
<Viverse clientId={import.meta.env.VITE_VIVERSE_APP_ID}><YourGame /></Viverse>
```

--------------------------------

### Deploy Application to VIVERSE

Source: https://pmndrs.github.io/viverse/tutorials/publish-to-viverse

Deploys your built application to the VIVERSE platform. Replace `your-build-output-directly-here` with the path to your build output and `your-app-id-here` with your actual App ID.

```bash
viverse-cli app publish your-build-output-directly-here --app-id your-app-id-here
```

--------------------------------

### Authenticate VIVERSE CLI

Source: https://pmndrs.github.io/viverse/tutorials/publish-to-viverse

Logs into your VIVERSE account using the CLI to enable app creation and deployment.

```bash
viverse-cli auth login
```

--------------------------------

### HTML Structure for VIVERSE App

Source: https://pmndrs.github.io/viverse/without-react/introduction

Sets up the basic HTML structure for the VIVERSE application, including a canvas element for rendering and meta tags for responsiveness. It also includes a script tag to load the main application logic.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>VIVERSE Vanilla Game</title>
    <script async type="module" src="./index.ts"></script>
</head>
<body style="touch-action: none; margin: 0; position: relative; width: 100dvw; height: 100dvh; overflow: hidden;">
    <canvas id="root" style="position: absolute; inset: 0;"></canvas>
</body>
</html>
```

--------------------------------

### Remove VIVERSE Integrations Example

Source: https://pmndrs.github.io/viverse/tutorials/remove-viverse-integrations

This code snippet demonstrates how to remove VIVERSE integrations by replacing the `<Viverse>` component with `<BvhPhysicsWorld>` and utilizing other physics-related components from `@react-three/viverse`.

```jsx
import { Sky } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'
import { BvhPhysicsWorld, SimpleCharacter, BvhPhysicsBody, PrototypeBox } from '@react-three/viverse'

export default function App() {
return (
<Canvas shadows style={{ position: "absolute", inset: "0", touchAction: "none" }}>
<BvhPhysicsWorld>
<Sky />
<directionalLight intensity={1.2} position={[-10, 10, -10]} castShadow />
<ambientLight intensity={1} />
<SimpleCharacter />
<BvhPhysicsBody>
<PrototypeBox scale={[10, 1, 15]} position={[0, -0.5, 0]} />
</BvhPhysicsBody>
</BvhPhysicsWorld>
</Canvas>
)
}
```

--------------------------------

### Create VIVERSE App

Source: https://pmndrs.github.io/viverse/tutorials/publish-to-viverse

Creates a new app entry on the VIVERSE platform. Remember to note the generated App ID for future use.

```bash
viverse-cli app create
```

--------------------------------

### Vite Dev Script Configuration

Source: https://pmndrs.github.io/viverse/without-react/introduction

Adds a 'dev' script to the package.json file to run the Vite development server with host mode enabled.

```json
{
  "scripts": {
    "dev": "vite --host"
  }
}
```

--------------------------------

### Viverse Client Integration

Source: https://pmndrs.github.io/viverse/without-react/introduction

Connects to Viverse services to fetch user profiles and avatars. Initializes the Client with a Viverse App ID from environment variables and then uses AvatarClient to retrieve profile information. The character creation is updated to use the fetched avatar URL.

```javascript
import { Client } from '@viverse/sdk'
import AvatarClient from '@viverse/sdk/avatar-client'
// Add before character setup
const client = import.meta.env.VITE_VIVERSE_APP_ID == null
  ? undefined
  : new Client({ 
      clientId: import.meta.env.VITE_VIVERSE_APP_ID, 
      domain: 'https://account.htcvive.com/' 
    })
const auth = await client?.checkAuth()
const avatarClient = auth == null 
  ? undefined 
  : new AvatarClient({ 
      token: auth?.access_token, 
      baseURL: 'https://sdk-api.viverse.com/' 
    })
const profile = (await avatarClient?.getProfile()) ?? {
  name: 'Anonymous',
  activeAvatar: { headIconUrl: 'https://picsum.photos/200', vrmUrl: undefined },
}
// Update character creation to use profile avatar
const character = new SimpleCharacter(camera, world, canvas, { 
  model: { url: profile.activeAvatar?.vrmUrl, type: "vrm" } 
})
```

--------------------------------

### Viverse App ID Configuration

Source: https://pmndrs.github.io/viverse/without-react/introduction

Specifies how to configure the Viverse App ID in a production environment using a `.env.production` file for Vite projects.

```dotenv
VITE_VIVERSE_APP_ID=your_viverse_app_id_here
```

--------------------------------

### Creating a 3D UI Card with @react-three/uikit

Source: https://pmndrs.github.io/viverse/tutorials/access-avatar-and-profile

Illustrates how to use `@react-three/uikit` components like `Root`, `Image`, and `Text` to create a styled card-like layout in 3D space, utilizing flexbox for arrangement.

```jsx
<Root
  depthTest={false}
  renderOrder={1}
  backgroundOpacity={0.5}
  borderRadius={10}
  paddingX={2}
  height={20}
  backgroundColor="white"
  flexDirection="row"
  alignItems="center"
  gap={4}
><Image 
    width={16} 
    height={16} 
    borderRadius={14} 
    src={profile.activeAvatar?.headIconUrl} 
  /><Text fontWeight="bold" fontSize={12} marginRight={3}>{profile.name}</Text></Root>

```

--------------------------------

### Set Up First Person Input Controls

Source: https://pmndrs.github.io/viverse/tutorials/first-person

Configures the SimpleCharacter to use keyboard for movement and mouse for camera rotation, enabling standard first-person gameplay controls.

```jsx
<SimpleCharacter
  input={[LocomotionKeyboardInput, PointerLockInput]}
  // ... other props
/>
```

--------------------------------

### SimpleCharacter Animations

Source: https://pmndrs.github.io/viverse/getting-started/all-components-and-hooks

Details on animations available for the SimpleCharacter, including their types, URLs, and specific playback options like trimming and scaling.

```APIDOC
SimpleCharacter Animations:
  walk, run, idle, jumpForward, jumpUp, jumpLoop, jumpDown:
    type: 'mixamo' | 'gltf' | 'vrma' - Animation file type
    url: string - Animation file URL
    removeXZMovement: boolean - Remove horizontal movement from animation
    trimTime: { start?: number; end?: number } - Trim animation timing
    scaleTime: number - Scale animation playback speed
```

--------------------------------

### Basic AR App Structure with @react-three/fiber

Source: https://pmndrs.github.io/viverse/tutorials/augmented-and-virtual-reality

Demonstrates the fundamental structure of an AR application using @react-three/fiber and @react-three/xr. It includes setting up the canvas, XR components, and the main scene.

```typescript
import { Canvas } from '@react-three/fiber'
import { Viverse } from '@react-three/viverse'
import { XR, XROrigin, createXRStore } from '@react-three/xr'
import { Scene } from './Scene'

const store = createXRStore({ offerSession: 'immersive-ar' })

export default function App() {
  return (
    <Viverse>
      <Canvas
        style={{ position: "absolute", inset: "0", touchAction: "none" }}
        camera={{ fov: 90, position: [0, 2, 2] }}
        shadows
        gl={{ antialias: true, localClippingEnabled: true }}
      >
        <XR store={store}>
          <XROrigin scale={10} position-y={-8} position-z={10} />
          <Scene />
        </XR>
      </Canvas>
    </Viverse>
  )
}

```

--------------------------------

### Basic Viverse App with React Three Fiber

Source: https://pmndrs.github.io/viverse/index

A simple React Three Fiber application demonstrating the use of Viverse components like Viverse, Sky, SimpleCharacter, BvhPhysicsBody, and PrototypeBox.

```javascript
import { Sky } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'
import { Viverse, SimpleCharacter, BvhPhysicsBody, PrototypeBox } from '@react-three/viverse'
  
export default function App() {
return (
<Canvas shadows style={{ position: "absolute", inset: "0", touchAction: "none" }}>
<Viverse>
<Sky />
<directionalLight intensity={1.2} position={[-10, 10, -10]} castShadow />
<ambientLight intensity={1} />
<SimpleCharacter />
<BvhPhysicsBody>
<PrototypeBox scale={[10, 1, 15]} position={[0, -0.5, 0]} />
</BvhPhysicsBody>
</Viverse>
</Canvas>
)
}

```

--------------------------------

### Viverse Provider Component

Source: https://pmndrs.github.io/viverse/getting-started/all-components-and-hooks

The main provider component that sets up VIVERSE authentication and physics context. It must wrap your entire application or the parts that use VIVERSE features. It handles authentication, client ID, and domain settings.

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

--------------------------------

### Loading 3D Models with GLTFLoader

Source: https://pmndrs.github.io/viverse/without-react/introduction

Loads a 3D environment model (e.g., 'map.glb') using Three.js's GLTFLoader. It ensures that loaded objects have shadows enabled for both casting and receiving.

```javascript
import { GLTFLoader } from 'three/examples/jsm/Addons.js'
// Add after sky setup
const gltfLoader = new GLTFLoader()
const ground = await gltfLoader.loadAsync('./map.glb')
ground.scene.traverse((object) => {
  object.castShadow = true
  object.receiveShadow = true
})
scene.add(ground.scene)
```

--------------------------------

### Complete PlayerTag Component

Source: https://pmndrs.github.io/viverse/tutorials/access-avatar-and-profile

Combines profile fetching, UI rendering with `@react-three/uikit`, and camera-facing logic using `useFrame` to create a dynamic player tag component.

```jsx
import { useViverseProfile } from '@react-three/viverse'
import { Root, Image, Text } from '@react-three/uikit'
import { useRef } from 'react'
import { useFrame } from '@react-three/fiber'
import { Group } from 'three'
export function PlayerTag() {
  const profile = useViverseProfile() ?? {
    name: 'Anonymous',
    activeAvatar: { headIconUrl: 'https://picsum.photos/200' },
  }
  const ref = useRef<Group>(null)
  // Make the tag always face the camera
  useFrame((state) => {
    if (ref.current == null) {
      return
    }
    ref.current.quaternion.copy(state.camera.quaternion)
  })
  return (
    <group ref={ref} position-y={2.15}><Root
        depthTest={false}
        renderOrder={1}
        backgroundOpacity={0.5}
        borderRadius={10}
        paddingX={2}
        height={20}
        backgroundColor="white"
        flexDirection="row"
        alignItems="center"
        gap={4}
      ><Image 
          width={16} 
          height={16} 
          borderRadius={14} 
          src={profile.activeAvatar?.headIconUrl} 
        /><Text fontWeight="bold" fontSize={12} marginRight={3}>{profile.name}</Text></Root></group>
  )
}

```

--------------------------------

### Set Up XR Store for AR

Source: https://pmndrs.github.io/viverse/tutorials/augmented-and-virtual-reality

Configures the XR store to enable Augmented Reality experiences. The `offerSession: 'immersive-ar'` option specifically targets AR functionality.

```typescript
import { XR, XROrigin, createXRStore } from '@react-three/xr'
const store = createXRStore({ offerSession: 'immersive-ar' })

```

--------------------------------

### Player Tag UI Implementation

Source: https://pmndrs.github.io/viverse/without-react/introduction

Adds a floating player tag UI above the character. It configures the renderer for UI rendering, creates a UI container with styling, and adds an image and text to display the player's avatar and name. The render loop is updated to include UI updates and rotate the player tag to face the camera.

```javascript
import { Group } from 'three'
import { Container, withOpacity, Image, Text, reversePainterSortStable } from '@pmndrs/uikit'
// Configure renderer for UI rendering
renderer.setTransparentSort(reversePainterSortStable)
renderer.localClippingEnabled = true
// Create player tag
const playerTag = new Group()
character.add(playerTag)
playerTag.position.y = 2.15
const container = new Container({
  depthTest: false,
  renderOrder: 1,
  '*': {
    depthTest: false,
    renderOrder: 1,
  },
  borderRadius: 10,
  paddingX: 2,
  height: 20,
  backgroundColor: withOpacity('white', 0.5),
  flexDirection: 'row',
  alignItems: 'center',
  gap: 4,
})
playerTag.add(container)
const playerImage = new Image({ 
  width: 16, 
  height: 16, 
  borderRadius: 8, 
  src: profile.activeAvatar?.headIconUrl 
})
container.add(playerImage)
const playerText = new Text({ 
  fontWeight: 'bold', 
  fontSize: 12, 
  marginRight: 3, 
  text: profile.name 
})
container.add(playerText)
// Update render loop to include UI updates
renderer.setAnimationLoop(() => {
  const delta = clock.getDelta()
  character.update(delta)
  renderer.render(scene, camera)
  // Update the UI
  container.update(delta)
  // Rotate the player tag to face the camera
  playerTag.quaternion.copy(camera.quaternion)
  // Respawn player when they fall down
  if (character.position.y < -10) {
    character.position.set(0, 0, 0)
  }
})
```

--------------------------------

### Scene Component with Sky and Lighting

Source: https://pmndrs.github.io/viverse/tutorials/simple-game

Defines the Scene component, adding a Sky background and basic lighting (directional and ambient) for the 3D environment.

```javascript
import { Sky } from '@react-three/drei'
export function Scene() {
  return (
    <>{/* Environment */}<Sky />{/* Basic lighting */}<directionalLight
        intensity={1.2}
        position={[5, 10, 10]}
        castShadow
      /><ambientLight intensity={1} /></>)
}
```

--------------------------------

### cameraBehavior Options

Source: https://pmndrs.github.io/viverse/getting-started/all-components-and-hooks

Configurable options for camera behavior, including collision, rotation, and zoom settings. These options allow fine-tuning of camera interactions within the Viverse environment.

```APIDOC
cameraBehavior:
  collision: object | boolean - Enable camera collision (default: true)
    offset: number - Collision offset distance (default: 0.2)
  characterBaseOffset: Vector3 | [number, number, number] - Camera position relative to character (default: [0, 1.3, 0])
  rotation: object | boolean - Enable camera rotation (default: true)
    minPitch: number - Minimum pitch angle (default: -Math.PI/2)
    maxPitch: number - Maximum pitch angle (default: Math.PI/2)
    minYaw: number - Minimum yaw angle (default: -Infinity)
    maxYaw: number - Maximum yaw angle (default: +Infinity)
    speed: number - Rotation speed multiplier (default: 1000)
  zoom: object | boolean - Enable camera zoom (default: true)
    speed: number - Zoom speed multiplier (default: 1000)
    minDistance: number - Minimum camera distance (default: 1)
    maxDistance: number - Maximum camera distance (default: 7)
```

--------------------------------

### Implementing Lighting and Shadows in Three.js

Source: https://pmndrs.github.io/viverse/without-react/introduction

Adds directional and ambient lighting to the scene to illuminate the 3D environment. It configures shadow properties for the directional light and enables shadow mapping in the renderer.

```javascript
import { AmbientLight, DirectionalLight } from 'three'
// Add after sky setup
const dirLight = new DirectionalLight('white', 1.0)
dirLight.shadow.bias = -0.001
dirLight.shadow.mapSize.set(1024, 1024)
dirLight.shadow.camera.left = -100
dirLight.shadow.camera.right = 100
dirLight.shadow.camera.top = 100
dirLight.shadow.camera.bottom = -50
dirLight.castShadow = true
dirLight.position.set(10, 10, 10)
scene.add(dirLight)
scene.add(new AmbientLight('white', 0.3))
// Enable shadows in renderer
renderer.shadowMap.enabled = true
```

--------------------------------

### Import CharacterModelBone Component

Source: https://pmndrs.github.io/viverse/tutorials/equipping-items

Demonstrates the necessary import statement for using the CharacterModelBone component from the '@react-three/viverse' library. This is the first step in attaching objects to character bones.

```javascript
import { CharacterModelBone } from '@react-three/viverse'
```

--------------------------------

### Configure Production App ID

Source: https://pmndrs.github.io/viverse/tutorials/publish-to-viverse

Sets the VIVERSE App ID for production environments by creating a `.env.production` file. This variable is used to provide the App ID to the VIVERSE component.

```bash
# .env.production
VITE_VIVERSE_APP_ID=your-app-id-here
```

--------------------------------

### Adding a Simple Character

Source: https://pmndrs.github.io/viverse/tutorials/simple-game

Imports and renders a `SimpleCharacter` component from `@react-three/viverse` along with environment and lighting. It also includes `BvhPhysicsBody` for physics interactions.

```javascript
import { Sky } from '@react-three/drei'
import { SimpleCharacter, BvhPhysicsBody, PrototypeBox } from '@react-three/viverse'
import { useRef } from 'react'
export function Scene() {
  return (
    <>{/* Environment */}<Sky />{/* Lighting */}<directionalLight
        intensity={1.2}
        position={[5, 10, 10]}
        castShadow
      /><ambientLight intensity={1} /><SimpleCharacter/>{/* Level Geometry */}<BvhPhysicsBody>{/* ... platforms remain the same ... */}</BvhPhysicsBody></>
  )
}
```

--------------------------------

### Wrap Scene with XR Components

Source: https://pmndrs.github.io/viverse/tutorials/augmented-and-virtual-reality

Wraps the scene content with `XR` and `XROrigin` components to establish the AR environment. `XROrigin` sets the coordinate system for AR tracking, and its scale and position are adjusted for the scene.

```typescript
import { Suspense } from 'react'
import { Canvas } from '@react-three/fiber'
import { Viverse } from '@react-three/viverse'
import { XR, XROrigin } from '@react-three/xr'
import { Scene } from './Scene'
import { Text } from 'troika-three-text' // Assuming Text is imported from troika-three-text

export function App() {
  return (
    <Viverse><Canvas
        style={{ width: '100%', flexGrow: 1 }}
        camera={{ fov: 90, position: [0, 2, 2] }}
        shadows
        gl={{ antialias: true, localClippingEnabled: true }}
      ><Suspense fallback={<Text>Loading...</Text>}><XR store={store}><XROrigin scale={10} position-y={-8} position-z={10} /><Scene /></XR></Suspense></Canvas></Viverse>
  )
}

```

--------------------------------

### SimpleCharacter Component

Source: https://pmndrs.github.io/viverse/getting-started/all-components-and-hooks

Creates a simple character controller with physics, supporting walking, running, and jumping actions, along with camera controls. It automatically uses the active VIVERSE avatar if authenticated. Configuration options for movement speeds are available.

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

--------------------------------

### Scene Component with Level Geometry

Source: https://pmndrs.github.io/viverse/tutorials/simple-game

Expands the Scene component to include the game level geometry using BvhPhysicsBody and PrototypeBox for platforms, with enhanced directional light shadow properties.

```javascript
import { Sky } from '@react-three/drei'
import { BvhPhysicsBody, PrototypeBox } from '@react-three/viverse'
export function Scene() {
  return (
    <>{/* Environment */}<Sky />{/* Lighting - expanded with shadow settings */}<directionalLight
        intensity={1.2}
        position={[5, 10, 10]}
        castShadow
      /><ambientLight intensity={1} /><BvhPhysicsBody><PrototypeBox 
          color="#ffffff" 
          scale={[10, 0.5, 10]} 
          position={[0, -2, 0]} 
        />{/* Platforms */}<PrototypeBox 
          color="#cccccc" 
          scale={[2, 1, 3]} 
          position={[4, 0, 0]} 
        /><PrototypeBox 
          color="#ffccff" 
          scale={[3, 1, 3]} 
          position={[3, 1.5, -1]} 
        /><PrototypeBox 
          color="#ccffff" 
          scale={[2, 0.5, 3]} 
          position={[2, 2.5, -3]} 
        /><PrototypeBox 
          color="#ffccff" 
          scale={[2, 1, 3]} 
          position={[-3, 0, -2]} 
        /><PrototypeBox 
          color="#ccffff" 
          scale={[1, 1, 4]} 
          position={[0, -1, 0]} 
        /><PrototypeBox 
          color="#ffffcc" 
          scale={[4, 1, 1]} 
          position={[0, 3.5, 0]} 
        /></BvhPhysicsBody></>)
}
```

--------------------------------

### Integrating PlayerTag into SimpleCharacter

Source: https://pmndrs.github.io/viverse/tutorials/access-avatar-and-profile

Shows the final step of rendering the `PlayerTag` component as a child of the `SimpleCharacter` component to display the player tag in the game scene.

```jsx
<SimpleCharacter><PlayerTag /></SimpleCharacter>

```

--------------------------------

### SimpleCharacter Component Options

Source: https://pmndrs.github.io/viverse/getting-started/all-components-and-hooks

Configuration options for the SimpleCharacter component, including model loading, physics properties, input handling, and movement parameters. The component also supports default group props like position, rotation, and scale.

```APIDOC
SimpleCharacter Component Options:

useViverseAvatar: boolean
  - Allows to configure whether the users vrm avatar should be displayed as the character model.
  - Default: `true`

model: string | boolean | object
  - URL to VRM or GLTF model file.
  - type: "gltf" | "vrm" - the type of file to be loaded.
  - castShadow: boolean - Enable shadow casting (default: `true`).
  - receiveShadow: boolean - Enable shadow receiving (default: `true`).
  - boneRotationOffset: Quaternion | undefined - Allows to apply an rotation offset when placing objects as children of the character's bones (default: `undefined`).
  - Set to `false` to disable model loading.
  - Set to `true` or omit to use default robot model.

physics:
  - capsuleRadius: number - Character collision capsule radius (default: `0.4`).
  - capsuleHeight: number - Character collision capsule height (default: `1.7`).
  - gravity: number - Gravity acceleration in m/s² (default: `-20`).
  - linearDamping: number - Air resistance coefficient (default: `0.1`).
  - maxGroundSlope: number - Max slope for a collider to be detected as a walkable ground (default: `1` which equals to 45°).

movement:
  - walk: object | boolean
    - Enable walking (default: `true`).
    - speed: Movement speed in units per second (default: `2.5`).
    - Set to `false` to disable walking.
  - run: object | boolean
    - Enable running (default: `true`).
    - speed: Running speed in units per second (default: `4.5`).
    - Set to `false` to disable running.
  - jump: object | boolean
    - Enable jumping (default: `true`).
    - delay: Time before jump starts in seconds (default: `0.15`).
    - bufferTime: Jump input buffer time in seconds (default: `0.1`).
    - speed: Jump velocity in units per second (default: `8`).
    - Set to `false` to disable jumping.

input: Array<Input> | custom InputSystem
  - Default: `[LocomotionKeyboardInput, PointerCaptureInput]`.
  - Configure input handling with custom input classes.
  - Available Input Classes:
    - `LocomotionKeyboardInput`: WASD movement, Space for jump, Shift for run.
    - `PointerCaptureInput`: Mouse look with pointer capture (requires manual `setPointerCapture`).
    - `PointerLockInput`: Mouse look with pointer lock (requires manual `requestPointerLock`).
```

--------------------------------

### Adding a Sky Background with Three.js

Source: https://pmndrs.github.io/viverse/without-react/introduction

Integrates a realistic sky background into the Three.js scene using the Sky class. It configures the sun's position to create a dynamic sky effect.

```javascript
import { MathUtils, Vector3 } from 'three'
import { Sky } from 'three/examples/jsm/Addons.js'
// Add after scene creation
const sky = new Sky()
sky.scale.setScalar(450000)
const phi = MathUtils.degToRad(40)
const theta = MathUtils.degToRad(30)
const sunPosition = new Vector3().setFromSphericalCoords(1, phi, theta)
sky.material.uniforms.sunPosition.value = sunPosition
scene.add(sky)
```

--------------------------------

### Implement Snap Rotation for VR Comfort

Source: https://pmndrs.github.io/viverse/tutorials/augmented-and-virtual-reality

Replaces the standard XROrigin with a custom SnapRotateXROrigin component to enable snap rotation using the right thumbstick for improved VR comfort.

```typescript
import { useXRInputSourceState } from '@react-three/xr'
import { XROrigin } from '@react-three/xr'
import { useRef } from 'react'
import { Group } from 'three'
import { useFrame } from '@react-three/fiber'

function SnapRotateXROrigin() {
  const ref = useRef<Group>(null)
  const rightController = useXRInputSourceState('controller', 'right')
  const prev = useRef(0)
  useFrame(() => {
    if (ref.current == null) return
    const current = Math.round(rightController?.gamepad?.['xr-standard-thumbstick']?.xAxis ?? 0)
    if (current < 0 && prev.current >= 0) {
      // Rotate left
      ref.current.rotation.y += Math.PI / 2
    }
    if (current > 0 && prev.current <= 0) {
      // Rotate right
      ref.current.rotation.y -= Math.PI / 2
    }
    prev.current = current
  })
  return <XROrigin ref={ref} />
}

// Usage:
// <SimpleCharacter ... ><SnapRotateXROrigin /></SimpleCharacter>
```

--------------------------------

### Add Physics and Character

Source: https://pmndrs.github.io/viverse/without-react/introduction

Integrates physics and a controllable character into the scene. Initializes BvhPhysicsWorld, adds the ground to the physics world, and creates a SimpleCharacter instance. The character is updated in the render loop, and logic is included to respawn the player if they fall below a certain y-coordinate.

```javascript
import { BvhPhysicsWorld, SimpleCharacter } from '@pmndrs/viverse'
// Add after loading the map
const world = new BvhPhysicsWorld()
world.addBody(ground.scene, false)
const character = new SimpleCharacter(camera, world, canvas, { 
  model: { url: undefined } // We'll add avatar URL later
})
scene.add(character)
// Update character in render loop
renderer.setAnimationLoop(() => {
  const delta = clock.getDelta()
  character.update(delta)
  renderer.render(scene, camera)
  // Respawn player when they fall down
  if (character.position.y < -10) {
    character.position.set(0, 0, 0)
  }
})
```

--------------------------------

### Fetching Viverse Profile Data

Source: https://pmndrs.github.io/viverse/tutorials/access-avatar-and-profile

Demonstrates how to use the `useViverseProfile()` hook to retrieve the current user's profile data, including their name and avatar image URL. It also includes a fallback for when the user is not logged in.

```javascript
const profile = useViverseProfile() ?? {
  name: 'Anonymous',
  activeAvatar: { headIconUrl: 'https://picsum.photos/200' },
}

```

--------------------------------

### Use XR Controller Input

Source: https://pmndrs.github.io/viverse/tutorials/augmented-and-virtual-reality

Replaces traditional keyboard/mouse input with XR controller input using the `useXRControllerInput` hook. This enables natural interaction within the AR/VR environment.

```typescript
import { useXRControllerInput } from '@react-three/viverse'
import { SimpleCharacter } from '@react-three/viverse' // Assuming SimpleCharacter is imported
import { PlayerTag } from './PlayerTag' // Assuming PlayerTag is imported

export function Scene() {
  const input = useXRControllerInput()
  return (
    <><SimpleCharacter 
        input={[input]} 
        cameraBehavior={false} 
        ref={characterRef}
      ><PlayerTag /></SimpleCharacter>{/* ... rest of scene */}</>
  )
}

```

--------------------------------

### Configure VR Session Type

Source: https://pmndrs.github.io/viverse/tutorials/augmented-and-virtual-reality

Configures the XR store to offer an 'immersive-vr' session, which presents the user with a native VR enter button.

```javascript
const store = createXRStore({
  offerSession: 'immersive-vr',
})
```

--------------------------------

### Viverse Hooks

Source: https://pmndrs.github.io/viverse/getting-started/all-components-and-hooks

Provides access to the Viverse client, authentication state, avatar operations, and login/logout functionality. Hooks like `useViverseProfile` and `useViverseActiveAvatar` utilize Suspense for data fetching. Avatar-related hooks return undefined if the user is not authenticated.

```APIDOC
useViverseClient(): Client
  - Returns the VIVERSE client instance for making API calls.
  - Throws an error if not within a `<Viverse>` provider.

useViverseAuth(): Auth object
  - Returns the current authentication state.
  - Auth object contains access tokens.
  - Returns `undefined` if the user is not authenticated.

useViverseAvatarClient(): AvatarClient | undefined
  - Returns the avatar client for avatar-related operations.
  - Returns `undefined` if the user is not authenticated.

useViverseLogin(): Function
  - Returns a function to initiate the VIVERSE login flow.

useViverseLogout(): Function
  - Returns a function to initiate the VIVERSE logout flow.

useViverseProfile(): Profile object | undefined
  - Fetches the user's profile (name, avatar info) using Suspense.
  - Profile object includes `name`, `activeAvatar`, etc.
  - Returns `undefined` if the user is not authenticated.

useViverseActiveAvatar(): Avatar object | undefined
  - Fetches the user's currently selected avatar using Suspense.
  - Avatar object includes `vrmUrl`, `headIconUrl`, etc.
  - Returns `undefined` if the user is not authenticated.

useViverseAvatarList(): Array<Avatar object> | undefined
  - Fetches the user's personal avatar collection using Suspense.
  - Returns `undefined` if the user is not authenticated.

useViversePublicAvatarList(): Array<Avatar object> | undefined
  - Fetches publicly available avatars using Suspense.
  - Returns `undefined` if the user is not authenticated.

useViversePublicAvatarByID(id): Avatar object | undefined
  - Fetches a specific public avatar by ID using Suspense.
  - Returns `undefined` if the user is not authenticated.
```

--------------------------------

### Using Custom VRM Models with SimpleCharacter

Source: https://pmndrs.github.io/viverse/tutorials/custom-models-and-animations

Demonstrates how to replace the default robot avatar in the SimpleCharacter component with a custom VRM model by providing a URL. It includes properties for shadow casting and receiving.

```jsx
import { SimpleCharacter } from '@react-three/viverse'
export function MyCharacter() {
  return (
    <SimpleCharacter
      model={{
        url: '/path/to/your-model.vrm',
        castShadow: true,
        receiveShadow: true
      }}
    />
  )
}
```
Tokens:
Raw