three.js Login & Auth minimal example

Learn how to clone a three.js example project then import the VIVERSE SDK to add login and authentication features

This tutorial demonstrates how to extend a basic three.js example project with VIVERSE SDK functionality, creating an engaging collectible driving game with Rapier physics.

In this initial tutorial, we'll add the Authentication SDK, as well as several gameplay features that we'll continue to build on in future steps with the Storage and Leaderboard SDK examples.

Pre-requisite #1: Create a World and App ID in VIVERSE Studio

All SDK usage requires an App ID tied to a specific VIVERSE World, which can be created via VIVERSE Studio. This process is described in detail in our documentation on VIVERSE Studio — but simply create a new app and copy its App ID to get started.

NOTE: VIVERSE SDKs cannot be used with projects published via the PlayCanvas Create SDK extension, which do not have App IDs.

Pre-requisite #2: Clone the three.js Vehicle Controller Example

Start by copying the official three.js Rapier vehicle controller sample as your foundation. This example provides a complete three.js scene setup with Rapier physics tied to a functional vehicle controller with WASD controls — drive too fast before turning and you can fully flip over, providing a fun challenge driven by Rapier's realistic physics simulation.

Step 1: Add VIVERSE SDK Integration

Building on the base three.js vehicle controller example, we'll now add VIVERSE authentication and gameplay enhancements. Simply copy the CDN URL into the <head> of your HTML document.

<!-- Add to <head> section: -->
<script src="https://www.viverse.com/static-assets/viverse-sdk/index.umd.cjs"></script>

Step 2: Implement VIVERSE Authentication

Client Initialization

This process is described generically in our documentation, Login & Authentication for the SDK, but here is how it would apply to a modular three.js script:

// Initialize VIVERSE client
function initializeViverseClient() {
  globalThis.viverseClient = new globalThis.viverse.client({
    clientId: "your-app-id", // Replace with your actual App ID from VIVERSE Studio
    domain: "account.htcvive.com",
    cookieDomain: window.location.hostname,
  });
}

Authentication Check

Once the viverseClient is instantiated, use its checkAuth() function to determine whether the user is logged in. It will return undefined if they are not logged-in, or credentials if they are.

// Check authentication status
async function checkAuthentication() {
  try {
    const result = await globalThis.viverseClient.checkAuth();

    if (result) {
      isAuthenticated = true;
      userInfo = result;
      updateAuthUI(true, result.account_id);
      console.log("User authenticated:", result);
    } else {
      isAuthenticated = false;
      userInfo = null;
      updateAuthUI(false);
      console.log("User not authenticated");
    }
  } catch (error) {
    console.error("Authentication check failed:", error);
    isAuthenticated = false;
    updateAuthUI(false);
  }
}

Now that we're checking auth status, let's add some UI to our demo scene to prompt the login process if they are logged out.

function createAuthUI() {
  // Create authentication status element
  const authElement = document.createElement("div");
  authElement.id = "auth-status";
  authElement.innerHTML = "Checking authentication...";
  document.body.appendChild(authElement);

  // Create login button
  const loginButton = document.createElement("button");
  loginButton.id = "login-button";
  loginButton.innerHTML = "Login with VIVERSE";
  loginButton.addEventListener("click", loginWithViverse);
  document.body.appendChild(loginButton);
}

UI State Management

// Update authentication UI
function updateAuthUI(authenticated, userId = null) {
  const authElement = document.getElementById("auth-status");
  const loginButton = document.getElementById("login-button");

  if (authenticated) {
    authElement.innerHTML = `Logged in as: ${userId}`;
    authElement.className = "authenticated";
    loginButton.style.display = "none";
  } else {
    authElement.innerHTML = "Not logged in";
    authElement.className = "unauthenticated";
    loginButton.style.display = "block";
  }
}

Once uploaded and running on VIVERSE, all this authentication functionality should now be working! But what can we do with a logged in VIVERSE user? To find out, we have to add some gameplay features and a scoring system.

Step 3: Enhance the OrbitControls Camera System

The base vehicle controller example uses a simple static camera setup which points at the car but does not follow it closely. We'll upgrade this with smart car following behavior for a more engaging experience that will still allow the user to view the vehicle and scene from a variety of angles.

Default Settings + Events for Camera Following

// Initialize OrbitControls for zoom and rotation
controls = new OrbitControls(camera, renderer.domElement);
controls.target = new THREE.Vector3(0, 2, 0);
controls.enablePan = false; // Disable panning, keep zoom and rotate
controls.minDistance = 3; // Minimum zoom distance
controls.maxDistance = 30; // Maximum zoom distance
controls.maxPolarAngle = Math.PI * 0.8; // Prevent camera from going too low
controls.enableDamping = true; // Enable damping for smoother feel
controls.dampingFactor = 0.1;

