client

Web client with Vite, React, and 3D rendering

Overview

The @hyperscape/client package is the web game client:

• Vite for fast builds with HMR
• React 19 UI framework
• Three.js WebGPU rendering (WebGPU required - no WebGL fallback)
• Capacitor for iOS/Android mobile builds
• Privy authentication
• Farcaster miniapp SDK

WebGPU Required: The client requires WebGPU support. All shaders use TSL (Three Shading Language) which only works with WebGPU. There is no WebGL fallback. Requires Chrome 113+, Edge 113+, or Safari 18+ (macOS 15+).

Breaking Change (Feb 2026): WebGL fallback was completely removed. Users on browsers without WebGPU will see an error screen with upgrade instructions. Check browser support at webgpureport.org.

Package Location

packages/client/
├── src/
│   ├── auth/           # Privy authentication
│   ├── components/     # React UI components
│   ├── constants/      # Client constants
│   ├── game/           # Game loop and logic
│   ├── hooks/          # React hooks
│   ├── lib/            # Networking, utilities
│   ├── public/         # Static assets
│   ├── screens/        # UI screens
│   ├── types/          # TypeScript types
│   ├── utils/          # Helper functions
│   ├── index.tsx       # React entry point (main game)
│   ├── index.html      # HTML template (main game)
│   ├── stream.tsx      # React entry point (streaming mode) - NEW March 2026
│   ├── stream.html     # HTML template (streaming mode) - NEW March 2026
│   └── index.css       # Global styles (Tailwind)
├── ios/                # iOS native project (Capacitor)
├── android/            # Android native project (Capacitor)
├── capacitor.config.ts # Mobile configuration
├── vite.config.ts      # Vite configuration (multi-page build)
└── .env.example        # Environment template

Screens

Located in src/screens/:

// From packages/client/src/screens/
LoginScreen.tsx           // Privy authentication
LoadingScreen.tsx         // Asset loading
UsernameSelectionScreen.tsx  // First-time username
CharacterSelectScreen.tsx // Choose character
CharacterEditorScreen.tsx // Create/edit character with VRM preview
DashboardScreen.tsx       // Game hub / lobby
GameClient.tsx            // Main 3D gameplay

Screen	Purpose
LoginScreen	Privy authentication
UsernameSelectionScreen	First-time username entry
CharacterSelectScreen	Choose existing character
CharacterEditorScreen	Create/edit character (VRM preview)
DashboardScreen	Game hub and lobby
GameClient	Main 3D gameplay
LoadingScreen	Asset loading state
StreamingMode	Optimized streaming capture (minimal UI overhead) - NEW March 2026

Streaming Entry Points (March 2026)

The client includes dedicated entry points for streaming capture (commit 71dcba8):

Entry Points:

• src/index.html / src/index.tsx - Main game (full UI)
• src/stream.html / src/stream.tsx - Streaming mode (minimal UI)

Viewport Mode Detection:

import { isStreamPageRoute, isEmbeddedSpectatorViewport, isStreamingLikeViewport } from '@hyperscape/shared';

// Detect streaming capture mode
if (isStreamPageRoute(window)) {
  // Running in streaming mode (/stream.html or ?page=stream)
}

// Detect embedded spectator
if (isEmbeddedSpectatorViewport(window)) {
  // Running as embedded spectator (?embedded=true&mode=spectator)
}

// Detect any streaming-like viewport
if (isStreamingLikeViewport(window)) {
  // Either streaming or embedded spectator
}

Vite Multi-Page Build:

The Vite configuration builds separate bundles for game and streaming:

// From vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        main: resolve(__dirname, 'src/index.html'),
        stream: resolve(__dirname, 'src/stream.html')
      }
    }
  }
});

Benefits:

• Optimized streaming capture with minimal UI overhead
• Separate bundles reduce streaming page load time
• Automatic viewport mode detection for conditional rendering
• Clear separation between game and streaming entry points

UI Components

Located in src/components/:

// From packages/client/src/components/
CharacterPreview.tsx      // VRM character preview
DraggableWindow.tsx       // Draggable UI windows
EmbeddedGameClient.tsx    // Embedded game in dashboard
GameWindow.tsx            // Main game container
MinimapCompass.tsx        // Minimap with compass
MinimapStaminaBar.tsx     // Stamina display
MenuButton.tsx            // Menu buttons
Portal.tsx                // React portal for overlays
Fields.tsx                // Form field components
Icons.tsx                 // Icon components

// Subfolders
character/                // Character-related components
dashboard/                // Dashboard components

HUD Components

• Health/Constitution display
• Combat status indicators
• Skills panel with XP progress
• 28-slot inventory grid
• Equipment slots display
• Bank interface (unlimited storage)
• Chat window
• Minimap with compass

Game Components

• Three.js 3D renderer
• Camera controller (third-person, click-to-move)
• Input handler (WASD movement, click actions)
• Entity renderers (players, mobs, items)
• VRM avatar display with emotes

Environment Variables

# Required
PUBLIC_PRIVY_APP_ID=your-privy-app-id

# Server URLs (production)
PUBLIC_API_URL=https://api.hyperscape.lol
PUBLIC_WS_URL=wss://api.hyperscape.lol
PUBLIC_CDN_URL=https://cdn.hyperscape.lol

# Farcaster (optional)
PUBLIC_ENABLE_FARCASTER=true
PUBLIC_APP_URL=https://hyperscape.lol

Running

Development

bun run dev:client    # Vite dev server with HMR

Opens at http://localhost:3333

Production Build

cd packages/client
bun run build         # Build to dist/
bun run preview       # Preview production build

Mobile Builds

iOS

Requires macOS with Xcode installed.

bun run ios           # Build and open Xcode
bun run ios:dev       # Sync and open (no rebuild)
bun run ios:build     # Production build

Android

Requires Android Studio installed.

bun run android       # Build and open Android Studio
bun run android:dev   # Sync and open (no rebuild)
bun run android:build # Production build

Capacitor Sync

bun run cap:sync          # Sync both platforms
bun run cap:sync:ios      # iOS only
bun run cap:sync:android  # Android only

Dependencies

Package	Purpose
react	UI framework (v19)
react-dom	React DOM renderer
vite	Build tool
three	3D rendering
@capacitor/core	Mobile builds
@hyperscape/shared	Core engine
@privy-io/react-auth	Authentication
@farcaster/miniapp-sdk	Farcaster integration
styled-components	CSS-in-JS
tailwindcss	Utility CSS
livekit-client	Voice chat

Deployment

Cloudflare Pages

bun run deploy        # Deploy to staging
bun run deploy:prod   # Deploy to production

Key Files

File	Purpose
src/index.tsx	React entry point
src/game/	Game loop and logic
src/screens/	UI screens
vite.config.ts	Vite configuration
capacitor.config.ts	Mobile configuration
wrangler.toml	Cloudflare Pages config