# 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](#core-systems)
- [Components](#components)
- [Types and Interfaces](#types-and-interfaces)
- [Usage Examples](#usage-examples)
- [Configuration](#configuration)

## Core Systems

### Controls System

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

#### `Controls` Class

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

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

### GiveServerRecord Interface

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

### Terrain Props Interface

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

## Usage Examples

### Basic World Setup

```typescript
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

```typescript
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

```typescript
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

```bash
# 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

```typescript
// 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

```typescript
// 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.*