// Track when user interaction ends to update follow offset
window.userControlling = false;

controls.addEventListener("start", () => {
  window.userControlling = true;
});

controls.addEventListener("end", () => {
  window.userControlling = false;
  // Update the follow offset when user stops controlling
  updateCameraOffset();
});

Camera Updates

function updateCamera() {
  if (!car || !controls) return;

  // Get car's world position and rotation
  const carPosition = car.position.clone();
  const carQuaternion = car.quaternion.clone();

  // Create a level quaternion (only Y rotation, no roll/pitch)
  const carEuler = new THREE.Euler().setFromQuaternion(carQuaternion, "YXZ");
  const levelQuaternion = new THREE.Quaternion().setFromEuler(
    new THREE.Euler(0, carEuler.y, 0, "YXZ")
  );

  if (!window.userControlling) {
    // When user is not controlling, use the stored offset for following
    const desiredCameraPosition = cameraOffset.clone();
    desiredCameraPosition.applyQuaternion(levelQuaternion); // Use level quaternion
    desiredCameraPosition.add(carPosition);

    // Ensure camera stays above ground (minimum height)
    const minCameraHeight = 1.0; // Minimum height above ground
    if (desiredCameraPosition.y < minCameraHeight) {
      desiredCameraPosition.y = minCameraHeight;
    }

    // Smoothly move camera and target to follow the car
    const lerpFactor = 0.05;
    controls.target.lerp(carPosition, lerpFactor);
    camera.position.lerp(desiredCameraPosition, lerpFactor);
  } else {
    // When user is controlling, just update target to follow car position
    const targetLerpFactor = 0.05;
    controls.target.lerp(carPosition, targetLerpFactor);

    // Also ensure user-controlled camera doesn't go below ground
    if (camera.position.y < 1.0) {
      camera.position.y = 1.0;
    }
  }

  // Update controls
  controls.update();
}

Step 5: Add Game Mechanics - Collectibles System

Now we'll add a scoring system with collectible items to transform the basic driving demo into an engaging game. This will also give us a score to track with the Leaderboard and Storage SDKs in future tutorials.

Collectible Creation

function createCollectible(x, y, z) {
  const geometry = new THREE.OctahedronGeometry(0.5);
  const material = new THREE.MeshStandardMaterial({
    color: 0xffd700,
    emissive: 0x444400,
    metalness: 0.3,
    roughness: 0.1,
  });
  const mesh = new THREE.Mesh(geometry, material);

  mesh.position.set(x, y, z);
  mesh.castShadow = true;
  mesh.receiveShadow = true;

  // Add physics body for collision detection
  physics.addMesh(mesh, 0); // Mass 0 for static/kinematic body
  mesh.userData.isCollectible = true;
  mesh.userData.collected = false;
  mesh.userData.originalY = y;
  mesh.userData.time = Math.random() * Math.PI * 2; // Random phase for animation

  scene.add(mesh);
  collectibles.push(mesh);

  return mesh;
}

Collectible Spawning System

function createCollectibles() {
  const numCollectibles = 15; // Number of collectibles to spawn
  const groundSize = 40; // Size of the ground area (matches the ground geometry)
  const minDistance = 3; // Minimum distance between collectibles
  const carStartArea = 5; // Radius around car start position to avoid

  const spawnedPositions = [];

  for (let i = 0; i < numCollectibles; i++) {
    let position;
    let attempts = 0;
    const maxAttempts = 50;

    do {
      // Generate random position within ground bounds
      position = {
        x: (Math.random() - 0.5) * (groundSize - 4), // Leave some margin from edges
        y: 1,
        z: (Math.random() - 0.5) * (groundSize - 4) - 20, // Offset by ground position
      };
      attempts++;
    } while (
      attempts < maxAttempts &&
      (isPositionTooClose(position, spawnedPositions, minDistance) ||
        isPositionTooClose(position, [{ x: 0, z: 0 }], carStartArea))
    );

    // If we found a valid position, spawn the collectible
    if (attempts < maxAttempts) {
      createCollectible(position.x, position.y, position.z);
      spawnedPositions.push(position);
    }
  }

  updateScoreUI();
}

function isPositionTooClose(newPos, existingPositions, minDistance) {
  return existingPositions.some((pos) => {
    const dx = newPos.x - pos.x;
    const dz = newPos.z - pos.z;
    return Math.sqrt(dx * dx + dz * dz) < minDistance;
  });
}

Collision Detection and Scoring

For this demo, a simple distance-based collision check should suffice.

