> ## Documentation Index > Fetch the complete documentation index at: https://hyperscape-ai-mintlify-docs-update.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://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/`: ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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:** ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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: ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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/`: ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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 ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}} # 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 ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}} bun run dev:client # Vite dev server with HMR ``` Opens at [http://localhost:3333](http://localhost:3333) ### Production Build ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}} cd packages/client bun run build # Build to dist/ bun run preview # Preview production build ``` ## Mobile Builds ### iOS Requires macOS with Xcode installed. ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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 ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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 ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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 |