You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
Matthew Raymer 3d226a38dc feat: Add comprehensive documentation and project structure improvements 5 days ago
.vscode Initial commit 2 years ago
components/objects feat: Add comprehensive documentation and project structure improvements 5 days ago
public Initial commit 2 years ago
src feat: Add comprehensive documentation and project structure improvements 5 days ago
.gitignore feat: Add comprehensive documentation and project structure improvements 5 days ago
.gitmodules Incremental update. Separating types 2 years ago
API.md feat: Add comprehensive documentation and project structure improvements 5 days ago
CHANGELOG.md feat: Add comprehensive documentation and project structure improvements 5 days ago
CONTRIBUTING.md feat: Add comprehensive documentation and project structure improvements 5 days ago
README.md feat: Add comprehensive documentation and project structure improvements 5 days ago
SECURITY.md feat: Add comprehensive documentation and project structure improvements 5 days ago
index.html Stable (?) stub 2 years ago
package-lock.json Incremental update. Separating types 2 years ago
package.json feat: Add comprehensive documentation and project structure improvements 5 days ago
tsconfig.json feat: Add comprehensive documentation and project structure improvements 5 days ago
tsconfig.node.json Initial commit 2 years ago
vite.config.ts feat: Add comprehensive documentation and project structure improvements 5 days ago

README.md

World Component

A reusable Vue 3 + TypeScript + Three.js component for creating interactive 3D worlds and visualizations.

Overview

The World Component is designed to be an abstract, reusable 3D visualization component that can be integrated into other projects. It provides a modular architecture with separate systems for rendering, controls, animation loops, and responsive resizing.

Project History

  • 2023-06-28: Initial commit - Basic Vue 3 + TypeScript + Vite setup
  • 2023-06-28: Stable stub - Core WorldComponent.vue structure
  • 2023-06-29: Added systems folder - Core rendering systems (Controls, Loop, Renderer, Resizer)
  • 2023-06-30: Incremental update - Separated types and added terrain/landmarks components

Architecture

The project follows a modular architecture with clear separation of concerns:

Core Systems (src/systems/)

  • Controls.ts: OrbitControls wrapper for camera manipulation
  • Loop.ts: Animation loop management with delta time
  • Renderer.ts: WebGL renderer abstraction
  • Resizer.ts: Responsive canvas resizing

Components (src/components/ and components/)

  • objects/Landmarks.ts: Dynamic landmark loading and animation
  • objects/Terrain.ts: Terrain generation with texture mapping

Main Component

  • WorldComponent.vue: Main Vue component that orchestrates the 3D world

Features

  • Modular Design: Each system is self-contained and reusable
  • TypeScript Support: Full type safety throughout the codebase
  • Three.js Integration: Leverages Three.js for 3D graphics
  • Responsive: Automatically handles window resizing
  • Animation System: Built-in animation loop with delta time
  • Camera Controls: Orbit controls with configurable limits
  • Dynamic Loading: Support for loading 3D models and landmarks
  • Texture Mapping: Terrain with texture support

Dependencies

Core Dependencies

  • Vue 3.3.4: Progressive JavaScript framework
  • Three.js 0.153.0: 3D graphics library
  • TypeScript 5.1.5: Type-safe JavaScript

Additional Dependencies

  • axios 1.4.0: HTTP client for API calls
  • ramda 0.29.0: Functional programming utilities
  • three-orbitcontrols-ts 0.1.2: TypeScript orbit controls
  • vue-facing-decorator 2.1.20: Class-based Vue components

Installation

# Clone the repository
git clone <repository-url>
cd world-component

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Usage

Basic Integration

<template>
  <div id="app">
    <WorldComponent />
  </div>
</template>

<script lang="ts">
import WorldComponent from './WorldComponent.vue'

export default {
  name: 'App',
  components: {
    WorldComponent
  }
}
</script>

Custom Configuration

The World Component can be customized by extending the base systems:

import { Controls } from './systems/Controls'
import { Loop } from './systems/Loop'
import { Renderer } from './systems/Renderer'
import { Resizer } from './systems/Resizer'

// Custom configuration
const controls = new Controls(camera, canvas)
const loop = new Loop(camera, scene, renderer)
const resizer = new Resizer(camera, renderer)

Development

Project Structure

world-component/
├── src/
│   ├── systems/           # Core rendering systems
│   │   ├── Controls.ts    # Camera controls
│   │   ├── Loop.ts        # Animation loop
│   │   ├── Renderer.ts    # WebGL renderer
│   │   └── Resizer.ts     # Responsive resizing
│   ├── components/
│   │   └── objects/       # 3D objects
│   │       └── Landmarks.ts
│   ├── types/             # TypeScript type definitions
│   ├── WorldComponent.vue # Main component
│   └── main.ts           # Application entry point
├── components/
│   └── objects/          # Additional 3D objects
│       └── Terrain.ts
└── public/               # Static assets

Adding New Systems

  1. Create a new TypeScript file in src/systems/
  2. Export a class with clear interfaces
  3. Integrate with the main WorldComponent
  4. Add proper TypeScript types

Adding New Objects

  1. Create a new TypeScript file in src/components/objects/
  2. Extend or use Three.js objects
  3. Implement a tick() method if animation is needed
  4. Add to the scene in WorldComponent

Security Considerations

  • API Calls: All external API calls use proper authentication
  • Asset Loading: 3D models are loaded from trusted sources
  • Input Validation: User inputs are validated before processing
  • Error Handling: Comprehensive error handling for all operations

Contributing

  1. Follow the existing code style and architecture
  2. Add comprehensive TypeScript types
  3. Include proper error handling
  4. Document all public methods and classes
  5. Test thoroughly before submitting

License

[Add your license information here]

Author

Matthew Raymer


This component is designed to be abstract and reusable across different projects requiring 3D visualization capabilities.