A warm, syrupy, waffle-themed animated race for random selection.
The cozy cousin of the classic browser duck race — built for streamers, giveaways, raffles, and fun decision-making moments.
🧇 Premium AI-generated waffles racing in boats.
Maximum suspense. Winner only clear at the buzzer.
Wafflerace is a premium, syrupy recreation of the classic browser duck race — built for streamers, giveaways, raffles, and dramatic random selections.
Paste a list of names, set the duration, and watch real AI-generated waffles paddle their boats with chaotic, variable speeds and natural bobbing. The race is deliberately engineered so the winner only becomes obvious in the final seconds.
It uses high-quality generated assets (50+ boat sprites + layered river backgrounds) instead of simple drawings, plus subtle synthesized audio and particles for a more alive, 2026-feeling experience.
You can browse the current boat collections and backgrounds directly:
This is a companion project to Project Syrup.
Current Focus (Post-v0.1.9) — Release discipline & polish
- The release process now strictly requires that all version tags come from the
devbranch, enforced via real git history checks rather than GitHub's unreliablebase_reffield. - Ongoing logo and visual refinement (new premium logo, WebP optimization, transparency fixes, removal of legacy fallback assets).
- Improved CI and contributor hygiene (
go.sumhandling,templ+goimports, consistent asset pipeline). - The project is intentionally keeping the core race experience stable while maturing its release and maintenance practices.
v0.1.9 — Major asset milestone: Full completion of the Flags of US collection + launch of the new Flags of the World collection, plus important improvements to the boat collections system and loader.
- Full backend persistence with SQLite (races, history, saved lists)
- Spectator mode + public race links
- Live "Current Leaders" sidebar
- Race templates / quick starts
- Significantly improved history and results UI
- Better error handling across the app
- Frontend testing foundation (Vitest)
- Extracted race logic for maintainability
- ESLint + Prettier enforced
Wafflerace now uses high-quality AI-generated boat sprites and river backgrounds instead of programmer art. The race emphasizes maximum suspense: boats move with chaotic, variable speeds, but no one visually reaches the finish line until the very final seconds.
- Flags of US collection completed — All 50 U.S. states now have dedicated boats (Alabama → Wyoming). Every boat follows the strict right-facing + stern flag rules.
- New "Flags of the World" collection launched — First 5 countries complete (India, China, United States, Indonesia, Pakistan) using the same rigorous asset pipeline.
- Boat collection system significantly improved — Loader now properly supports named sprite collections (not just numbered
boat-right-XXfiles). - Much stricter and more documented asset generation workflow (originals → transparent PNG → WebP) enforced across all collections.
- Much stronger History & Analytics view (stats, searchable table, recent races)
- Dedicated /history page with analytics
- Boat Collections / Themes system (switch between different sets of boats, e.g. "Default" vs "Flags of US")
- Comprehensive frontend testing foundation (Vitest + tests for core logic)
- Improved error handling and resilience
- Further frontend architecture cleanup (extracted race-logic.js)
- Basic management surface via History
- All previous features (Spectator mode, Live leaders, "I need to pee", templates, etc.)
- ESLint + Prettier enforced
- Backend API improvements for future webhooks and integrations
- 50 unique right-facing AI boat sprites with subtle rocking and reactive name flags
- Parallax scrolling backgrounds (3 layers at different speeds, randomly selected each race)
- Synthesized audio: gentle water drone, splashes on big surges, and a win chime
- Particle effects (syrup drips and small splashes)
- Smooth loading progress screen while assets load
- Extremely aggressive final-phase jitter and rubber-banding
- Strong visual clamping so the leader stays well back until the buzzer
- "I need to pee" pause button
- Quick duration presets (15s–5min in 30s steps) + manual input
- Name display options (full / short / hidden)
- Hide controls during race for cleaner presentation
- Race history (last 10 runs stored locally)
- "Run Again with same names" workflow
- Touch-friendly setup screen for tablets
- Up to 50 participants with smooth 60fps canvas animation
- Clean results with podium + full field (no times shown)
- Docker + Traefik + CrowdSec ready for production deployment
See the changelog for full details.
- Backend: Go + Gin
- Frontend: Templ + HTMX + Tailwind CSS + DaisyUI
- Animation: HTML Canvas (for smooth performance at higher participant counts)
- Packaging: Docker + Docker Compose
- Philosophy: Keep it simple and boring. Readable names over clever ones.
Wafflerace is designed to run behind Traefik with automatic Let's Encrypt SSL and protected by CrowdSec.
Two compose files are provided:
| File | Purpose | Recommended For |
|---|---|---|
docker-compose.dev.yml |
Development | Local / Staging |
docker-compose.prod.yml |
Production | Live deployments |
Before running either compose file, open it and complete the "PREREQUISITES / CUSTOMIZATION CHECKLIST" located right after the version: line at the top.
This checklist covers:
- Let's Encrypt email
- All hostnames / domains
- CrowdSec bouncer API key
- External network name (
proxy) - Production image version pinning
See README-dev.md for more details.
Wafflerace is a companion project to Project Syrup.
The long-term goal is to be able to use (or embed) the race functionality inside the main waffle application when needed for random draws, giveaways, or fun community moments.
For now it is developed as its own focused tool.
Active work happens on the dev branch.
The main branch is kept stable and contains the current README plus minimal supporting files.
docker compose up -d --buildThen visit http://localhost:9090.
See README-dev.md for production-style Traefik + CrowdSec setup.
We use WebP as the primary format for boats and backgrounds (much smaller files).
Useful commands:
npm run convert:boats # Convert boat sprites to WebP
npm run convert:backgrounds # Convert backgrounds to WebPWhen creating new boat assets, boats must always face right. See assets/boat-concepts/README.md for the full rules.
See AGENTS.md for architecture decisions, rules (including the Scooby-Doo commit requirement), and important context.
Every commit must end with a random Scooby-Doo quote. Examples:
- "Ruh-roh!"
- "Zoinks!"
- "Jinkies!"
- "Would you do it for a Scooby Snack?"
- "Puppy Power!"
Wafflerace exists because two glass artists kept running great waffles the hard way.
Special shout out to Dani Boo Glass and Crysis Designs for creating the original Waffle and for driving me nuts watching them copy/paste spot lists over and over again in chat.
MIT — do whatever you want.
If this project helps you run smoother races, consider supporting the work:
Built with 🧇, maple syrup, and a concerning number of late nights.