Gamepad-Controlled Carousel Image Gallery

Overview

This project is a single-file HTML application demonstrating a gamepad-focused interface for an image gallery carousel. It emphasizes controller-only interaction, with no keyboard or mouse support, to showcase immersive, console-like web experiences. Built with vanilla HTML, CSS, and JavaScript, it uses the Gamepad API for input, localStorage for image persistence (as data URLs), and haptic feedback for navigation. Ideal for prototyping gamepad web apps or accessible interfaces.

The core file is index.html, which embeds all styles and scripts—no external dependencies required.

Features

• Splash Screen: Starts with a welcome prompt; enter gallery via gamepad button press.
• Linear Carousel Navigation: Browse images left/right with gamepad stick; no wrap-around for a bounded experience.
• Vibration Feedback: Short "bump" haptic response on image changes (browser-compatible).
• Image Upload: Add images via file picker triggered by gamepad button; stored as data URLs in localStorage.
• Persistence: Images persist across sessions/reloads (browser-dependent; no server or file system access).
• Clear Storage: Reset images with a dedicated button.
• Debug Mode: Toggle on-screen info about storage limitations (e.g., no /images folder due to browser security).
• Centered Layout: Full-viewport centering for a game-like presentation.
• Gamepad-Only Design: All actions via standard controller mappings (e.g., Xbox/PS layouts).

Requirements

• Modern browser with Gamepad API support (e.g., Chrome, Edge; Firefox partial for haptics).
• Connected gamepad (e.g., Xbox, PlayStation, or compatible USB controller).
• LocalStorage enabled (not in incognito mode or restricted environments).
• Run locally or via a simple server (e.g., python -m http.server) to avoid file:// restrictions.

No installation needed—open index.html in a browser.

How to Use

1. Connect Gamepad: Plug in or pair your controller; the app detects it automatically.
2. Start from Splash: Press A (button 0) to enter the gallery.
3. Navigate: Use left stick X-axis (left/right) to switch images; vibrates on change.
4. Upload Images: Press A to open file picker; select images (multiple OK).
5. Clear Images: Press X (button 2) to reset storage.
6. Debug Info: Press Y (button 3) to toggle storage debug messages.
7. Quit: Press B (button 1) to return to splash; re-enter anytime.
8. Exit: Close the browser tab.

If no images are loaded, a message prompts upload. Storage issues (e.g., unavailable) trigger warnings/alerts.

Controls (Standard Xbox Mapping)

• Left Stick X (Axis 0): Navigate left (< -0.5) or right (> 0.5).
• A (Button 0): Start from splash / Upload images in gallery.
• B (Button 1): Quit to splash.
• X (Button 2): Clear storage.
• Y (Button 3): Toggle debug.

Mappings may vary by controller; check console logs for details.

Technical Details

• Storage: Uses localStorage for data URL persistence—no /images folder or file system writes (browser sandboxed).
• Haptics: Via vibrationActuator or hapticActuators for cross-browser support; 200ms dual-rumble at full intensity.
• Polling: Efficient requestAnimationFrame loop for gamepad input; debounced axis for smooth control.
• Security: No external APIs; all client-side. Data URLs may hit storage quotas (~5MB/browser).
• Limitations: No offline folder access; debug explains this. Vibration/browser support varies.

Repository Notes

• Any .txt files in the repository represent previous versions or iterations of the program code, preserved for reference or historical purposes.

Development Notes

• Testing: Verified in Chrome/Edge with Xbox controller. Test vibration in target browsers.
• Customization: Edit button indices in JS for different controllers. Add preload images by hardcoding URLs in images array.
• Improvements: Potential additions: Confirmation for clear (extra state), quota error handling, multi-controller support.

License

MIT License—free to use/modify with attribution.

For issues or contributions, open a pull request or report bugs.