initial game template

README.md

@@ -1,9 +1,10 @@
 # RP2350 TFT Display with Touch and SD Card Demo
 
-A modular embedded application for RP2350 microcontrollers featuring display, touch, and SD card support with hardware abstraction layers.
+A modular embedded application for RP2350 microcontrollers featuring display, touch, and SD card support with hardware abstraction layers. **Now includes a reactive game template architecture!**
 
 ## Features
 
+- **Reactive Game Template** - Event-driven architecture optimized for e-ink displays and power efficiency
 - **Display Abstraction Layer** - Support for multiple display types (ST7796, ST7789, E-Paper)
 - **Touch Abstraction Layer** - Extensible touch controller support (FT6336U)
 - **SD Card with FatFS** - File system support with board-aware initialization
@@ -12,6 +13,75 @@ A modular embedded application for RP2350 microcontrollers featuring display, to
 - **Automated Build Scripts** - Build for one board or all boards with single commands
 - **Hardware Abstraction** - Factory pattern for displays and touch controllers
 
+## 🎮 Reactive Game Template
+
+The project now uses a **clean, event-driven architecture** perfect for building games and interactive applications:
+
+### Key Features
+- ⚡ **Event-Driven**: Display only updates when input is received
+- 🔋 **Power Efficient**: Uses `__wfi()` to sleep between inputs (< 1mA idle)
+- 📄 **E-ink Optimized**: Minimizes screen refreshes for e-paper displays
+- 🎯 **Interrupt-Driven**: Touch and button handling via hardware interrupts
+- 🧩 **Modular**: Clear separation of input processing, game logic, and rendering
+
+### Architecture Highlights
+
+```
+Interrupt → Set Flag → Wake CPU → Process Input → Update Game → Draw → Refresh → Sleep
+```
+
+**Before (Polling Loop):**
+```cpp
+while(1) {
+    if (touch_interrupt_flag) {
+        // Read touch data
+        // Process coordinates
+        // Draw directly
+        // Handle gestures inline
+        refresh_screen();
+    }
+}
+```
+
+**After (Reactive Template):**
+```cpp
+while(1) {
+    __wfi();  // Sleep until interrupt
+    
+    InputEvent input = process_button_input(config);
+    if (!input.valid) {
+        input = process_touch_input(config, &last_touch_time);
+    }
+    
+    if (input.valid && game_update(&game_state, input, config, &renderer)) {
+        game_draw(&game_state, &renderer, &gui);
+        refresh_screen(bit_buffer, display);
+    }
+}
+```
+
+### Creating Your Own Game
+
+1. **Modify GameState** - Define your game variables
+2. **Implement game_init()** - Set initial values
+3. **Implement game_update()** - Handle input and update state
+4. **Implement game_draw()** - Render your game graphics
+
+The reactive loop and input system work automatically!
+
+**📖 [Read the Full Template Usage Guide](TEMPLATE_USAGE.md)** for detailed examples and patterns.
+
+### Example Game (Included)
+
+The template includes a **Button Navigation Game** demonstrating:
+- Hardware button input handling (KEY0 switches focus, KEY1 clicks)
+- GUI component usage (buttons, radio buttons, status bars)
+- State management (click counters, focus tracking)
+- Visual feedback (filled buttons show focus)
+- E-ink optimized refreshes
+
+Perfect starting point for your own game!
+
 ## Supported Hardware Configurations
 
 ### Available Board Configurations