🏗️ Arquitectura del Juego 🏗️ Game Architecture

Visión General de la Arquitectura Architecture Overview

El juego sigue una arquitectura modular basada en managers que separa las responsabilidades y promueve la mantenibilidad. El sistema está construido alrededor del concepto de managers especializados que manejan diferentes aspectos del juego. The game follows a modular manager-based architecture that separates responsibilities and promotes maintainability. The system is built around the concept of specialized managers that handle different aspects of the game.

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Game Manager  │────│  State Manager  │────│ Tutorial Manager│
│   (Coordinador) │    │   (Flujo Juego) │    │   (Aprendizaje) │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Entity Manager  │    │Collision Manager│    │   UI Manager    │
│   (Entidades)   │    │    (Física)     │    │  (Interfaz)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Level Manager  │    │ Firebase Manager│    │  Sound Manager  │
│    (Niveles)    │    │  (Datos Nube)   │    │     (Audio)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Componentes Principales Main Components

1. Game Manager (src/game/game_manager.py) 1. Game Manager (src/game/game_manager.py)

Propósito: Coordinador central que orquesta todos los sistemas del juego. Purpose: Central coordinator that orchestrates all game systems.

Responsabilidades: Responsibilities:

• Ejecución del bucle principal del juego Main game loop execution
• Coordinación de managers Manager coordination
• Delegación del manejo de eventos Event handling delegation
• Coordinación del renderizado Rendering coordination

def run(self):
    """Bucle principal del juego""""""Main game loop"""
    while self.running:
        self.handle_events()
        self.update()
        self.render()
        self.clock.tick(self.config.FPS)

def handle_events(self):
    """Delega eventos a los managers apropiados""""""Delegates events to appropriate managers"""
    
def update(self):
    """Actualiza todos los sistemas del juego""""""Updates all game systems"""
    
def render(self):
    """Renderiza todos los elementos visuales""""""Renders all visual elements"""

2. Entity Manager (src/managers/entity_manager.py) 2. Entity Manager (src/managers/entity_manager.py)

Propósito: Gestiona todas las entidades del juego (jugador, enemigos, coleccionables, proyectiles). Purpose: Manages all game entities (player, enemies, collectibles, projectiles).

Responsabilidades: Responsibilities:

• Gestión del ciclo de vida de entidades Entity lifecycle management
• Control de spawn y timing Spawn control and timing
• Actualizaciones e interacciones de entidades Entity updates and interactions
• Coordinación del renderizado Rendering coordination

class EntityManager:
    def __init__(self, config):
        self.player = None
        self.enemies = []
        self.collectibles = []
        self.projectiles = []
        
        # Control de spawn# Spawn control
        self.spawn_timer = 0
        self.monster_spawn_timer = 0
        self.monsters_spawned = 0

3. Game State Manager (src/managers/game_state_manager.py) 3. Game State Manager (src/managers/game_state_manager.py)

Propósito: Gestiona los estados del juego y las transiciones. Purpose: Manages game states and transitions.

Estados: States:

• MENU - Menú principal MENU - Main menu
• TUTORIAL - Modo tutorial TUTORIAL - Tutorial mode
• PLAYING - Gameplay activo PLAYING - Active gameplay
• PAUSED - Juego pausado PAUSED - Game paused
• SHOP - Tienda del juego SHOP - Game shop
• GAME_OVER - Pantalla de game over GAME_OVER - Game over screen
• LEVEL_COMPLETE - Completar nivel LEVEL_COMPLETE - Level complete

def set_state(self, new_state):
    """Transición segura de estado con validación""""""Safe state transition with validation"""
    
def is_playing(self):
    """Verifica si está en estados de gameplay activo""""""Checks if in active gameplay states"""
    return self.state in ["PLAYING", "TUTORIAL"]

Sistema de Entidades Entity System

Jerarquía de Entidades Entity Hierarchy

Entity (Base)
├── Player
│   ├── Sistema de Movimiento
│   ├── Sistema de Animación
│   └── Sistema de Inventario
├── Enemy
│   ├── Barrel (Dirigido por IA)
│   └── Monster (Máquina de estados)
├── Collectible
│   └── Star (Valores de puntos: 10, 20, 50)
└── Projectile
    └── Banana (Explosivo)Entity (Base)
├── Player
│   ├── Movement System
│   ├── Animation System
│   └── Inventory System
├── Enemy
│   ├── Barrel (AI-driven)
│   └── Monster (State machine)
├── Collectible
│   └── Star (Point values: 10, 20, 50)
└── Projectile
    └── Banana (Explosive)

Sistema del Jugador (src/entities/player.py) Player System (src/entities/player.py)

Características: Features:

• Animación basada en sprites (12 frames para secuencia de salto) Sprite-based animation (12 frames for jump sequence)
• Movimiento basado en física Physics-based movement
• Gestión de inventario (bananas, vidas, puntuación) Inventory management (bananas, lives, score)
• Manejo de entrada Input handling

def update_animation(self):
    """Maneja la animación de sprites basada en el estado""""""Handles sprite animation based on state"""
    if not self.on_ground and self.sprites['jump']:
        # Reproduce secuencia de animación de salto# Play jump animation sequence
        if not self.is_jumping_animation:
            self.is_jumping_animation = True
            self.jump_frame = 0

Arquitectura de IA AI Architecture

Sistema de IA Híbrido Hybrid AI System

El juego implementa un sofisticado sistema de IA que combina múltiples enfoques: The game implements a sophisticated AI system that combines multiple approaches:

1. Capa de Decisión Primaria: Lógica basada en reglas para comportamiento confiable Primary Decision Layer: Rule-based logic for reliable behavior
2. Capa de Validación: Q-Learning para refinamiento de comportamiento Validation Layer: Q-Learning for behavior refinement
3. Capa de Seguridad: Mecanismos anti-atasco y de respaldo Safety Layer: Anti-stuck and fallback mechanisms

def barrel_movement(self, platforms, player_rect=None):
    # 1. Decisión primaria basada en reglas# 1. Primary rule-based decision
    primary_action = self.decide_primary_action(dx, dy, current_platform, player_platform)
    
    # 2. Validación Q-Learning# 2. Q-Learning validation
    if hasattr(self, 'ai_agent'):
        q_action = self.ai_agent.choose_action(state)
        if self.should_override_action(primary_action, q_action, dx, dy):
            primary_action = q_action
    
    # 3. Ejecutar decisión# 3. Execute decision
    self.execute_action_decision(primary_action, current_platform, dx)

Gestión de Datos Data Management

Integración con Firebase (src/managers/firebase_manager.py) Firebase Integration (src/managers/firebase_manager.py)

Servicios Utilizados: Services Used:

• Realtime Database: Leaderboards y guardados en la nube Realtime Database: Leaderboards and cloud saves
• Authentication: Gestión de usuarios Authentication: User management
• REST API: Comunicación HTTP directa (sin SDK) REST API: Direct HTTP communication (no SDK)

Conclusión Conclusion

Esta arquitectura proporciona una base sólida para un juego mantenible, extensible y de alto rendimiento, manteniendo una separación limpia de responsabilidades y un manejo robusto de errores. El patrón de managers permite una fácil extensión y modificación de funcionalidades sin afectar otros sistemas. This architecture provides a solid foundation for a maintainable, extensible, and high-performance game, maintaining clean separation of concerns and robust error handling. The manager pattern allows for easy extension and modification of functionality without affecting other systems.