{"id":28491667,"url":"https://github.com/dimillian/boomrl","last_synced_at":"2026-04-24T21:32:04.975Z","repository":{"id":295961805,"uuid":"991798495","full_name":"Dimillian/BoomRL","owner":"Dimillian","description":"A roguelike Doom that you can play in your browser","archived":false,"fork":false,"pushed_at":"2025-05-28T08:07:47.000Z","size":82,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-21T13:40:42.494Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dimillian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-28T07:01:19.000Z","updated_at":"2025-07-04T09:24:21.000Z","dependencies_parsed_at":"2025-06-02T23:35:58.194Z","dependency_job_id":null,"html_url":"https://github.com/Dimillian/BoomRL","commit_stats":null,"previous_names":["dimillian/boomrl"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Dimillian/BoomRL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimillian%2FBoomRL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimillian%2FBoomRL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimillian%2FBoomRL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimillian%2FBoomRL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dimillian","download_url":"https://codeload.github.com/Dimillian/BoomRL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimillian%2FBoomRL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32241616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-08T08:08:03.459Z","updated_at":"2026-04-24T21:32:04.970Z","avatar_url":"https://github.com/Dimillian.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BoomRL - Roguelike Doom\n\nA browser-based roguelike Doom-style first-person shooter built with **TypeScript** and Three.js. Experience fast-paced FPS action combined with roguelike progression, featuring procedural level generation, randomized weapons with rarities, and meta-progression systems.\n\n## 🎮 Features\n\n### Core Gameplay\n- **First-Person Shooter**: Doom-style movement and shooting mechanics\n- **Procedural Levels**: Every run features unique maze-like environments\n- **Weapon System**: 6 weapon types with 5 rarity levels and 10+ modifiers\n- **Roguelike Elements**: Permadeath, random generation, meta-progression\n\n### Weapon System (The Fun Part!)\n- **Weapon Types**: Pistol, Shotgun, Assault Rifle, SMG, Sniper Rifle, Plasma Rifle\n- **Rarity System**: Common → Uncommon → Rare → Epic → Legendary\n- **Modifiers**: Explosive, Piercing, Incendiary, Vampiric, Electric, and more\n- **Dynamic Stats**: Damage, fire rate, reload speed, accuracy, range, magazine size\n- **Procedural Names**: \"Epic Explosive Assault Rifle of Piercing\"\n\n### Progression \u0026 Meta-Game\n- **Resource Collection**: Scrap metal, energy cores, weapon parts\n- **Persistent Upgrades**: Health, speed, damage, reload speed improvements\n- **Weapon Unlocks**: Discover new weapon types through gameplay\n- **Statistics Tracking**: Performance metrics and achievement system\n\n## 🛠️ Technology Stack\n\n- **Language**: TypeScript (strict mode enabled)\n- **3D Engine**: Three.js with full type definitions\n- **Build Tool**: Vite with TypeScript support\n- **Audio**: Howler.js (planned)\n- **Styling**: CSS3 with retro terminal aesthetic\n- **Development**: ES6 modules, path aliases, comprehensive type safety\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Node.js (v18 or higher)\n- npm or yarn\n\n### Installation\n```bash\n# Clone the repository\ngit clone https://github.com/dimillian/BoomRL.git\ncd BoomRL\n\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n```\n\nThe game will be available at `http://localhost:5173`\n\n### Development Commands\n```bash\nnpm run dev          # Start development server with hot reload\nnpm run build        # Build for production (includes TypeScript checking)\nnpm run preview      # Preview production build\nnpm run type-check   # Run TypeScript type checking\nnpm run lint         # Run ESLint code quality checks\n```\n\n## 🎯 Controls\n\n- **WASD** - Movement\n- **Mouse** - Look around (pointer lock)\n- **Left Click** - Shoot\n- **R** - Reload weapon\n- **E** - Interact with objects\n- **ESC** - Toggle menu\n- **Shift** - Run (hold)\n- **Ctrl** - Crouch (hold)\n- **Space** - Jump\n\n## 📁 Project Structure\n\n```\nBoomRL/\n├── src/\n│   ├── main.ts              # Entry point (TypeScript)\n│   ├── types/\n│   │   ├── game.ts          # Comprehensive type definitions\n│   │   └── modules.d.ts     # Module declarations\n│   ├── core/                # Core game systems\n│   │   ├── Game.js          # Main game loop and scene\n│   │   └── InputManager.js  # Input handling system\n│   ├── entities/            # Game entities\n│   │   └── Player.js        # Player controller\n│   ├── levels/              # Level generation\n│   │   └── Level.js         # Procedural level generator\n│   ├── weapons/             # Weapon system\n│   │   ├── WeaponSystem.js  # Weapon generation and management\n│   │   └── Weapon.js        # Individual weapon class\n│   ├── ui/                  # User interface\n│   │   └── UIManager.js     # UI state and HUD management\n│   └── utils/               # Utility functions\n│       └── MathUtils.js     # Mathematical helpers\n├── docs/                    # Documentation\n│   ├── DEVELOPMENT.md       # Technical architecture\n│   └── GAME_RULES.md        # Game design document\n├── tsconfig.json            # TypeScript configuration\n├── vite.config.ts           # Vite build configuration\n└── package.json             # Dependencies and scripts\n```\n\n## 🔧 TypeScript Migration Status\n\n### ✅ Completed\n- [x] TypeScript configuration and build setup\n- [x] Comprehensive type definitions (`src/types/game.ts`)\n- [x] Main entry point converted to TypeScript\n- [x] Path aliases and module resolution\n- [x] Development workflow with type checking\n\n### 🔄 In Progress\n- [ ] Core systems conversion (Game, InputManager, UIManager)\n- [ ] Entity systems conversion (Player)\n- [ ] Level generation system conversion\n- [ ] Weapon system conversion\n\n### 🎯 Benefits of TypeScript\n- **Type Safety**: Catch errors at compile time\n- **Better IntelliSense**: Full autocompletion for Three.js and game objects\n- **Refactoring**: Safe code changes and renames\n- **Documentation**: Types serve as inline documentation\n- **Scalability**: Easier to maintain and extend\n\n## 🎪 Current Development Phase\n\n**Phase 1**: ✅ Complete - Core FPS mechanics with playable prototype\n**Phase 2**: 🚧 In Progress - TypeScript conversion and enemy AI system\n**Phase 3**: 📋 Planned - Meta-progression and loot systems\n**Phase 4**: 📋 Planned - Audio, effects, and optimization\n\n## 🎲 Game Design Philosophy\n\n### Roguelike Elements\n- **Procedural Generation**: Every run is unique\n- **Permadeath**: Death resets progress, encouraging risk/reward decisions\n- **Meta-Progression**: Permanent upgrades provide long-term goals\n- **Emergent Gameplay**: Random weapons create varied strategies\n\n### FPS Mechanics\n- **Fast-Paced**: Doom-style movement with momentum\n- **Weapon Variety**: Each weapon type offers different playstyles\n- **Skill-Based**: Player improvement through practice and knowledge\n- **Visual Feedback**: Clear hit indicators and responsive controls\n\n## 🐛 Development \u0026 Debugging\n\n### Console Logging System\nThe game uses emoji-prefixed console logs for easy debugging:\n- 🎮 Game initialization and lifecycle\n- 🔫 Weapon system and combat\n- 🗺️ Level generation and management\n- 🖥️ UI state changes\n- 💥 Combat and damage events\n\n### TypeScript Development\n```bash\n# Watch for TypeScript errors\nnpm run type-check\n\n# Development with hot reload\nnpm run dev\n\n# Check code quality\nnpm run lint\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch: `git checkout -b feature/amazing-feature`\n3. Follow TypeScript coding standards (see `.cursorrules`)\n4. Commit your changes: `git commit -m 'Add amazing feature'`\n5. Push to the branch: `git push origin feature/amazing-feature`\n6. Open a Pull Request\n\n### Code Standards\n- Use TypeScript strict mode\n- Provide explicit types for all public APIs\n- Follow the existing emoji logging system\n- Write clear, descriptive commit messages\n- Test changes in the browser before submitting\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🎯 Roadmap\n\n- [ ] Complete TypeScript conversion\n- [ ] Enemy AI and combat system\n- [ ] Audio system with spatial sound\n- [ ] Visual effects and particles\n- [ ] Mobile touch controls\n- [ ] Multiplayer support (future consideration)\n\n---\n\n**Ready to experience the ultimate browser-based roguelike FPS? Clone, build, and start your BoomRL adventure! 🎮🔫**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimillian%2Fboomrl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimillian%2Fboomrl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimillian%2Fboomrl/lists"}