3D Warehouse Tetris

A 3D warehouse logistics game built with Babylon.js where players pack pallets with various-sized boxes in real-time.

🎮 Game Overview

This is a unique take on the classic Tetris concept, adapted for warehouse logistics. Players must efficiently pack a pallet with boxes of varying sizes, optimizing space usage while maintaining stability. The game features realistic physics, 3D visualization, and progressive difficulty.

✨ Features

Core Gameplay

• 3D Environment: Full 3D warehouse scene with container dimensions (1200×1000×2000mm)
• Dynamic Box Generation: Boxes range from 100×100×50mm to 1200×1000×1000mm
• Smart Distribution: Piece sizes follow normal distribution (large pieces 3σ, small pieces 1σ)
• Physics-Based Stacking: Realistic collision detection and gravity
• Stability System: Boxes require 80% support area to be considered stable

Controls

• Arrow Keys: Move pieces horizontally and forward/backward
• F Key: Rotate piece 90° around Y-axis
• Space Bar: Temporarily slow down game (20% speed)
• P Key: Pause/Resume game
• R Key: Reset game
• F11: Toggle fullscreen

Mobile Support

• Single Finger: Drag to move pieces
• Double Tap: Rotate piece
• Two Finger Spread: Slow down game temporarily

Game Mechanics

• Progressive Difficulty: Drop time decreases from 10s to 2s over 10 stages
• Score System: Based on fill ratio and piece count
• Piece Queue: Preview of next 5 pieces
• Game End: Triggers when first piece exceeds container height

🚀 Getting Started

Prerequisites

• Modern web browser with WebGL support
• No additional software installation required

Installation

1. Clone or download the repository
2. Open index.html in a web browser
3. Start playing immediately!

Local Development

For development, you can use any local web server:

# Using Python 3
python -m http.server 8000

# Using Node.js
npx http-server

# Using PHP
php -S localhost:8000

Then navigate to http://localhost:8000

🏗️ Architecture

File Structure

warehouse-tetris/
├── index.html          # Main HTML file
├── js/
│   ├── game.js         # Core game engine
│   ├── piece.js        # Game piece management
│   ├── physics.js      # Physics and collision detection
│   └── ui.js           # User interface and controls
└── README.md           # This file

Core Classes

WarehouseTetrisGame

• Main game controller
• Manages game state, piece spawning, and game loop
• Handles input and collision detection

GamePiece

• Individual box representation
• 3D mesh creation and physics setup
• Stability calculations and visual feedback

PhysicsEngine

• Collision detection and resolution
• Support area calculations
• Convex hull algorithms for stability

GameUI

• User interface management
• Touch controls for mobile
• Score display and game state UI

🎯 Game Rules

1. Objective: Pack as many boxes as possible into the container
2. Scoring: Based on container fill ratio and number of pieces placed
3. Stability: Each piece must have at least 80% support area
4. Game End: Occurs when a piece is placed above container height
5. Progression: Speed increases every minute (stage progression)

🔧 Customization

Game Parameters

Modify these values in js/game.js:

// Container dimensions (in mm)
this.baseWidth = 1200 / 1000;      // 1.2 units
this.baseLength = 1000 / 1000;     // 1.0 units
this.containerHeight = 2000 / 1000; // 2.0 units

// Piece size constraints
this.minPieceSize = { x: 100, y: 100, z: 50 };
this.maxPieceSize = { x: 1200, y: 1000, z: 1000 };

// Game timing
this.dropTime = 10000; // 10 seconds

Visual Customization

• Modify colors in js/piece.js for different box appearances
• Adjust lighting in js/game.js for different atmospheres
• Change materials and textures for varied visual effects

📱 Mobile Optimization

The game is designed with mobile devices in mind:

• Touch-friendly controls
• Responsive design
• Optimized 3D rendering
• Gesture-based interactions

Enhanced Boundary Detection System

The game now features a comprehensive boundary detection system that prevents pieces from falling outside the playable area:

Virtual Container Boundaries

• Primary XZ Limits: Pieces cannot extend beyond the base container's XZ dimensions
• Dynamic Adjustment: Boundaries automatically adjust based on the current piece's Y position

Placed Piece Boundaries

• Secondary XZ Limits: Previously placed static boxes act as additional boundary constraints
• Smart Detection: Only considers placed pieces that are at or above the falling piece's bottom level
• Most Restrictive: Uses the most restrictive boundaries from both virtual container and placed pieces

Boundary Enforcement

• Continuous Monitoring: Boundaries are checked during all piece movements (dropping, moving, rotating, spawning)
• Automatic Correction: Pieces are automatically repositioned to stay within effective boundaries
• Real-time Updates: Boundaries update dynamically as the stack grows higher

Debugging Tools

• Key B: Log current boundary status and effective boundaries
• Key N: Force boundary constraint and show visual feedback
• Key V: Toggle visual boundary debug lines (blue = virtual container, red = effective boundaries)

Technical Implementation

• checkAndConstrainPieceBoundaries(): Main boundary enforcement method
• calculatePieceBoundaries(pieceBottomY): Calculates effective boundaries considering placed pieces
• isPieceWithinBoundaries(piece): Checks if a piece is within current effective boundaries
• Visual Debug Lines: Real-time visualization of boundary constraints

This system ensures realistic stacking behavior where pieces cannot fall outside the logical playable area defined by both the container and previously placed pieces.

🚧 Future Enhancements

Phase 2 Features

• Multi-Viewport System: 4-corner camera views for better visibility
• Advanced Physics: More realistic stacking and stability calculations
• Piece Variations: Different box types and materials
• Sound Effects: Audio feedback for actions and events

Phase 3 Features

• Android App: Native mobile application
• Leaderboards: Online score tracking
• Multiplayer: Competitive and cooperative modes
• Custom Levels: User-created warehouse layouts

🐛 Known Issues

• Physics engine may occasionally cause pieces to overlap
• Support area calculation is simplified and may not be 100% accurate
• Mobile performance may vary based on device capabilities

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Babylon.js Team: For the excellent 3D engine
• Tetris: For the original game concept inspiration
• Warehouse Logistics: For the real-world application context

📞 Support

For questions, issues, or contributions:

• Create an issue in the repository
• Check the documentation
• Review the code comments for implementation details

---

Happy Packing! 🎯📦