Add PICO-8 emulator support with femto8 integration

Co-authored-by: waemfinger <waemfinger@gmail.com>

Author: cursoragent

IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,219 @@
+# PICO-8 Emulator Implementation Summary
+
+This document summarizes the proposed implementation for adding PICO-8 emulator support to esp-box-emu.
+
+## Files Created
+
+### 1. Core Documentation
+- **`PICO8_PR_PROPOSAL.md`** - Comprehensive PR proposal with implementation plan
+- **`IMPLEMENTATION_SUMMARY.md`** - This summary document
+
+### 2. Component Structure
+- **`components/pico8/CMakeLists.txt`** - Build configuration for PICO-8 component
+- **`components/pico8/include/pico8.hpp`** - C++ API wrapper for femto8 emulator
+- **`components/pico8/src/pico8.cpp`** - Implementation of the API wrapper
+- **`components/pico8/README.md`** - Component documentation
+
+### 3. Integration Files
+- **`main/pico8_cart.hpp`** - Cart class implementation for PICO-8
+- **`main/carts_integration_example.hpp`** - Integration points for main cart system
+
+## Implementation Roadmap
+
+### Phase 1: Foundation (Week 1)
+1. **Set up femto8 submodule**
+   ```bash
+   cd components/pico8
+   git submodule add https://github.com/benbaker76/femto8.git
+   ```
+
+2. **Create basic component structure**
+   - Copy the created files to the appropriate locations
+   - Set up build configuration
+   - Test compilation without functionality
+
+3. **Implement basic Pico8Cart class**
+   - Basic initialization and cleanup
+   - Placeholder implementations for required methods
+   - Integration with cart system
+
+### Phase 2: Core Functionality (Week 2)
+1. **Video integration**
+   - Implement video buffer management
+   - Add palette conversion for ESP32 display
+   - Test basic video output
+
+2. **Input system**
+   - Map gamepad controls to PICO-8 inputs
+   - Test input responsiveness
+   - Handle button state management
+
+3. **Audio integration**
+   - Connect PICO-8 audio synthesis to ESP32 audio pipeline
+   - Implement audio buffer management
+   - Test audio output quality
+
+### Phase 3: Advanced Features (Week 3)
+1. **Save state system**
+   - Implement save/load functionality
+   - Integrate with existing save system
+   - Test save state reliability
+
+2. **Menu integration**
+   - Add PICO-8 to emulator selection
+   - Implement cartridge metadata parsing
+   - Add PICO-8-specific settings
+
+3. **Performance optimization**
+   - Profile memory usage
+   - Optimize frame rate
+   - Test with various cartridges
+
+## Key Integration Points
+
+### 1. Cart System Changes
+Add to `main/carts.hpp`:
+```cpp
+#if defined(ENABLE_PICO8)
+#include "pico8_cart.hpp"
+#endif
+```
+
+Add to `cart.hpp` enum:
+```cpp
+enum class Emulator {
+  // ... existing emulators ...
+  PICO8,
+};
+```
+
+### 2. File Extension Support
+Add to extension mapping:
+```cpp
+if (extension == ".p8") return Emulator::PICO8;
+```
+
+### 3. Build System Integration
+Add to `main/CMakeLists.txt`:
+```cmake
+if(CONFIG_ENABLE_PICO8)
+  list(APPEND COMPONENT_REQUIRES pico8)
+endif()
+```
+
+### 4. Configuration Option
+Add to Kconfig:
+```kconfig
+config ENABLE_PICO8
+    bool "Enable PICO-8 emulator"
+    default y
+```
+
+## Technical Specifications
+
+### Memory Usage
+- **Emulator Core**: ~50KB
+- **Video Buffer**: 16KB (128×128 pixels)
+- **Cartridge Data**: Up to 32KB
+- **Audio Buffers**: ~8KB
+- **Total Additional**: ~106KB
+
+### Performance Targets
+- **Frame Rate**: 60 FPS on ESP32-S3
+- **Audio Latency**: <20ms
+- **Boot Time**: <2 seconds
+- **Memory Efficiency**: <110KB total overhead
+
+### Compatibility
+- **Hardware**: All existing esp-box-emu hardware
+- **Controls**: Standard gamepad layout
+- **Display**: All supported display configurations
+- **Audio**: Existing audio pipeline
+
+## Testing Strategy
+
+### Unit Tests
+1. **Component Loading**: Test PICO-8 component initialization
+2. **Cartridge Parsing**: Test .p8 file loading
+3. **Video Output**: Test framebuffer generation
+4. **Audio Output**: Test audio synthesis
+5. **Input Handling**: Test button mapping
+
+### Integration Tests
+1. **Menu Integration**: Test PICO-8 appears in emulator selection
+2. **Save States**: Test save/load functionality
+3. **Video Scaling**: Test all scaling modes
+4. **Performance**: Test frame rate consistency
+
+### Game Tests
+1. **Simple Games**: Test basic PICO-8 functionality
+2. **Complex Games**: Test advanced features
+3. **Audio Games**: Test music and sound effects
+4. **Long Sessions**: Test memory stability
+
+## Dependencies
+
+### External
+- **femto8**: PICO-8 emulator core (MIT license)
+- **Lua**: Embedded in femto8 for cartridge execution
+
+### Internal
+- **box-emu**: Core emulation framework
+- **statistics**: Performance monitoring
+- **shared_memory**: Memory management
+- **espp**: ESP32 utilities
+
+## Potential Challenges & Solutions
+
+### 1. Memory Constraints
+**Challenge**: Lua interpreter memory usage
+**Solution**: Use femto8's embedded optimizations, limit heap size
+
+### 2. Audio Synthesis
+**Challenge**: PICO-8's unique 4-channel synthesis
+**Solution**: Leverage existing audio pipeline, optimize for ESP32
+
+### 3. Cartridge Format
+**Challenge**: PICO-8's complex cartridge structure
+**Solution**: Use femto8's proven cartridge parser
+
+### 4. Performance
+**Challenge**: Maintaining 60 FPS on ESP32-S3
+**Solution**: Profile and optimize critical paths, use PSRAM efficiently
+
+## Success Metrics
+
+### Functionality
+- [ ] Loads and runs PICO-8 cartridges
+- [ ] Maintains 60 FPS performance
+- [ ] Audio works correctly
+- [ ] Save states function properly
+- [ ] Integrates seamlessly with existing UI
+
+### Quality
+- [ ] Memory usage stays within bounds
+- [ ] No crashes or stability issues
+- [ ] Responsive input handling
+- [ ] Good video quality at all scaling modes
+
+### User Experience
+- [ ] Easy to use (follows existing patterns)
+- [ ] Good game compatibility
+- [ ] Fast loading times
+- [ ] Intuitive controls
+
+## Next Steps
+
+1. **Review and approve** this implementation plan
+2. **Set up development environment** with femto8 integration
+3. **Create initial working prototype** with basic functionality
+4. **Iterate based on testing** and performance requirements
+5. **Submit PR** with complete implementation
+
+## Conclusion
+
+This implementation plan provides a comprehensive roadmap for adding PICO-8 emulator support to esp-box-emu. The approach follows established patterns in the codebase, uses a proven emulator core (femto8), and is designed to work within the ESP32's resource constraints.
+
+The modular design ensures that the PICO-8 emulator can be easily enabled/disabled, and the implementation is compatible with all existing hardware configurations. The estimated memory overhead (~106KB) is well within the ESP32-S3's capabilities, and the performance targets are achievable with proper optimization.
+
+The three-phase implementation plan provides a structured approach to development, with clear milestones and testing criteria. This should result in a high-quality PICO-8 emulator that seamlessly integrates with the existing esp-box-emu ecosystem.