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

[Copilot]

Plan: Add Text-Based UI Option

• Explore repository structure and understand current pygame-based UI
• Run existing tests to verify baseline functionality (50 tests passing)
• Add command-line argument parsing to apex.py for UI mode selection
• Create a new TextSimulationRunner class that runs simulations without pygame
• Modify apex.py entry point to support both pygame and text modes
• Add text-based display of simulation stats to console
• Modify Simulation to accept optional soundService parameter for text mode
• Test the text-based UI manually (working correctly)
• Ensure existing tests still pass (all 50 tests passing)
• Document the new text-based UI option in README
• Add environment visualization using ASCII characters with curses
• Implement non-blocking keyboard controls for interactive terminal use
• Update README with control legend and text mode features
• Create SimulationController to abstract gameplay logic from UI
• Refactor both pygame and text UIs to use SimulationController
• Add comprehensive tests for SimulationController (9 new tests)
• Verify all 59 tests pass
• Fix text visualization bug (AttributeError on self.debug)
• Fix excessive screen refresh causing text to jump around
• Capture entity behavior logs to prevent game board from being pushed off screen

All tasks completed! Logs now display as a single "Event:" line in the stats area.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Provide text-based UI option</issue_title>
<issue_description>Users should have the option of using a text-based UI instead of the standard pygame UI.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #110

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[dmccoystephenson]

@copilot that's great, but the enrollment should be visualized and a non blocking terminal should be used to allow key commands. See Preponderous-Software/ophidian#95

[Copilot]

@copilot that's great, but the enrollment should be visualized and a non blocking terminal should be used to allow key commands. See Preponderous-Software/ophidian#95

Done! Commit 1bec9e5 adds:

Environment Visualization:

• ASCII art display of the entire ecosystem grid
• Each entity type has a unique character (C=Chicken, P=Pig, K=Cow, W=Wolf, F=Fox, R=Rabbit, .=Grass, x=Excrement)
• Color-coded entities in compatible terminals

Non-blocking Terminal Controls:

• Uses Python's curses library for immediate keyboard input
• All interactive controls work without pressing Enter
• Same controls as GUI mode: SPACE (pause), d (debug), c/p/k/w/f/b (spawn entities), [/] (speed control), q (quit)

Visual Layout:

[ASCII Grid Visualization of Ecosystem]

Tick: 1523  Living: 42  Total: 1245
Grass: 1156  Excrement: 47
C:8 P:6 K:4 W:12 F:5 R:7

q:Quit SPACE:Pause d:Debug [/]:Speed c/p/k/w/f/b:Spawn

The implementation now provides a fully interactive terminal experience similar to the referenced ophidian-prototype PR.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/Preponderous-Software/ophidian-prototype/pulls/95
  • Triggering command: curl -s REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[dmccoystephenson]

@copilot Great job, now ensure the user interface is abstracted sufficiently and decoupled sufficiently from the gameplay that it will be easy to support both with minimal changes when modifying just gameplay.

[Copilot]

@copilot Great job, now ensure the user interface is abstracted sufficiently and decoupled sufficiently from the gameplay that it will be easy to support both with minimal changes when modifying just ...

Done! Commit f2d395c introduces SimulationController to abstract gameplay logic from UI implementation.

Key Improvements:

1. Single Source of Truth: All gameplay actions (spawning entities, pause/resume, speed control) are now centralized in SimulationController

2. No Code Duplication: Both pygame and text UIs use the same controller methods instead of duplicating entity spawning and state management logic

3. Easy Maintenance: Future gameplay changes only require modifications in SimulationController, not in both UIs

4. Better Testing: Added 9 comprehensive tests for the controller (59 total tests passing)

Architecture:

TextSimulationRunner ──┐
                        ├──> SimulationController ──> Simulation
SimulationScreen ──────┘

Both UIs now call controller methods like spawnChicken(), togglePause(), update() instead of directly manipulating the simulation. This ensures future UI additions or gameplay modifications can be made independently with minimal changes.

[dmccoystephenson]

@copilot the text visualization of the environment appears to be broken, I no longer see it when running the program

[Copilot]

@copilot the text visualization of the environment appears to be broken, I no longer see it when running the program

Fixed in commit 3dc9910. The issue was a reference to self.debug on line 212 that was missed during the controller refactoring.

The Bug:

statsHeight = 12 if self.debug else 8  # AttributeError - self.debug doesn't exist

The Fix:

statsHeight = 12 if self.controller.isDebug() else 8  # Now uses controller

The AttributeError was being silently caught in the exception handler (line 240), causing the entire _draw_screen() method to fail silently without any output. Text visualization now works correctly with all 59 tests passing.

[dmccoystephenson]

@copilot the screen appears to be refreshing far too often and it is difficult to play because text jumps around instead of remaining stable

[Copilot]

@copilot the screen appears to be refreshing far too often and it is difficult to play because text jumps around instead of remaining stable

Fixed in commit 9e4311e. The screen was refreshing on every simulation tick (30-60 times per second), causing excessive flickering.

Changes:

1. Rate Limiting: Screen now refreshes at max 10 FPS instead of every tick

   if currentTime - self.lastDrawTime >= 0.1:  # 10 Hz refresh
       self._draw_screen()

2. Smart Clearing: Screen only clears when necessary (pause/debug toggle), not on every frame

3. Stable Display: Text now remains stable while simulation runs at full speed internally

The simulation still processes at high speed, but the visual display updates at a comfortable 10 FPS rate, providing a stable viewing experience without text jumping.

[dmccoystephenson]

@copilot logs regarding entity behavior are pushing the game board off the screen. These should be rendered in a non conflicting way or only the latest message should be displayed.

[Copilot]

@copilot logs regarding entity behavior are pushing the game board off the screen. These should be rendered in a non conflicting way or only the latest message should be displayed.

Fixed in commit 9cccb9f. Entity behavior logs (deaths/reproductions) were using print() statements that disrupted the curses display.

Solution:

1. Stdout Redirection: TextSimulationRunner now captures print() statements by implementing write() and flush() methods

   sys.stdout = self  # Redirect during curses session

2. Display Latest Event: Only the most recent message is stored and displayed in the stats area:

   Event: Pig has reproduced with Pig at ( 23 , 14 ).
   

3. Clean Layout: Game board remains stable, with the latest event shown below entity counts without pushing anything off screen

The logs are now captured instead of written directly to stdout, preventing terminal scrolling while keeping users informed of important events.