Python Combat Engine (Turn-Based) ⚔️

English | Español

English Version

This project is a turn-based combat engine developed in Python. It is designed under a Data-Driven architecture, meaning the combat system is completely independent of the characters; the fighting mechanics adapt dynamically based on the statistics and skills defined in the data. 🛠️ Technical Features

Modular Architecture: Clear separation between the engine logic, character entities, and the graphical user interface (GUI).

Dynamic Resource System: Energy system management that validates the cost of each action in real-time.

Advanced Combat Mechanics: * crit_chance (Critical hit chance) and evasion (Dodge/Evasion) probabilities.

    Damage reduction through armor (Armor/Defense).

    Temporary states like protection (Shields).

Graphical User Interface (Tkinter): Implementation of a native window that manages the combat log and user interaction without blocking the main thread.

Persistent Game Loop: Rematch system that allows restarting the game state by reusing the same interface instance.

🏗️ Project Structure

character.py: Base class for fighters. Manages their properties and action logic.

combat_engine.py: Flow controller. Manages turns, attacker/defender alternation, and victory conditions.

ui_manager.py: Visual abstraction layer. Centralizes text rendering and input capture via Tkinter.

energy.py: Independent component for resource management (Energy/Mana).

stats.py: Configuration file where character attributes and skills are defined.

🚀 Scalability

The system is prepared for easy expansion:

New Entities: New characters can be added to the stats.py dictionary without modifying a single line of engine code.

New Mechanics: The attack method is extensible to support status effects (poison, stun, etc.).

Interface: By using a decoupled UiManager, Tkinter could be replaced by Pygame or a Web API with minimal changes to the core engine.

🧠 Key Learnings

During the development of this engine, specific software architecture challenges were solved:

Dependency Injection: The UiManager instance is passed to combat methods. This allows character logic to remain interface-agnostic while "reporting" events to the window cleanly.

GUI Memory Management: Solved the multiple-window issue by using a Shared Instance, ensuring the game loop stays within a single Tkinter process.

Data-Driven Design: The separation of stats (statistics) from the engine allows the system to scale to any theme (fantasy, sci-fi, etc.) without touching the source code.

Versión en Español

Este proyecto es un motor de combate por turnos desarrollado en Python. Está diseñado bajo una arquitectura Data-Driven, lo que significa que el sistema de combate es totalmente independiente de los personajes; las mecánicas de pelea se adaptan dinámicamente según las estadísticas y habilidades definidas en los datos. 🛠️ Características Técnicas

Arquitectura Modular: Separación clara entre la logica del motor, las entidades de personajes y la interfaz gráfica.

Sistema de Recursos Dinámico: Gestión de sistema de energía que valida el costo de cada acción en tiempo real.

Mecánicas de Combate Avanzadas: - Probabilidades de crítico y evasion (evasión/esquive).

    Reducción de daño mediante armadura.

    Estados temporales como la protección/escudo.

Interfaz Gráfica (Tkinter): Implementación de una ventana nativa que gestiona el log de combate y la interacción del usuario sin bloquear el hilo principal.

Game Loop Persistente: Sistema de revanchas que permite reiniciar el estado del juego reutilizando la misma instancia de la interfaz.

🏗️ Estructura del Proyecto

character.py: Clase base de los luchadores. Maneja sus propiedades y la lógica de sus acciones.

combat_engine.py: Controlador de flujo. Gestiona los turnos, la alternancia entre atacante/defensor y las condiciones de victoria.

ui_manager.py: Capa de abstracción visual. Centraliza el renderizado de texto y la captura de inputs mediante Tkinter.

energy.py: Componente independiente para la gestión de recursos (energía/maná).

stats.py: Archivo de configuración donde se definen los atributos y habilidades de los luchadores.

🚀 Escalabilidad

El sistema está preparado para crecer fácilmente:

Nuevas Entidades: Se pueden añadir nuevos personajes al diccionario de stats.py sin tocar una sola línea de código del motor.

Nuevas Mecánicas: El método attack es extensible para soportar efectos de estado (veneno, aturdimiento, etc.).

Interfaz: Al usar un UiManager desacoplado, se podría reemplazar Tkinter por Pygame o una API web con cambios mínimos en el motor.

🧠 Aprendizajes Clave

Durante el desarrollo de este motor, se resolvieron retos específicos de arquitectura de software:

• Inyección de Dependencias: Se implementó el paso de la instancia de UiManager a los métodos de combate. Esto permite que la lógica del personaje sea agnóstica a la interfaz y pueda "reportar" eventos a la ventana de forma limpia.
• Gestión de Memoria en GUI: Se solucionó el problema de múltiples ventanas mediante el uso de una instancia compartida, asegurando que el bucle de juego se mantenga dentro de un único proceso de Tkinter.
• Data-Driven Design: La separación de las estadísticas del motor permite que el sistema sea escalable a cualquier temática (fantasía, sci-fi, etc.) sin modificar el código fuente.