Zoodeku 🦁

A mobile puzzle game for Android inspired by the iOS game Bullpen, combining elements of Minesweeper and Sudoku. Built with Godot 4.7.1.

🎮 Game Description

Zoodeku is a logic puzzle game where players must find hidden animals on a grid using deduction and logic. Each animal must be placed according to strict rules:

• One animal per row
• One animal per column
• One animal per color block
• Animals cannot touch each other (including diagonally)

🎯 How to Play

Controls

• Single tap: Place a white cross (✕) to mark cells that cannot contain animals
• Double tap: Attempt to reveal an animal
  • ✅ Correct: Animal emoji is revealed
  • ❌ Wrong: Lose a life

Objective

Find all the hidden animals to complete the puzzle. The number of lives varies by difficulty.

Game Modes

• Main Path: 10 hand-crafted levels with increasing difficulty
• Endless Mode: Randomly generated puzzles for infinite play

Progression

• Complete levels to unlock new animal emojis
• Unlock animals: 🦁 (Lion), 🐘 (Elephant), 🦊 (Fox), 🐼 (Panda), 🦋 (Butterfly)
• Customize your game with your favorite unlocked animal

🚀 Getting Started

Prerequisites

• Godot Engine 4.7.1 or later
• For Android export: Android SDK and build tools

Running the Game

Using GDVM (Recommended)

# Navigate to project directory
cd zoodeku

# Run the game
gdvm run

Using Godot Editor

1. Open the project in Godot Editor
2. Press F5 or click the Play button

Building for Android

1. Open the project in Godot Editor
2. Go to Project → Export
3. Add Android export preset
4. Configure:
   • Package name (e.g., com.yourname.zoodeku)
   • Minimum SDK level
   • Signing certificates
5. Click Export Project to generate APK

📁 Project Structure

zoodeku/
├── scripts/
│   ├── cell.gd                 # Individual cell logic and state management
│   ├── grid_manager.gd         # Grid state and game logic
│   ├── puzzle_generator.gd     # Puzzle generation algorithm
│   ├── game_controller.gd     # Main game scene controller
│   ├── game_state.gd           # Global state and save/load system
│   ├── puzzle_data.gd          # Puzzle data structure
│   └── ui/                     # UI scene controllers
│       ├── main_menu.gd
│       ├── level_select.gd
│       └── animal_select.gd
├── scenes/
│   ├── main_menu.tscn          # Main menu scene
│   ├── level_select.tscn       # Level selection screen
│   ├── animal_select.tscn      # Animal customization screen
│   ├── game.tscn              # Main game scene
│   └── cell.tscn              # Cell template for grid
├── resources/
│   └── levels/                # Hand-crafted level data (JSON)
│       ├── level_1.json      # Tutorial level
│       ├── level_2.json      # Easy levels
│       └── ...               # Up to level_10.json
├── themes/                    # UI themes (future)
└── project.godot             # Godot project configuration

🎨 Features

Core Gameplay

• Grid-based puzzle mechanics (8x8 to 10x10 grids)
• Color-coded cell blocks for visual puzzle solving
• Touch-optimized controls for mobile
• Lives system with win/lose conditions

Puzzle Generation

• Backtracking algorithm for puzzle generation
• Validates all constraints (row, column, color, adjacency)
• Difficulty scaling parameters
• Ensures solvable puzzles

Progression System

• Save/load player progress
• Level unlock system
• Animal unlock system
• Customizable animal selection

Mobile Optimization

• Portrait orientation (1080x1920 viewport)
• Responsive layout using anchors and containers
• Touch input handling
• Mobile rendering mode

🛠️ Development

Adding New Levels

1. Create a new JSON file in resources/levels/
2. Follow the level data structure:

{
  "grid_size": {"x": 8, "y": 8},
  "color_mapping": {"0,0": 0, "0,1": 0, ...},
  "animal_positions": [{"x": 0, "y": 0}, ...],
  "animal_emoji": "🦁",
  "lives": 4,
  "difficulty": "easy",
  "level_id": "level_X"
}

3. Update level count in scripts/ui/level_select.gd

Adding New Animals

1. Add animal to the animals array in scripts/ui/animal_select.gd
2. Set unlock threshold in scripts/game_controller.gd (_check_animal_unlocks)
3. Update unlock requirements

Difficulty Settings

Modify difficulty configurations in scripts/puzzle_generator.gd:

var difficulty_configs = {
    "easy": {...},
    "medium": {...},
    "hard": {...},
    "expert": {...}
}

🧪 Testing

Manual Testing Checklist

• Complete tutorial level successfully
• Test tap and double-tap responsiveness
• Verify puzzle generation creates valid puzzles
• Test lives system works correctly
• Verify win/lose conditions trigger appropriately
• Test animal unlock system
• Verify save/load functionality
• Test on actual Android device
• Verify touch controls work on mobile screen

Validation Commands

# Run the game
gdvm run

# Export for Android (in Godot Editor)
# Project → Export → Export Project

📝 Game Mechanics Details

Puzzle Constraints

Each valid puzzle must satisfy:

1. Row Constraint: Exactly one animal per row
2. Column Constraint: Exactly one animal per column
3. Color Constraint: Exactly one animal per color block
4. Adjacency Constraint: No two animals can touch (including diagonally)

Color System

• Grid cells are colored to represent regions
• Animals must be placed one per color region
• Color palette defined in scripts/cell.gd
• 8 harmonious colors for accessibility

Difficulty Progression

• Easy: 8x8 grid, 4 colors, 4 animals, 4 lives
• Medium: 9x9 grid, 5 colors, 5 animals, 3 lives
• Hard: 9x9 grid, 6 colors, 6 animals, 2 lives
• Expert: 10x10 grid, 7 colors, 7 animals, 2 lives

🎯 Future Enhancements

Potential features for future versions:

• More levels and animals
• Difficulty selection for endless mode
• Sound effects and background music
• Animated cell reveals
• Hints system
• Achievements and leaderboards
• Daily challenges
• Multiplayer puzzles

📄 License

This project is created for educational and entertainment purposes.

🙏 Credits

Built with Godot Engine 4.7.1 Inspired by the iOS game Bullpen

🐛 Known Issues

• Some ObjectDB instances leak on exit (cosmetic, doesn't affect gameplay)
• Resource warnings on exit (cosmetic, doesn't affect gameplay)

📞 Support

For issues or questions, please refer to the Godot documentation or community forums.