function checkCollisions() {
  if (!car || !chassis) return;

  const carPosition = car.position;
  const collectDistance = 1.5; // Distance threshold for collection

  const collectiblesToCheck = [...collectibles];

  collectiblesToCheck.forEach((collectible) => {
    if (!collectible || collectible.userData.collected || !collectible.visible)
      return;

    const distance = carPosition.distanceTo(collectible.position);
    if (distance < collectDistance) {
      collectPickup(collectible);
    }
  });
}

function collectPickup(collectible) {
  if (collectible.userData.collected) return;

  collectible.userData.collected = true;
  score += 100; // Add 100 points per collectible

  // Immediately hide the collectible
  collectible.visible = false;

  // Remove from physics world immediately
  if (collectible.userData.physics) {
    physics.removeBody(collectible.userData.physics.body);
    collectible.userData.physics = null; // Clear the reference
  }

  // Remove from collectibles array immediately
  const index = collectibles.indexOf(collectible);
  if (index > -1) {
    collectibles.splice(index, 1);
  }

  // Remove from scene immediately
  scene.remove(collectible);

  // Clean up geometry and material
  if (collectible.geometry) {
    collectible.geometry.dispose();
  }
  if (collectible.material) {
    collectible.material.dispose();
  }

  updateScoreUI();

  // Spawn a new collectible to replace the collected one
  spawnNewCollectible();
}

function spawnNewCollectible() {
  const groundSize = 40;
  const minDistance = 3;
  const carStartArea = 5;
  const maxAttempts = 50;

  let position;
  let attempts = 0;

  do {
    // Generate random position within ground bounds
    position = {
      x: (Math.random() - 0.5) * (groundSize - 4),
      y: 1,
      z: (Math.random() - 0.5) * (groundSize - 4) - 20,
    };
    attempts++;
  } while (
    attempts < maxAttempts &&
    (isPositionTooClose(
      position,
      collectibles.map((c) => c.position),
      minDistance
    ) ||
      isPositionTooClose(position, [{ x: 0, z: 0 }], carStartArea))
  );

  // If we found a valid position, spawn the collectible
  if (attempts < maxAttempts) {
    createCollectible(position.x, position.y, position.z);
  }
}

Step 6: Integration and Initialization

Building on the existing three.js vehicle controller, add these integrations:

// 1. Add VIVERSE authentication variables at the top
let isAuthenticated = false;
let userInfo = null;

// 2. Add score tracking variables
let score = 0;
let collectibles = [];

// 3. In your existing init() function, add these calls:
async function init() {
  // ... existing three.js setup from base example ...

  // NEW: Create authentication UI elements
  createAuthUI();

  // NEW: Initialize VIVERSE authentication after physics
  await initPhysics(); // existing
  initializeViverseClient(); // NEW
  checkAuthentication(); // NEW

  // NEW: Set up enhanced camera controls (replaces basic camera)
  setupEnhancedCamera();

  // ... rest of existing initialization ...
}

function animate() {
  if (vehicleController) {
    updateCarControl();
    vehicleController.updateVehicle(1 / 60);
    updateWheels(); // Update wheel positions and rotations
  }

  // Update camera to follow car
  updateCamera();

  // Update collectibles animations and check collisions
  animateCollectibles();
  checkCollisions();

  if (physicsHelper) physicsHelper.update();

  renderer.render(scene, camera);
}

Step 6: Build and Publish to VIVERSE

That's it! That should fulfil our minimal requirements create a small mini game we can publish to VIVERSE to then run login and authentication check features. Now we just need to build and publish.

Whatever your build process, simply zip the final build folder to prepare to upload. In the demo project we're using Vite.js, so just run npm run build to engage that. This will create all necessary static build files in the /dist folder of your project.

Once the build .zip is ready, navigate to VIVERSE Studio's Upload section, click "Manage Content" next to the app you created earlier, and use the "Upload Content" section to select the .zip.

From there, you can preview your build, or submit it for content review and approval. This process is explored in great detail in the VIVERSE Studio section of our docs if you have further questions.

Final Build

That's it! The build is ready. Here are the relevant links:

three.js example project source code:

38KB

vv-auth-three.zip

hashtagPre-requisite #1: Create a World and App ID in VIVERSE Studio

hashtagPre-requisite #2: Clone the three.js Vehicle Controller Example

hashtagStep 1: Add VIVERSE SDK Integration

hashtagStep 2: Implement VIVERSE Authentication

hashtagClient Initialization

hashtagAuthentication Check

hashtagLogin Flow

hashtagUI State Management

hashtagStep 3: Enhance the OrbitControls Camera System

hashtagDefault Settings + Events for Camera Following

hashtagCamera Updates

hashtagStep 5: Add Game Mechanics - Collectibles System

hashtagCollectible Creation

hashtagCollectible Spawning System

hashtagCollision Detection and Scoring

hashtagStep 6: Integration and Initialization

hashtagStep 6: Build and Publish to VIVERSE

hashtagFinal Build