commit bf12ab5e5758b9f52e8f1316b8fbe9e99262f881 Author: User Date: Sat Mar 21 10:29:35 2026 +0000 Initial commit: Project structure and documentation diff --git a/.a0proj/agents.json b/.a0proj/agents.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/.a0proj/agents.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/.a0proj/memory/embedding.json b/.a0proj/memory/embedding.json new file mode 100644 index 0000000..4b4ceb4 --- /dev/null +++ b/.a0proj/memory/embedding.json @@ -0,0 +1 @@ +{"model_provider": "huggingface", "model_name": "sentence-transformers/all-MiniLM-L6-v2"} \ No newline at end of file diff --git a/.a0proj/memory/index.faiss b/.a0proj/memory/index.faiss new file mode 100644 index 0000000..923ed1a Binary files /dev/null and b/.a0proj/memory/index.faiss differ diff --git a/.a0proj/memory/index.pkl b/.a0proj/memory/index.pkl new file mode 100644 index 0000000..84c6a44 Binary files /dev/null and b/.a0proj/memory/index.pkl differ diff --git a/.a0proj/memory/knowledge_import.json b/.a0proj/memory/knowledge_import.json new file mode 100644 index 0000000..9aee8d7 --- /dev/null +++ b/.a0proj/memory/knowledge_import.json @@ -0,0 +1 @@ +{"/a0/knowledge/main/about/github_readme.md": {"file": "/a0/knowledge/main/about/github_readme.md", "checksum": "60fcbd470ea57133e6f949b80e14490e", "ids": ["KV5nnBpdaM", "Dfl2s19T3t", "9DLQfNjrxt", "tLBC2pmMzx", "sTm0FPSqKv", "1K14cggHPO"]}, "/a0/knowledge/main/about/installation.md": {"file": "/a0/knowledge/main/about/installation.md", "checksum": "9ed8bf50b81ca30e74ba2d6bd76836c0", "ids": ["2D6FRytthd", "oWQAtW44VO", "b1rgZuFvWO", "FEYpysrqnM", "LD7eM4Wsgc", "p4B3ShreeS"]}} \ No newline at end of file diff --git a/.a0proj/project.json b/.a0proj/project.json new file mode 100644 index 0000000..a5bb236 --- /dev/null +++ b/.a0proj/project.json @@ -0,0 +1 @@ +{"title": "3D flyer", "description": "We're replicating late-80s flight simulators in a web browser using JS and Threee.js. The intent is to make it look like something you'd find on a PC or Amiga of the time. Think low-resolution, polygonal, low frame-rate. The landscape must be realistic (villages, forests, bodies of water) but should be procedural with persistence!", "instructions": "Always test. Use your knowledge of playwright, for example. Check for front-end JS errors. Any new features should be in a new branch - the repo is at gitea@repos.retroweb.dev:ai-zone/wings88.git but try https if that doesn't work. Ask the user if any permissions are required.", "color": "#fb5607", "git_url": "", "memory": "own", "file_structure": {"enabled": true, "max_depth": 5, "max_files": 20, "max_folders": 20, "max_lines": 250, "gitignore": "# Python environments & cache\nvenv/**\n**/__pycache__/**\n\n# Node.js dependencies\n**/node_modules/**\n**/.npm/**\n\n# Version control metadata\n**/.git/**\n"}} \ No newline at end of file diff --git a/.a0proj/secrets.env b/.a0proj/secrets.env new file mode 100644 index 0000000..e69de29 diff --git a/.a0proj/variables.env b/.a0proj/variables.env new file mode 100644 index 0000000..e69de29 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..dfdca33 --- /dev/null +++ b/.gitignore @@ -0,0 +1,72 @@ +# Dependencies +node_modules/ + +# Environment files +.env +.env.local + +# IDE and editor files +dist/ +.DS_Store +.vscode/ +.idea/ + +# Build output +/dist/ +/build/ + +# Logs +logs/ +*.log + +# Runtime data +.pids/ +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage +lib-cov/ + +# Coverage data +coverage/ + +# npm cache +npm-debug.log* + +# Yarn cache +.yarn-cache/ + +# dotenv directory +.env*.local + +# next.js +.next/ +out/ + +# Vite +.cache/ + +# Editor swap files +*.swp +*.swo + +# macOS files +.DS_Store +.AppleDouble +.LSOverride + +# Windows files +Thumbs.db +Desktop.ini + +# Linux files +*.~ +*.bak + +# Temporary files +*.tmp +*.temp + +# OS generated files +._* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0ff4be7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,132 @@ +# Contributing to 3D Flight Simulator + +Thank you for considering contributing to the 3D Flight Simulator project! We welcome contributions from everyone, whether you're fixing bugs, adding new features, improving documentation, or suggesting enhancements. + +## 🤝 How to Contribute + +### 1. Reporting Issues + +Before creating a new issue, please check if it has already been reported: +- Search the [issue tracker](https://gitea@repos.retroweb.dev:ai-zone/wings88/issues) +- If you find a related issue, add a comment with additional information + +When reporting a new issue, please include: +- A clear description of the problem +- Steps to reproduce the issue +- Your browser and operating system +- Any relevant screenshots or error messages + +### 2. Suggesting Features + +We welcome feature requests! Please: +- Describe the feature in detail +- Explain why it would be useful +- Provide any relevant examples or mockups + +### 3. Code Contributions + +#### Setting Up the Project + +1. Fork the repository on GitHub +2. Clone your fork locally: + ```bash + git clone https://gitea@repos.retroweb.dev:ai-zone/wings88.git + cd wings88 + ``` +3. Set up the development environment: + ```bash + npm install + ``` + +#### Making Changes + +1. Create a new branch for your feature or bug fix: + ```bash + git checkout -b your-branch-name + ``` +2. Make your changes to the code +3. Test your changes thoroughly +4. Update documentation if needed +5. Commit your changes with a meaningful message: + ```bash + git commit -m "feat: add new feature description" + ``` + +#### Submitting a Pull Request + +1. Push your branch to your fork: + ```bash + git push origin your-branch-name + ``` +2. Open a pull request on the main repository +3. Fill out the pull request template with: + - Description of your changes + - Related issues (if any) + - Screenshots (if applicable) + - Testing instructions + +### 4. Documentation Contributions + +Improving documentation is just as valuable as code contributions! Please: +- Fix typos or unclear explanations +- Add missing information +- Improve code examples +- Update API documentation + +### 5. Testing + +We appreciate contributions that improve test coverage: +- Add unit tests for new features +- Add integration tests for critical paths +- Fix failing tests + +## 📜 Code of Conduct + +Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms. + +## 📋 Development Guidelines + +### Coding Standards + +- Follow the existing code style +- Write self-documenting code with meaningful variable names +- Keep functions small and focused +- Add comments for complex logic +- Write unit tests for new functionality + +### Commit Messages + +Please follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: +- `feat:` for new features +- `fix:` for bug fixes +- `docs:` for documentation changes +- `style:` for code style changes +- `refactor:` for code refactoring +- `test:` for test-related changes +- `chore:` for maintenance tasks + +### Branching Strategy + +- `main` - Production-ready code (protected branch) +- `dev` - Development branch for new features +- Feature branches - Named after the feature being developed (e.g., `feat/landscape-generation`) +- Bugfix branches - Named after the bug being fixed (e.g., `fix/crash-on-load`) + +## 📞 Communication + +For questions or discussions, please: +- Use the [GitHub Discussions](https://gitea@repos.retroweb.dev:ai-zone/wings88/discussions) feature +- Open an issue for specific questions about the codebase +- Join our community chat (if available) + +## 🎯 Current Priorities + +Check the [project board](https://gitea@repos.retroweb.dev:ai-zone/wings88/projects) for current priorities and ongoing work. + +## 📝 Additional Resources + +- [Three.js Documentation](https://threejs.org/docs/) +- [Web Audio API Documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) +- [Canvas API Documentation](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) + +Thank you for contributing to the 3D Flight Simulator project! Your efforts help make this project better for everyone. diff --git a/README.md b/README.md new file mode 100644 index 0000000..d39b606 --- /dev/null +++ b/README.md @@ -0,0 +1,138 @@ +# 3D Flight Simulator (Retro 80s Style) + +A browser-based 3D flight simulator with retro 80s aesthetic, procedural landscape generation, and persistent world saving. + +## 🎮 Project Overview + +This project recreates the feel of late-80s flight simulators in a web browser using JavaScript and Three.js. The intent is to make it look like something you'd find on a PC or Amiga of the time - low-resolution, polygonal, low frame-rate with a retro aesthetic. + +### Key Features + +- **Retro 80s Aesthetic**: Low-resolution, polygonal graphics with 80s color palettes +- **Procedural Landscape**: Realistic villages, forests, bodies of water generated procedurally +- **Persistent World**: Once generated, landscapes remain consistent across sessions +- **Multiple Screens**: Loading, intro, play, and pause screens +- **Flight Controls**: Cockpit HUD with dials and metrics +- **Save/Load System**: Save game progress including procedural landscapes +- **FPS Cap**: Configurable frame rate cap (20, 30, 50, 60 FPS) for authentic retro feel +- **Retro Audio**: Synthesized music similar to Soundblaster MIDI + +## 🚀 Getting Started + +### Prerequisites + +- Node.js (v16 or higher) +- npm or yarn +- Modern web browser (Chrome, Firefox, Edge) + +### Installation + +1. Clone the repository: + ```bash + git clone https://gitea@repos.retroweb.dev:ai-zone/wings88.git + cd wings88 + ``` + +2. Install dependencies: + ```bash + npm install + ``` + +3. Start the development server: + ```bash + npm run dev + ``` + +4. Open your browser to `http://localhost:3000` + +### Building for Production + +```bash +npm run build +``` + +This will create optimized production files in the `dist/` directory. + +## 📂 Project Structure + +``` +/a0/usr/projects/3d_flyer/ +├── .a0proj/ # Project configuration +├── src/ # Source code +│ ├── assets/ # Static assets +│ │ ├── images/ # Image files +│ │ ├── sounds/ # Audio files +│ │ └── models/ # 3D models +│ ├── js/ # JavaScript code +│ │ ├── screens/ # Screen components +│ │ ├── core/ # Core game logic +│ │ └── utils/ # Utility functions +│ ├── css/ # CSS styles +│ └── index.html # Main HTML file +├── public/ # Public assets +├── docs/ # Documentation +├── tests/ # Test files +├── .gitignore # Git ignore rules +├── package.json # Project configuration +├── README.md # This file +├── LICENSE # License information +└── CONTRIBUTING.md # Contribution guidelines +``` + +## 🛠️ Development + +### Available Scripts + +- `npm run dev` - Start development server with hot reload +- `npm run build` - Create production build +- `npm run test` - Run tests +- `npm run lint` - Run linter + +### Branching Strategy + +- `main` - Production-ready code +- `dev` - Development branch for new features +- Feature branches - Named after the feature being developed + +### Commit Messages + +Follow conventional commits format: +- `feat:` for new features +- `fix:` for bug fixes +- `docs:` for documentation changes +- `style:` for code style changes +- `refactor:` for code refactoring +- `test:` for test-related changes + +## 🎨 Design Guidelines + +### Color Palette + +Inspired by 80s gaming (Amiga 500, 386 DOS): +- Use limited color palettes (16-32 colors) +- Prefer vibrant, distinctive colors +- Avoid anti-aliasing for pixelated look + +### Sound Design + +- Synthesized music similar to Soundblaster MIDI +- Retro sound effects +- Procedural audio generation for dynamic environments + +### Performance Targets + +- Default FPS cap: 20 FPS (configurable) +- Low memory footprint +- Fast load times + +## 📜 License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## 🤝 Contributing + +Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. + +## 📞 Contact + +For questions or support, please open an issue in the repository.