Viewport Mode Detection API

The clientViewportMode utility provides runtime detection of different viewport modes for conditional rendering and behavior.

Overview

Hyperscape supports three viewport modes:

Normal Mode - Standard gameplay (default)
Stream Mode - Optimized for streaming capture (/stream.html or ?page=stream)
Embedded Spectator Mode - Embedded spectator view (?embedded=true&mode=spectator)

API Reference

`isStreamPageRoute(win?: Window): boolean`

Detects if the current page is running in streaming capture mode. Returns: true if:

URL pathname ends with /stream.html
URL query parameter page=stream

Example:

import { isStreamPageRoute } from '@hyperscape/shared/runtime/clientViewportMode';

if (isStreamPageRoute()) {
  // Hide UI elements for clean streaming capture
  hidePlayerUI();
}

`isEmbeddedSpectatorViewport(win?: Window): boolean`

Detects if running as an embedded spectator (e.g., in betting app iframe). Returns: true if:

URL query parameters: embedded=true AND mode=spectator
OR window config: __HYPERSCAPE_EMBEDDED__=true AND __HYPERSCAPE_CONFIG__.mode="spectator"

Example:

import { isEmbeddedSpectatorViewport } from '@hyperscape/shared/runtime/clientViewportMode';

if (isEmbeddedSpectatorViewport()) {
  // Disable player controls in spectator mode
  disablePlayerInput();
}

`isStreamingLikeViewport(win?: Window): boolean`

Detects any streaming-like viewport (stream OR embedded spectator). Returns: true if either isStreamPageRoute() or isEmbeddedSpectatorViewport() returns true. Example:

import { isStreamingLikeViewport } from '@hyperscape/shared/runtime/clientViewportMode';

if (isStreamingLikeViewport()) {
  // Apply streaming-specific optimizations
  reduceUIOverhead();
  disableDebugOverlays();
}

Usage Patterns

Conditional UI Rendering

import { isStreamPageRoute } from '@hyperscape/shared/runtime/clientViewportMode';

function GameUI() {
  const isStreaming = isStreamPageRoute();
  
  return (
    <>
      {!isStreaming && <PlayerInventory />}
      {!isStreaming && <ChatPanel />}
      <GameViewport />
    </>
  );
}

Streaming Optimizations

import { isStreamingLikeViewport } from '@hyperscape/shared/runtime/clientViewportMode';

function initializeRenderer() {
  const renderer = new WebGPURenderer();
  
  if (isStreamingLikeViewport()) {
    // Optimize for streaming capture
    renderer.setPixelRatio(1); // Fixed 1:1 for consistent encoding
    renderer.shadowMap.enabled = true; // High quality shadows for viewers
  } else {
    // Optimize for player experience
    renderer.setPixelRatio(window.devicePixelRatio);
    renderer.shadowMap.enabled = userSettings.shadows;
  }
  
  return renderer;
}

Spectator Controls

import { isEmbeddedSpectatorViewport } from '@hyperscape/shared/runtime/clientViewportMode';

function CameraController() {
  const isSpectator = isEmbeddedSpectatorViewport();
  
  useEffect(() => {
    if (isSpectator) {
      // Lock camera to arena view
      camera.position.set(0, 50, 50);
      camera.lookAt(0, 0, 0);
      controls.enabled = false;
    }
  }, [isSpectator]);
}

URL Patterns

Stream Mode

http://localhost:3333/stream.html
http://localhost:3333/?page=stream
https://hyperscape.gg/stream.html
https://hyperscape.gg/?page=stream

Embedded Spectator Mode

http://localhost:3333/?embedded=true&mode=spectator
https://hyperscape.gg/?embedded=true&mode=spectator

Normal Mode

http://localhost:3333/
http://localhost:3333/index.html
https://hyperscape.gg/

Vite Multi-Page Build

The client now builds separate entry points for different modes: vite.config.ts:

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

Output:

dist/index.html - Main game bundle
dist/stream.html - Streaming capture bundle (minimal UI)

Integration with Streaming Pipeline

