# Contributing to World Component

Thank you for your interest in contributing to the World Component project! This document provides guidelines and information for contributors.

## Table of Contents

- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Coding Standards](#coding-standards)
- [Architecture Guidelines](#architecture-guidelines)
- [Testing](#testing)
- [Pull Request Process](#pull-request-process)
- [Code Review Guidelines](#code-review-guidelines)

## Getting Started

### Prerequisites

- Node.js >= 16.0.0
- npm >= 8.0.0
- Git

### Development Setup

1. **Fork the repository**
   ```bash
   git clone https://github.com/yourusername/world-component.git
   cd world-component
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Start development server**
   ```bash
   npm run dev
   ```

4. **Run type checking**
   ```bash
   npm run type-check
   ```

## Coding Standards

### TypeScript Guidelines

- Use strict TypeScript configuration
- Provide comprehensive type definitions
- Use interfaces for object shapes
- Prefer `const` over `let` when possible
- Use meaningful variable and function names

### Vue Component Guidelines

- Use Vue 3 Composition API or Class-based components with vue-facing-decorator
- Keep components focused and single-purpose
- Use proper prop validation
- Implement proper lifecycle management
- Use scoped styles when possible

### Three.js Guidelines

- Follow Three.js best practices for performance
- Dispose of resources properly (geometries, materials, textures)
- Use object pooling for frequently created/destroyed objects
- Implement proper cleanup in component unmount

### Documentation Standards

- Document all public methods and classes
- Include JSDoc comments for complex functions
- Provide usage examples in documentation
- Update README.md for significant changes

### Code Style

- Follow PEP 8 equivalent for TypeScript (80 character line limit)
- Use meaningful variable names
- Add comments for complex logic
- Keep methods under 80 lines when possible
- Use consistent indentation (2 spaces)

## Architecture Guidelines

### System Design

- Keep systems modular and focused
- Use dependency injection where appropriate
- Implement proper error handling
- Follow the single responsibility principle

### File Organization

```
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
├── types/             # TypeScript definitions
└── utils/             # Utility functions
```

### Adding New Systems

1. Create a new TypeScript file in `src/systems/`
2. Export a class with clear interfaces
3. Add comprehensive documentation
4. Include proper error handling
5. Add to the main WorldComponent integration

### Adding New Objects

1. Create a new TypeScript file in `src/components/objects/`
2. Extend or use Three.js objects appropriately
3. Implement a `tick()` method if animation is needed
4. Add proper cleanup methods
5. Document the object's purpose and usage

## Testing

### Running Tests

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

### Writing Tests

- Write unit tests for all public methods
- Test error conditions and edge cases
- Use descriptive test names
- Mock external dependencies
- Test Three.js objects in isolation

## Pull Request Process

### Before Submitting

1. **Ensure code quality**
   - Run `npm run type-check`
   - Run `npm run lint`
   - Run `npm run format`
   - All tests pass

2. **Update documentation**
   - Update README.md if needed
   - Add JSDoc comments for new methods
   - Update any relevant documentation

3. **Test thoroughly**
   - Test in different browsers
   - Test with different screen sizes
   - Test performance impact

### Pull Request Guidelines

1. **Create a descriptive title**
   - Use conventional commit format
   - Be specific about the change

2. **Write a detailed description**
   - Explain what the PR does
   - Include screenshots for UI changes
   - Reference related issues

3. **Keep PRs focused**
   - One feature or fix per PR
   - Keep changes manageable
   - Break large changes into smaller PRs

## Code Review Guidelines

### Review Process

1. **Automated checks must pass**
   - TypeScript compilation
   - Linting
   - Tests

2. **Manual review checklist**
   - Code follows project standards
   - Documentation is complete
   - Error handling is appropriate
   - Performance impact is considered
   - Security implications are addressed

### Review Comments

- Be constructive and specific
- Suggest improvements when possible
- Ask questions for clarification
- Use inline comments for specific issues

## Security Considerations

### Code Review Checklist

- [ ] No hardcoded secrets or API keys
- [ ] Input validation is implemented
- [ ] Error messages don't expose sensitive information
- [ ] External dependencies are from trusted sources
- [ ] Three.js objects are properly disposed
- [ ] No XSS vulnerabilities in dynamic content

### Reporting Security Issues

If you discover a security vulnerability, please:

1. **Do not create a public issue**
2. **Email the maintainer directly**
3. **Provide detailed information**
4. **Allow time for response**

## Getting Help

- **Documentation**: Check the README.md and inline documentation
- **Issues**: Search existing issues before creating new ones
- **Discussions**: Use GitHub Discussions for questions
- **Chat**: Join our community chat (if available)

## License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project.

---

Thank you for contributing to World Component! Your efforts help make this project better for everyone.