HissTastic
+A retro Snake-inspired arcade game.
Play in your browser or on Android. Local-first, no ads, no accounts.
A retro Snake-inspired arcade game.
Play in your browser or on Android. Local-first, no ads, no accounts.
+
- 
- 
- 
-
+ 
+ 
+| ---- - -## Local Development - -HissTastic has two runtimes. **Neither requires Vercel, a backend, or any external service for normal local play.** The global leaderboard uses Supabase only to sync player profile and personal-best rows. - -### Prerequisites - -- **Python 3.9+** ([python.org](https://python.org)) -- **Git** ([git-scm.com](https://git-scm.com)) -- **A modern browser** (Chrome, Firefox, Edge, Safari) -- **pygame** (for the Python runtime only) - -### Quick Start - -```bash -# Clone the repo -git clone https://github.com/sparshsam/hisstastic.git -cd hisstastic - -# Or use the dev server script -bash scripts/serve.sh -# Opens at http://localhost:8080 — the browser game, no build step required -``` - ---- - -### Python Runtime Setup - -The Python/Pygame version is the canonical runtime. - -```bash -# Create and activate a virtual environment -python -m venv .venv - -# macOS / Linux: -source .venv/bin/activate - -# Windows (PowerShell): -.venv\Scripts\activate - -# Install pygame -pip install pygame - -# Run the game -python main.py -``` - -**Legacy entry point** (preserved, unchanged): - -```bash -python hisstastic.py -``` - -**Troubleshooting:** - -| Problem | Fix | -|---------|-----| -| `ModuleNotFoundError: No module named 'pygame'` | Run `pip install pygame` | -| `pygame.error: video system not initialized` | Ensure you have a display (no `DISPLAY` in SSH) | -| `pygame.error: No available video device` | Install X server or use headless mode (see below) | - -**Headless/WSL (no display):** - -On WSL or headless servers, the Python runtime won't produce a window. This is expected. -Use the browser runtime instead — it's the primary local dev workflow. - ---- - -### Browser Runtime Setup - -The browser runtime is a zero-config static site. No build step, no framework, no Node.js required. - -#### Option A: Quick Dev Server (Recommended) - -```bash -bash scripts/serve.sh -# Opens at http://localhost:8080 -``` - -Or with a custom port: - -```bash -bash scripts/serve.sh 3000 -# Opens at http://localhost:3000 -``` - -#### Option B: Python HTTP Server (Manual) - -```bash -python -m http.server 8080 --directory web/ -# Opens at http://localhost:8080 -``` - -#### Option C: Any Static Server - -```bash -# Node (if installed) -npx serve web/ -p 8080 - -# PHP -php -S localhost:8080 -t web/ -``` - ---- - -### Local Static / Production-Style Preview - -To preview the game as it would appear in production, serve from the `web/` directory: - -```bash -# Start server -python -m http.server 8080 --directory web/ - -# Open in a browser -open http://localhost:8080 -``` - -**Important:** On plain HTTP `localhost`, the service worker is intentionally skipped to -avoid stale-cache confusion during local development. You can play and test everything on -localhost without issues — this is the recommended local workflow. - -To test full PWA offline caching and service worker behavior, deploy to a secure context -(HTTPS) such as: - -- Vercel preview deployment (`vercel --preview`) -- GitHub Pages -- Any HTTPS-enabled hosting -- A local HTTPS server (e.g. `mkcert` for a trusted local cert) - -When deployed to HTTPS, the service worker caches all assets and the game remains -playable offline. - ---- - -### Testing the Python Runtime - -```bash -# Validation suite (checks assets, schema, imports, etc.) -python validation.py - -# Unit tests -python -m unittest discover -v - -# Replay system -python -m hisstastic.replay_cli record -python -m hisstastic.replay_cli verify replays/replay_*.json -python -m hisstastic.replay_cli play replays/replay_*.json -``` +**Power-ups** — 4 types: +- Immunity +- Speed Boost +- Shield +- Score Multiplier -### Testing the Browser Runtime +**Difficulty** — Easy / Normal / Hard -```bash -# Local health check — verifies all files, assets, and dependencies -bash scripts/check-local.sh +**Audio** — Procedural sound effects + looping background music -# Start the server and open http://localhost:8080 -bash scripts/serve.sh +**Controls** — Keyboard, touch/swipe, on-screen D-pad -# Manual smoke tests: -# 1. Game loads without JS console errors -# 2. Title screen displays with difficulty selection -# 3. Gameplay: snake moves, eats food, collides with obstacles -# 4. Sound effects play on eat/power-up/game-over -# 5. Background music toggle works (🎵 Music button) -# 6. Music credit link opens YouTube source -# 7. PWA manifest loads (check DevTools → Application → Manifest) -# 8. Service worker state (check DevTools → Application → Service Workers; -# on localhost it won't register — expected. Verify on HTTPS/preview.) -# 9. Import/Export replay buttons work -# 10. Mobile D-pad controls respond on touch devices -``` +**Replay** — Deterministic recording, playback, verification ---- - -### Verifying All Assets Load Locally - -| Asset | Path | How to Verify | -|-------|------|---------------| -| **Browser HTML** | `web/index.html` | Load `http://localhost:8080` | -| **CSS** | `web/css/style.css` | DevTools → Network → style.css | -| **JS files** | `web/js/*.js` | DevTools → Sources → js/ | -| **Background music** | `web/assets/background-music.mp3` | Click 🎵 Music button; should play at low volume | -| **PWA manifest** | `web/manifest.webmanifest` | DevTools → Application → Manifest | -| **Service worker** | `web/sw.js` | DevTools → Application → Service Workers | -| **PWA icons** | `web/icons/icon-{192,512}.png` | DevTools → Application → Manifest | -| **Python assets** | `assets/snake.png, rodent.png, danger.png, power_up.png, icon.png` | `ls assets/` or `python validation.py` | - -**Graceful degradation:** If the background music file is missing or fails to load, the -Music button becomes disabled and the game continues without crashing. - ---- - -### Common Local Issues - -#### "The service worker keeps serving old files!" - -During development, the service worker caches aggressively. If you see stale content: - -1. Open DevTools → Application → Service Workers -2. Click **"Unregister"** -3. Hard-reload (`Ctrl+Shift+R` or `Cmd+Shift+R`) - -Or, run an incognito/private window where no service worker is registered. - -#### "Background music doesn't play!" - -- **Browser autoplay policy:** The music only starts after your first click/tap on the page. - Click anywhere on the game first. -- **File not found:** Check that `web/assets/background-music.mp3` exists. - If missing, the Music button will be disabled. -- **Volume too low:** Default volume is 0.15. Ensure your system volume is turned up. - -#### "The Python game doesn't start / black screen on WSL" - -WSL doesn't have a native display. The Python/Pygame runtime requires a window server. -Use the browser runtime instead (`bash scripts/serve.sh` then open in Windows browser). - -#### "Page looks wrong / assets not loading" - -Make sure you're accessing the game through an HTTP server, not by opening the HTML file directly -(`file:///` path). Browsers block many features (service workers, audio, fetch) on `file://` URLs. - -```bash -# Correct: -python -m http.server 8080 --directory web/ -# Then open http://localhost:8080 - -# Incorrect: double-clicking web/index.html (file:///path/to/index.html) -``` - ---- - -## Replay System - -Record a game session: - -```bash -python -m hisstastic.replay_cli record -``` - -Verify a replay file: - -```bash -python -m hisstastic.replay_cli verify replays/replay_12345_20260604.json -``` + | +-Play back a replay: +**Visual Themes** — 4 themes: +- Classic (green) +- Midnight (dark) +- Desert (warm) +- Ocean (teal) -```bash -python -m hisstastic.replay_cli play replays/replay_12345_20260604.json -``` +**Pause/Resume** — On-screen pause button -See [docs/replay-ux.md](docs/replay-ux.md) and [docs/ghost-racing.md](docs/ghost-racing.md). +**Haptic Feedback** — Vibration on mobile devices -## Browser Runtime +**Leaderboard** — Global personal-best via Supabase -A lightweight JavaScript/Canvas implementation is available in `web/`. +**Ghost Racing** — Race against your past self -Browser runtime capabilities: + | +
- 
-
- 
-
- Welcome screen with username setup • App icon — #00BF63 green -
diff --git a/assets/branding/icon.png b/assets/branding/icon.png new file mode 100644 index 0000000..46a4b26 Binary files /dev/null and b/assets/branding/icon.png differ diff --git a/assets/gallery/app_icon.png b/assets/gallery/app_icon.png new file mode 100644 index 0000000..c91cd49 Binary files /dev/null and b/assets/gallery/app_icon.png differ diff --git a/assets/gallery/gameplay.png b/assets/gallery/gameplay.png new file mode 100644 index 0000000..edeccca Binary files /dev/null and b/assets/gallery/gameplay.png differ diff --git a/assets/gallery/high_scores.png b/assets/gallery/high_scores.png new file mode 100644 index 0000000..dd98f0e Binary files /dev/null and b/assets/gallery/high_scores.png differ diff --git a/assets/gallery/home_page.png b/assets/gallery/home_page.png new file mode 100644 index 0000000..5d60443 Binary files /dev/null and b/assets/gallery/home_page.png differ diff --git a/assets/gallery/welcome_page.png b/assets/gallery/welcome_page.png new file mode 100644 index 0000000..0f16a3b Binary files /dev/null and b/assets/gallery/welcome_page.png differ diff --git a/assets/hero/hero.png b/assets/hero/hero.png new file mode 100644 index 0000000..edeccca Binary files /dev/null and b/assets/hero/hero.png differ diff --git a/assets/icons/apple-touch-icon.png b/assets/icons/apple-touch-icon.png new file mode 100644 index 0000000..14fe674 Binary files /dev/null and b/assets/icons/apple-touch-icon.png differ diff --git a/assets/icons/favicon-16x16.png b/assets/icons/favicon-16x16.png new file mode 100644 index 0000000..82172ca Binary files /dev/null and b/assets/icons/favicon-16x16.png differ diff --git a/assets/icons/favicon-32x32.png b/assets/icons/favicon-32x32.png new file mode 100644 index 0000000..eb18ff8 Binary files /dev/null and b/assets/icons/favicon-32x32.png differ diff --git a/assets/icons/icon-192.png b/assets/icons/icon-192.png new file mode 100644 index 0000000..9934512 Binary files /dev/null and b/assets/icons/icon-192.png differ diff --git a/assets/icons/icon-512.png b/assets/icons/icon-512.png new file mode 100644 index 0000000..426e8f0 Binary files /dev/null and b/assets/icons/icon-512.png differ diff --git a/docs/Architecture.md b/docs/Architecture.md new file mode 100644 index 0000000..dde8dc5 --- /dev/null +++ b/docs/Architecture.md @@ -0,0 +1,32 @@ +# Architecture + +This document is a brief summary. See the full [ARCHITECTURE.md](../ARCHITECTURE.md) at the repository root for the complete module structure, data flow diagrams, replay system design, ghost racing foundation, and security boundaries. + +## Overview + +HissTastic is a modular Python/Pygame arcade game with an experimental browser/PWA runtime. The original single-file prototype has been preserved, the Python runtime remains canonical, and the browser runtime is a playable sibling implementation under `web/`. + +## Key Components + +| Module | Responsibility | +|--------|---------------| +| `config.py` | Centralized CONFIG dict with all game constants and difficulty presets | +| `entities.py` | Data classes for Snake, Food, Obstacle, PowerUp | +| `game.py` | Main Game class — state machine orchestrating title, play, pause, game-over | +| `replay.py` | Deterministic replay recording, schema validation, playback, and verification | +| `ghost.py` | Local-only ghost replay loading and visualization | +| `audio.py` | Procedural sine-wave sound effects with graceful failure | + +## Runtime Flow + +Main states: `TITLE → PLAYING → PAUSED → GAME_OVER → EXIT` + +The browser runtime under `web/` mirrors this structure using JavaScript and Canvas, with touch/swipe controls, PWA support, and replay import/export. + +## Data Flow + +- Game state is in-memory within the `Game` class instance. +- Configuration from `config.py`. +- Assets loaded once by `assets.py` at startup. +- Replay files written to `replays/` as local JSON. +- No data is sent over the network (the browser runtime's Supabase leaderboard is the single exception — anonymous player ID and personal best only). diff --git a/docs/Contributing.md b/docs/Contributing.md new file mode 100644 index 0000000..9ffb41a --- /dev/null +++ b/docs/Contributing.md @@ -0,0 +1,48 @@ +# Contributing + +Thank you for considering a contribution to HissTastic. + +## Scope + +This repository is currently a preserved legacy prototype. Contributions should focus on documentation, preservation quality, compatibility fixes, and clearly scoped modernization work. + +Do not rewrite gameplay, change mechanics, or add new features unless the change is explicitly part of an approved modernization task. + +## Process + +1. Fork the repository. +2. Create a feature branch such as `docs/readme-alignment` or `fix/asset-loading`. +3. Make focused changes. +4. Run the relevant verification steps. +5. Submit a pull request with a short summary and manual test notes. + +## Git Safety + +- Never force-push `main`. +- Never rewrite protected or shared branches. +- Prefer normal `git push` after commits. +- Force-push only on isolated feature branches when absolutely necessary. +- If a force-push is used, explain the reason in the pull request or final report. + +## Standards + +- Preserve the original prototype unless a change is explicitly requested. +- Keep documentation restrained and accurate. +- Avoid telemetry, engagement-pressure mechanics, or unnecessary network services. +- Document any change that affects runtime behavior, dependencies, or data handling. +- Preserve deterministic replay behavior when changing input, spawn, timing, or scoring code. +- Keep ghost racing local-only and non-scoring. +- Follow the [ecosystem standards](https://github.com/sparshsam/ecosystem-standards). + +## Quick Links + +- [Development Setup](Development.md) +- [Architecture](Architecture.md) +- [Deployment](Deployment.md) +- [Testing](Testing.md) + +## Code of Conduct + +This project follows the [Code of Conduct](../CODE_OF_CONDUCT.md). + +By contributing, you agree that your contributions will be licensed under MIT. diff --git a/docs/Deployment.md b/docs/Deployment.md new file mode 100644 index 0000000..139ce10 --- /dev/null +++ b/docs/Deployment.md @@ -0,0 +1,55 @@ +# Deployment + +HissTastic can be deployed as an Android app (via Capacitor) or as a PWA (via any static hosting). + +## Android Build (Capacitor) + +### Prerequisites + +- Android SDK 35+ (target/compile SDK 36) +- Java 21+ +- Node.js 18+ + +### Build Steps + +```bash +npm install +npx cap sync +npm run cap:bundle:release +``` + +The APK will be at `android/app/build/outputs/apk/debug/app-debug.apk`. +The AAB will be at `android/app/build/outputs/bundle/release/app-release.aab`. + +### Detailed Instructions + +See [BUILD_ANDROID.md](../BUILD_ANDROID.md) for detailed debug, release, and signing instructions, including keystore setup and Play Store submission. + +## PWA Deployment + +The browser runtime is a static site — deployable to any static hosting provider. + +### Vercel (Recommended) + +```bash +npm install -g vercel +vercel --prod +``` + +The live game is hosted at: [https://hiss-tastic.vercel.app](https://hiss-tastic.vercel.app) + +### Other Options + +- **GitHub Pages:** Push the `web/` directory to `gh-pages` branch +- **Netlify:** Connect repo and set publish directory to `web/` +- **Any static server:** Copy the `web/` directory to any HTTP server + +### PWA Notes + +- On HTTPS, the service worker caches all assets for offline play. +- On plain HTTP localhost, the service worker is intentionally skipped (avoid stale-cache confusion during development). +- Test full PWA behavior on HTTPS before production release. + +### Play Store Listing + +See [STORE_LISTING.md](../STORE_LISTING.md) for the Play Store description, screenshots, and promotional assets. diff --git a/docs/Development.md b/docs/Development.md new file mode 100644 index 0000000..0eb5262 --- /dev/null +++ b/docs/Development.md @@ -0,0 +1,87 @@ +# Development + +## Prerequisites + +- **Python 3.9+** ([python.org](https://python.org)) +- **Git** ([git-scm.com](https://git-scm.com)) +- **A modern browser** (Chrome, Firefox, Edge, Safari) +- **pygame** (for the Python runtime only) + +## Quick Start + +```bash +git clone https://github.com/sparshsam/hisstastic.git +cd hisstastic + +# Start the dev server (no build step required) +bash scripts/serve.sh +# Opens at http://localhost:8080 +``` + +## Python Runtime Setup + +The Python/Pygame version is the canonical runtime. + +```bash +python -m venv .venv +source .venv/bin/activate # macOS/Linux +pip install pygame +python main.py +``` + +**Legacy entry point:** `python hisstastic.py` + +### Troubleshooting + +| Problem | Fix | +|---------|-----| +| `ModuleNotFoundError: No module named 'pygame'` | Run `pip install pygame` | +| `pygame.error: video system not initialized` | Ensure you have a display (no `DISPLAY` in SSH) | +| `pygame.error: No available video device` | Install X server or use headless mode | + +On WSL or headless servers, use the browser runtime instead. + +## Browser Runtime Setup + +Zero-config static site. No build step, no framework, no Node.js required. + +### Option A: Quick Dev Server (Recommended) + +```bash +bash scripts/serve.sh +# Opens at http://localhost:8080 +``` + +### Option B: Python HTTP Server + +```bash +python -m http.server 8080 --directory web/ +# Opens at http://localhost:8080 +``` + +### Option C: Any Static Server + +```bash +npx serve web/ -p 8080 # Node +php -S localhost:8080 -t web/ # PHP +``` + +## Testing + +```bash +# Validation suite +python validation.py + +# Unit tests +python -m unittest discover -v + +# Local health check +bash scripts/check-local.sh +``` + +## Common Issues + +- **Stale service worker:** Unregister in DevTools → Application → Service Workers, then hard-reload. +- **Background music doesn't play:** Click anywhere on the page first (browser autoplay policy). +- **Python black screen on WSL:** Use the browser runtime. +- **Assets not loading:** Serve via HTTP, not `file://`. diff --git a/docs/Testing.md b/docs/Testing.md new file mode 100644 index 0000000..21ca66e --- /dev/null +++ b/docs/Testing.md @@ -0,0 +1,56 @@ +# Testing + +## Python Runtime Tests + +### Validation Suite + +Comprehensive validation of assets, schema, imports, and game logic: + +```bash +python validation.py +``` + +### Unit Tests + +```bash +python -m unittest discover -v +``` + +### Replay System + +```bash +python -m hisstastic.replay_cli record +python -m hisstastic.replay_cli verify replays/replay_*.json +python -m hisstastic.replay_cli play replays/replay_*.json +``` + +## Browser Runtime Tests + +### Local Health Check + +Verifies all files, assets, and dependencies: + +```bash +bash scripts/check-local.sh +``` + +### Manual Smoke Tests + +After starting the dev server (`bash scripts/serve.sh`): + +1. Game loads without JS console errors +2. Title screen displays with difficulty selection +3. Gameplay: snake moves, eats food, collides with obstacles +4. Sound effects play on eat/power-up/game-over +5. Background music toggle works +6. PWA manifest loads (check DevTools → Application → Manifest) +7. Service worker state (on HTTPS only) +8. Import/Export replay buttons work +9. Mobile D-pad controls respond on touch devices + +## Android Build Tests + +```bash +npm run cap:bundle:debug +# Install APK on device and run smoke tests +```