Ocean Adventure 🌊

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.

🎮 Game Overview

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.

🎯 Gameplay Features

• 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

🌟 Key Highlights

• 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

🚀 Quick Start

Play Now

Visit Ocean Adventure Game to play directly in your browser!

System Requirements

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

🛠️ Development

Prerequisites

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

Installation

# 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!

Available Scripts

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

📖 Documentation

📋 Project Documentation

• 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

🎯 Quick Links

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

🎨 Game Features

🏊‍♀️ Swimming Mechanics

• 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

🌊 Environments

• 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

⭐ Collectibles & Objectives

• 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

📱 Mobile Support

Ocean Adventure is fully optimized for mobile devices with:

📲 Touch Controls

• 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

⚡ Performance Optimization

• 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

🌐 Live Previews & Deployments

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

🚀 Stable Deployment

• 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.

🔄 Pull Request Previews

• 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

📋 Preview Management

• 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

🐳 Container Deployment

• 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

🚧 Development Status

📊 Current Progress

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

✅ Stage 1: Foundation & Setup (COMPLETED)

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

🎉 Stage 2: Core Game Engine (COMPLETED)

• ✅ 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

🎉 Stage 3: Game Objects & Mechanics (COMPLETED)

• ✅ 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 (NEXT)

🔮 Future Stages

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

📋 Latest Milestones

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.

🤝 Contributing

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

🔰 First-Time Contributors

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

🚀 Advanced Contributors

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

📝 Types of Contributions

• 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

🏗️ Project Structure

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

🔧 Technical Stack

🎨 Frontend Technologies

• 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

🚀 Performance Features

• 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

📊 Performance Targets

🐛 Bug Reports & Feature Requests

🔍 Reporting Issues

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

💡 Feature Requests

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

📄 License

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

🤲 Open Source Commitment

• 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

🙏 Acknowledgments

💖 Special Thanks

• 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

🌟 Built With

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

📞 Contact & Support

💬 Get Help

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

🔗 Links

• 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! 🌊🏊‍♀️⭐