Sokoban Python

A classic Sokoban puzzle game implemented in Python using the gamelib framework. Push boxes to their designated spots to complete each level!

🎮 Game Description

Sokoban is a classic puzzle game where the player controls a warehouse worker who must push boxes to their designated storage locations. The challenge lies in planning your moves carefully, as boxes can only be pushed (not pulled) and you can't push multiple boxes at once.

🚀 Features

• 155 Levels: Complete collection of challenging Sokoban puzzles
• Intuitive Controls: Use arrow keys or WASD to move
• Visual Graphics: Clean, pixel-perfect graphics with GIF animations
• Level Progression: Automatic advancement to next level upon completion
• Restart Functionality: Reset current level at any time
• Cross-Platform: Works on Windows, macOS, and Linux

📋 Requirements

• Python 3.6 or higher
• tkinter (usually included with Python)
• No additional dependencies required!

🛠️ Installation

1. Clone the repository:

   git clone https://github.com/yourusername/sokoban-python.git
   cd sokoban-python

2. Run the game:

   python main.py

That's it! No additional installation steps required.

🎯 How to Play

Controls

Key	Action
↑ or W	Move Up
↓ or S	Move Down
← or A	Move Left
→ or D	Move Right
R	Restart Current Level
Esc	Exit Game

Game Elements

• @ - Player (you)
• $ - Box
• . - Goal (where boxes need to go)
• * - Box on Goal
• + - Player on Goal
• # - Wall

Objective

Push all boxes ($) onto the goal positions (.) to complete each level. Once all boxes are on goals, you'll automatically advance to the next level.

📁 Project Structure

sokoban-python/
├── main.py          # Main game logic and entry point
├── soko.py          # Core game mechanics and rules
├── gamelib.py       # Game framework (included)
├── niveles.txt      # Level definitions (155 levels)
├── teclas.txt       # Key mappings configuration
├── img/             # Game graphics
│   ├── box.gif
│   ├── goal.gif
│   ├── goal_with_box.gif
│   ├── goal_with_player.gif
│   ├── ground.gif
│   ├── player.gif
│   └── wall.gif
└── README.md        # This file

🎮 Gameplay Tips

1. Plan Ahead: Look at the entire level before making moves
2. Avoid Dead Ends: Don't push boxes into corners unless they're goals
3. Use Walls: Walls can help you position boxes correctly
4. Take Your Time: There's no time limit, so think through each move
5. Use Restart: Press R to restart if you get stuck

🔧 Technical Details

Architecture

• main.py: Handles game initialization, level loading, input processing, and rendering
• soko.py: Contains core game logic including movement rules and win conditions
• gamelib.py: Lightweight game framework providing graphics and input handling

Level Format

Levels are defined in niveles.txt using a simple text format:

• # represents walls
• @ represents the player
• $ represents boxes
• . represents goals
• * represents boxes on goals
• + represents player on goals

🤝 Contributing

Contributions are welcome! Here are some ways you can help:

1. Report Bugs: Found a bug? Open an issue!
2. Suggest Features: Have an idea? Let us know!
3. Add Levels: Create new challenging levels
4. Improve Graphics: Enhance the visual experience
5. Code Improvements: Optimize performance or add features

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Commit with a clear message: git commit -m "Add feature: description"
6. Push to your branch: git push origin feature-name
7. Open a Pull Request

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Gamelib Framework: Thanks to the gamelib developers for the excellent educational game framework
• Sokoban Community: Inspired by the classic Sokoban puzzles and community
• Level Designers: Credit to all the level designers who created these challenging puzzles

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include your operating system and Python version

🎯 Roadmap

• Level editor
• Save/load game progress
• Sound effects and music
• High score system
• Mobile version
• Multiplayer mode

---

Enjoy playing Sokoban! 🎮

Push those boxes and solve the puzzles!