Add RLCD animations and screensavers

screensavers/README.md

@@ -0,0 +1,48 @@
+# Retro Video Game Screensavers for Reyna little32 ESP32-S3
+
+A collection of 5 standalone, retro-game-inspired MicroPython screensavers designed for high-contrast, low-resolution reflective LCD screens (specifically the Waveshare ESP32-S3-RLCD-4.2).
+
+## Screensavers List
+
+1.  **Maze Chomper (`maze_chomper.py`)**
+    *   **Inspired By:** *maze-chase arcade classic*
+    *   **Description:** A wedge-shaped mouth chomps its way through a symmetric maze grid of dots. A ghost follows and chases the chomper. If the ghost catches the chomper, a collision is registered, and the board resets.
+2.  **Block Puzzle (`block_puzzle.py`)**
+    *   **Inspired By:** *falling-block puzzle classic*
+    *   **Description:** Tetromino pieces fall from the top of the board. A simple self-playing heuristic automatically shifts and rotates each piece to target a column. When a horizontal row is fully occupied, it is cleared. The game resets once blocks reach the ceiling.
+3.  **Alien Invaders (`alien_invaders.py`)**
+    *   **Inspired By:** *alien-wave shooter classic*
+    *   **Description:** Crawling leg-animated invaders march side-to-side and descend down the screen. An automated defender ship moves underneath to aim and destroy invaders. Both invaders and ship shoot bullets/bombs, causing pixel-spark explosions.
+4.  **Asteroid Drift (`asteroid_drift.py`)**
+    *   **Inspired By:** *vector-rock space classic*
+    *   **Description:** A wireframe, vector-style ship sits in the center of the screen, automatically aiming its nose towards the closest drifting space rock. The ship fires lasers to blow up and split larger rocks into medium and small fragments.
+5.  **Paddle Bounce (`paddle_bounce.py`)**
+    *   **Inspired By:** *paddle-ball arcade classic*
+    *   **Description:** Two vertical paddles play tennis against each other. The ball bounces off the top/bottom boundaries and the paddles, increasing speed with each paddle contact. Simulated reaction times and position offsets introduce realistic mistakes, allowing scores to accrue.
+
+## How It Works
+
+*   **Standalone Execution:** Each script is designed to run completely standalone and can be executed via REPL or boot routines.
+*   **Hardware Fallback:** If `board_config` or `display_instance` is not available (such as running under test environments or without initialized hardware), the script gracefully prints a warning message and exits without throwing a crash exception.
+*   **Touch Stop Detection:** Every script contains a robust `check_touch` function that intercepts touch interrupts/coordinates across various formats (`board_config.touch_instance`, `board_config.touch`, `display.get_touch()`, or `display.touch()`). If a touch is registered, the loop terminates immediately.
+*   **Frame Control:** Every script exposes a `run(text="", frames=None)` function. If `frames` is set to `1` (useful for syntax checks or single-frame rendering), the screensaver renders exactly one frame and exits. If `frames` is `None` or `<=0`, it runs indefinitely.
+
+## Example Execution Commands
+
+Upload the desired screensaver to your board using `mpremote`:
+```bash
+mpremote connect /dev/cu.usbmodem101 cp screensavers/maze_chomper.py :
+```
+
+Run the screensaver directly from the MicroPython REPL:
+```python
+# Execute the entire file to run automatically
+exec(open("maze_chomper.py").read())
+```
+
+Or import the module and invoke with custom parameters:
+```python
+# Import and run with frame limits (e.g. exit after 300 frames)
+import maze_chomper
+maze_chomper.run(text="BREAKROOM SCREEN", frames=300)
+```