Add interactive text-based UI with environment visualization and decoupled architecture

README.md

@@ -3,6 +3,42 @@ This game allows you to manage a virtual environment containing entities that de
 
 <img src="pics/screenshot4.PNG" alt="screenshot" width="720"/>
 
+## UI Modes
+Apex can be run in two different modes:
+
+### Pygame GUI Mode (Default)
+The standard graphical interface with visual representation of the ecosystem.
+```bash
+python src/apex.py
+```
+
+### Text-Based Mode
+A lightweight console-based interface that visualizes the ecosystem using ASCII characters and displays simulation statistics. Features include:
+- Real-time environment visualization with colored ASCII characters
+- Non-blocking keyboard controls (same as GUI mode)
+- Interactive spawning of entities
+- Pause/resume, speed control, and debug mode
+
+```bash
+python src/apex.py --text
+```
+
+**Legend for Text Mode:**
+- `.` = Grass (green)
+- `x` = Excrement (yellow)
+- `C` = Chicken (yellow)
+- `P` = Pig (magenta)
+- `K` = Cow (cyan)
+- `W` = Wolf (red)
+- `F` = Fox (red)
+- `R` = Rabbit (white)
+
+The text mode is ideal for:
+- Running simulations on headless servers
+- Lower resource consumption
+- Remote SSH sessions
+- Automated testing and analysis
+
 ## Types of Living Entities
 - Chicken
 - Pig
@@ -19,6 +55,10 @@ If there is no grass, everything collapses.
 Living entities spawn excrement when their energy needs are met and this turns into grass over time.
 
 ## Controls
+
+### Pygame GUI Mode
+The following keyboard controls are available in **Pygame GUI Mode**:
+
 Key | Action
 ------------ | -------------
 space | pause/unpause
@@ -41,6 +81,24 @@ f11 | toggle fullscreen mode
 r | restart
 q | quit
 
+### Text-Based Mode
+The following keyboard controls are available in **Text-Based Mode**:
+
+Key | Action
+------------ | -------------
+space | pause/unpause
+d | debug mode
+c | spawn a chicken
+p | spawn a pig
+k | spawn a cow
+w | spawn a wolf
+f | spawn a fox
+b | spawn a rabbit
+l | toggle tick speed limit
+] | increase tick speed (if enabled)
+[ | decrease tick speed (if enabled)
+q | quit
+
 At this time, the user can pause/unpause, toggle the tick speed limit, increase/decrease the tick speed, manually spawn living entities, restart the simulation, enter debug mode and quit the application.
 
 ## Support

src/apex.py

@@ -1,3 +1,4 @@
+import argparse
 import pygame
 from lib.graphiklib.graphik import Graphik
 from screen.mainMenuScreen import MainMenuScreen
@@ -58,5 +59,19 @@ def __quitApplication(self):
         pygame.quit()
         quit()
 
-apex = Apex()
-apex.run()
+if __name__ == "__main__":
+    # Parse command-line arguments
+    parser = argparse.ArgumentParser(description='Apex Ecosystem Simulator')
+    parser.add_argument('--text', action='store_true', 
+                        help='Run simulation in text mode (no GUI)')
+    args = parser.parse_args()
+
+    if args.text:
+        # Run in text mode
+        from textSimulationRunner import TextSimulationRunner
+        runner = TextSimulationRunner()
+        runner.run()
+    else:
+        # Run in pygame GUI mode (default)
+        apex = Apex()
+        apex.run()

src/simulation/simulation.py

@@ -27,10 +27,13 @@
 # @since July 26th, 2022
 class Simulation:
     # constructors ------------------------------------------------------------
-    def __init__(self, name, config, gameDisplay):
+    def __init__(self, name, config, gameDisplay, soundService=None):
         self.__config = config
         self.__gameDisplay = gameDisplay
-        self.__soundService = SoundService()
+        if soundService is None:
+            self.__soundService = SoundService()
+        else:
+            self.__soundService = soundService
 
         self.environment = Environment(name, self.getConfig().gridSize)