The streaming capture pipeline uses these URLs: ecosystem.config.cjs:

env: {
  GAME_URL: "http://localhost:3333/?page=stream",
  GAME_FALLBACK_URLS: "http://localhost:3333/?page=stream,http://localhost:3333/?embedded=true&mode=spectator,http://localhost:3333/",
}

Fallback Order:

Stream page (?page=stream) - Preferred for clean capture
Embedded spectator (?embedded=true&mode=spectator) - Fallback if stream page fails
Normal game (/) - Last resort

Testing

import { describe, it, expect } from 'vitest';
import { isStreamPageRoute, isEmbeddedSpectatorViewport, isStreamingLikeViewport } from '@hyperscape/shared/runtime/clientViewportMode';

describe('Viewport Mode Detection', () => {
  it('detects stream page route', () => {
    const mockWindow = {
      location: { pathname: '/stream.html', search: '' }
    } as Window;
    
    expect(isStreamPageRoute(mockWindow)).toBe(true);
  });
  
  it('detects embedded spectator', () => {
    const mockWindow = {
      location: { pathname: '/', search: '?embedded=true&mode=spectator' }
    } as Window;
    
    expect(isEmbeddedSpectatorViewport(mockWindow)).toBe(true);
  });
  
  it('detects streaming-like viewport', () => {
    const mockWindow = {
      location: { pathname: '/stream.html', search: '' }
    } as Window;
    
    expect(isStreamingLikeViewport(mockWindow)).toBe(true);
  });
});

Migration Guide

Before (Manual URL Parsing)

// Old approach - manual URL parsing
const urlParams = new URLSearchParams(window.location.search);
const isStreaming = urlParams.get('page') === 'stream';

After (Utility Functions)

// New approach - use utility functions
import { isStreamPageRoute } from '@hyperscape/shared/runtime/clientViewportMode';

const isStreaming = isStreamPageRoute();

packages/shared/src/runtime/clientViewportMode.ts - Core implementation
packages/client/src/stream.html - Streaming entry point
packages/client/src/stream.tsx - Streaming React entry
ecosystem.config.cjs - PM2 streaming configuration
packages/client/vite.config.ts - Multi-page build configuration

Configuration

Operations

Viewport mode detection

Viewport Mode Detection API

Overview

API Reference

`isStreamPageRoute(win?: Window): boolean`

`isEmbeddedSpectatorViewport(win?: Window): boolean`

`isStreamingLikeViewport(win?: Window): boolean`

Usage Patterns

Conditional UI Rendering

Streaming Optimizations

Spectator Controls

URL Patterns

Stream Mode

Embedded Spectator Mode

Normal Mode

Vite Multi-Page Build

Integration with Streaming Pipeline

Testing

Migration Guide

Before (Manual URL Parsing)

After (Utility Functions)

​Viewport Mode Detection API

​Overview

​API Reference

​isStreamPageRoute(win?: Window): boolean

​isEmbeddedSpectatorViewport(win?: Window): boolean

​isStreamingLikeViewport(win?: Window): boolean

​Usage Patterns

​Conditional UI Rendering

​Streaming Optimizations

​Spectator Controls

​URL Patterns

​Stream Mode

​Embedded Spectator Mode

​Normal Mode

​Vite Multi-Page Build

​Integration with Streaming Pipeline

​Testing

​Migration Guide

​Before (Manual URL Parsing)

​After (Utility Functions)

​Related Files

Viewport Mode Detection API

Overview

API Reference

`isStreamPageRoute(win?: Window): boolean`

`isEmbeddedSpectatorViewport(win?: Window): boolean`

`isStreamingLikeViewport(win?: Window): boolean`

Usage Patterns

Conditional UI Rendering

Streaming Optimizations

Spectator Controls

URL Patterns

Stream Mode

Embedded Spectator Mode

Normal Mode

Vite Multi-Page Build

Integration with Streaming Pipeline

Testing

Migration Guide

Before (Manual URL Parsing)

After (Utility Functions)

Related Files