Initial commit: Project structure and documentation

2026-03-21 10:29:35 +00:00
commit bf12ab5e57
11 changed files with 346 additions and 0 deletions
@@ -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.