world-component/API.md

World Component API Documentation

This document provides comprehensive API documentation for the World Component project, including all public interfaces, methods, and usage patterns.

Table of Contents

• Core Systems
• Components
• Types and Interfaces
• Usage Examples
• Configuration

Core Systems

Controls System

The Controls system provides camera orbit controls for the 3D world.

Controls Class

import { Controls } from '@/systems/Controls';

const controls = new Controls(camera: PerspectiveCamera, canvas: HTMLElement);

Constructor Parameters:

• camera: Three.js PerspectiveCamera instance
• canvas: HTML element to attach controls to

Methods:

• getControls(): OrbitControls - Returns the underlying OrbitControls instance

Configuration:

• Min polar angle: 40° (prevents camera from going below horizon)
• Max polar angle: 75° (prevents camera from going too high)
• Max distance: 250 units
• Damping enabled for smooth movement

Loop System

The Loop system manages the main animation loop and object updates.

Loop Class

import { Loop } from '@/systems/Loop';

const loop = new Loop(camera: PerspectiveCamera, scene: Scene, renderer: WebGLRenderer);

Constructor Parameters:

• camera: Three.js PerspectiveCamera instance
• scene: Three.js Scene instance
• renderer: Three.js WebGLRenderer instance

Methods:

• start(): void - Starts the animation loop
• stop(): void - Stops the animation loop

Features:

• Automatic delta time calculation
• Object update management
• Synchronized rendering

Renderer System

The Renderer system provides WebGL rendering abstraction.

Renderer Class

import { Renderer } from '@/systems/Renderer';

const renderer = new Renderer(parameters?: WebGLRendererParameters);

Constructor Parameters:

• parameters: Optional WebGL renderer configuration

Properties:

• domElement: HTMLCanvasElement - The canvas element for DOM insertion

Methods:

• render(scene: Scene, camera: Camera): void - Renders the scene

Resizer System

The Resizer system handles responsive canvas resizing.

Resizer Class

import { Resizer } from '@/systems/Resizer';

const resizer = new Resizer(camera: any, renderer: any);

Constructor Parameters:

• camera: Camera to adjust aspect ratio for
• renderer: Renderer to resize

Features:

• Automatic window resize handling
• Aspect ratio maintenance
• Pixel ratio optimization
• 50px UI offset compensation

Components

Terrain Component

The Terrain component creates textured terrain planes.

Terrain Class

import { Terrain } from '@/components/objects/Terrain';

const terrain = new Terrain({
  width: number,
  height: number,
  color: Color
});

Constructor Parameters:

• props.width: Width of the terrain plane
• props.height: Height of the terrain plane
• props.color: Base color of the terrain material

Returns: Three.js Mesh object

Features:

• Texture mapping support
• Configurable dimensions
• Flat shading
• Animation compatibility

Landmarks Component

The Landmarks component handles dynamic landmark loading and animation.

LandmarksLoader Class

import { LandmarksLoader } from '@/components/objects/Landmarks';

const landmarksLoader = new LandmarksLoader();
await landmarksLoader.load(vue, world, scene, loop, token);

Methods:

• load(vue, world, scene, loop, token): Promise<void> - Loads and creates landmarks

Parameters:

• vue: Vue component instance
• world: World object with scene and properties
• scene: Three.js scene
• loop: Animation loop instance
• token: Authentication token

Features:

• API data loading
• GLTF model loading
• Timed animations
• Lighting effects
• Error handling

Types and Interfaces

World Object Interface

interface World {
  scene: Scene;
  bushes: Object3D[];
  lights: Light[];
  PLATFORM_SIZE: number;
  PLATFORM_EDGE_FOR_UNKNOWNS: number;
  setExposedWorldProperties(key: string, value: any): void;
}

GiveServerRecord Interface

interface GiveServerRecord {
  issuedAt: string;
  // Additional properties as defined by the server
}

Terrain Props Interface

interface TerrainProps {
  width: number;
  height: number;
  color: Color;
}

Usage Examples

Basic World Setup

import { Controls } from '@/systems/Controls';
import { Loop } from '@/systems/Loop';
import { Renderer } from '@/systems/Renderer';
import { Resizer } from '@/systems/Resizer';
import { Scene, PerspectiveCamera } from 'three';

// Create Three.js objects
const scene = new Scene();
const camera = new PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new Renderer();

// Initialize systems
const controls = new Controls(camera, renderer.domElement);
const loop = new Loop(camera, scene, renderer);
const resizer = new Resizer(camera, renderer);

// Add to DOM
document.body.appendChild(renderer.domElement);

// Start animation loop
loop.start();

Terrain Creation

import { Terrain } from '@/components/objects/Terrain';
import { Color } from 'three';

const terrain = new Terrain({
  width: 100,
  height: 100,
  color: new Color(0x8B4513) // Brown color
});

scene.add(terrain);

Landmarks Loading

import { LandmarksLoader } from '@/components/objects/Landmarks';

const landmarksLoader = new LandmarksLoader();

try {
  await landmarksLoader.load(vue, world, scene, loop, authToken);
} catch (error) {
  console.error('Failed to load landmarks:', error);
}

Configuration

Environment Variables

# API Configuration
VITE_API_SERVER=https://api.example.com
VITE_ANIMATION_DURATION_SECS=30

# Development Configuration
VITE_DEV_MODE=true
VITE_DEBUG_LOGGING=true

Build Configuration

The project uses Vite for building with the following optimizations:

• Code Splitting: Automatic chunk splitting
• Tree Shaking: Unused code elimination
• Source Maps: Development debugging support
• Asset Optimization: Automatic asset optimization

TypeScript Configuration

Key TypeScript settings:

• Strict Mode: Enabled for type safety
• Path Aliases: Configured for clean imports
• Decorators: Enabled for Vue-facing-decorator
• Module Resolution: Bundler mode for Vite

Error Handling

Common Error Patterns

// API Error Handling
try {
  await landmarksLoader.load(vue, world, scene, loop, token);
} catch (error) {
  if (error.response?.status === 401) {
    // Handle authentication error
  } else if (error.response?.status === 404) {
    // Handle not found error
  } else {
    // Handle general error
  }
}

// Three.js Error Handling
try {
  const terrain = new Terrain(props);
} catch (error) {
  console.error('Terrain creation failed:', error);
  // Fallback to basic geometry
}

Error Recovery

• Texture Loading: Fallback to solid colors
• Model Loading: Use placeholder geometry
• API Failures: Graceful degradation
• WebGL Errors: Canvas fallback

Performance Considerations

Optimization Tips

1. Object Pooling: Reuse objects when possible
2. LOD (Level of Detail): Implement distance-based detail
3. Frustum Culling: Only render visible objects
4. Texture Compression: Use compressed textures
5. Geometry Instancing: Use instanced rendering for repeated objects

Memory Management

// Proper disposal
componentWillUnmount() {
  // Dispose of Three.js objects
  this.geometry.dispose();
  this.material.dispose();
  this.texture.dispose();
  
  // Stop animation loop
  this.loop.stop();
}

Browser Support

Supported Browsers

• Chrome >= 88
• Firefox >= 85
• Safari >= 14
• Edge >= 88

WebGL Requirements

• WebGL 2.0 support
• Hardware acceleration
• Adequate GPU memory

---

This API documentation is maintained alongside the codebase and should be updated with any changes to the public interfaces.