🎮 Idle Games Collection

A curated collection of relaxing idle and puzzle games built with HTML5, CSS3, and JavaScript. Perfect for unwinding or keeping your mind engaged during breaks.

Thank you for enjoying this little collection — if these games brought you a smile or a moment of calm, buying me a coffee helps keep the lights on and fuels future updates. Gratitude means the world. ❤️

🌐 Play Online

🚀 Play All Games Live

The complete collection is hosted on GitHub Pages with a beautiful launcher interface.

🎮 Games

🟣 Strange Pebbles

A physics sandbox with curious pebbles. Discover their interactions, build complex machines, or just enjoy the chaos.

• Tags: Physics, Sandbox, Simulation

🎄 Tree Decorator

A cozy, fractal-based Christmas tree decorating game. Draw glowing lights, place ornaments, and enjoy the festive atmosphere.

• Tags: Creative, Relaxing, Seasonal

🎄 Festive Advent

Unlock daily festive surprises, each hiding a cheerful mini-game or cozy activity. Progress is saved locally.

• Tags: Seasonal, Mini-games

🏮 Lumen Drift

Guide an astral lantern through drifting currents, collect glints, dodge dusk shadows, and chase ever-longer drifts.

• Tags: Relaxing, Arcade, Atmospheric

🛸 Space Trader

Retro space trading adventure in a deterministic procedural galaxy. Trade, haggle, refuel, and travel across systems.

• Tags: Trading, Procedural, Space, Retro

🐕 Sheepdog

Guide your border collie to herd fluffy sheep into their paddocks. Sort black and white sheep, manage stubborn ones.

• Tags: Herding, Puzzle, Cute

🎯 Ballistic Warfare

Turn-based artillery duel featuring rolling grenades, homing missiles, destructible terrain, and mobile-friendly controls.

• Tags: Artillery, Physics, Multiplayer

🧩 Fit the Shapes

Tetris-inspired puzzle game with special diamond and lava pieces. Place shapes strategically to clear rows.

• Tags: Puzzle, Strategy

🧩 Jigsaw Puzzle

Import an image and solve a satisfying jigsaw with interlocking pieces. Drag, snap, pan, and pinch-zoom.

• Tags: Puzzle, Touch

🌸 Garden Grower

A calm, plant-themed memory match game. Flip cards, find matching garden symbols, and clear the board.

• Tags: Memory, Puzzle, Relaxing

🚀 Space Scroller

Navigate through space in this endless scrolling adventure. Dodge obstacles, collect power-ups.

• Tags: Action, Endless, Space

🎲 Yahtzee

Classic dice game with a challenging twist! Roll for combinations, score strategically, and aim for the perfect Yahtzee.

• Tags: Dice, Strategy, Classic

🦴 Fossil Hunter

Archaeological discovery game with realistic sand brushing mechanics. Excavate ancient fossils.

• Tags: Archaeology, Discovery, Educational

🛠️ Tools

📻 AM Radio Console

Load any audio loop into a vintage AM receiver with tuning static, fine-grain touch control, and animated gauges.

• Tags: Audio, Retro, Visualizer

🛰️ Space Trader Starmap

Explore the procedural galaxy from Space Trader with zoomable starmaps, orbit lighting, and search.

• Tags: Space, Atlas, Reference

🎙️ Dictaphone

Professional audio recording tool with real-time position seeking, volume control, and export capabilities.

• Tags: Audio, Recording, Utility

🌀 Feed Cycle

Local-first RSS/Atom reader with OPML tools, media playback, smart tagging, filters, and themes.

• Tags: Reader, Utility, Local

🎡 Smart Spinners

Create unlimited customizable spin wheels with per-wheel palettes, advanced spin physics, and accessible inline results.

• Tags: Randomizer, Classroom, Utility

⏱️ Timers Studio

Run infinite countdown timers with customizable durations, per-timer sound/notification overrides.

• Tags: Productivity, Utility

🧊 Voxel Paint Studio

Create illuminated 3D voxel dioramas with lighting controls, SSAO, nav cube navigation, and export tools.

• Tags: 3D, Creative, Tool

🗂️ Personal Organiser

Complete productivity suite with accessible material UI. Manage notes, calendar events, tasks, cards.

• Tags: Productivity, Utility, Local

💿 RPM Disc Encoder

Encode short audio clips into a visual "RPM" disc PNG and decode them back.

• Tags: Audio, Tool, Experimental

🔄 QR Loop

Advanced file transfer via chunked QR codes. Transfer files of any size by automatically cycling through QR codes.

• Tags: QR Code, Utility, Transfer

✨ Features

🎨 Modern UI Design

• Clean, responsive interface that works on desktop and mobile
• Professional card-based layout with smooth animations
• Intuitive navigation and user experience

🌓 Universal Theme Support

• System Theme: Automatically follows your OS preference
• Light Mode: Bright, clean interface for daytime play
• Dark Mode: Easy on the eyes for evening sessions
• Persistent Settings: Your theme choice is remembered

📱 Responsive & Accessible

• Mobile-friendly design that scales to any screen size
• Keyboard navigation support
• High contrast ratios for accessibility
• Touch-friendly controls

🛠️ Technical Details

Built With

• HTML5 Canvas for game rendering and graphics
• CSS3 with CSS Variables for theming and animations
• Vanilla JavaScript for game logic and interactivity
• LocalStorage for persistent game data and preferences

� Progressive Web App

• Service worker precaches the entire collection for offline play.
• assets/js/pwa.js reads the centralized version constant in assets/js/version.js and prompts the user to refresh once a new build is available.
• manifest.webmanifest and bundled icons enable installation on desktop and mobile.
• All runtime dependencies (Three.js, QRious, jsQR, Transformers.js, Inter font) are vendored into assets/vendor/ and assets/fonts/ during the build so the experience is self-contained.

�🖼️ Favicon on GitHub Pages

Each HTML page explicitly links favicon.ico so icons resolve correctly at /idlegames/ on GitHub Pages instead of the site root.

🔒 Parental Controls

The launcher includes a lightweight client-side Parental Controls feature. From the main index.html you can open the Parental Controls modal (top-left "🔒 Parental" button) to:

• Set a password (enter it twice) and enable controls
• Sign in to an admin mode that shows per-item checkboxes (checked = visible)
• Apply & Enforce to lock the choices for non-logged-in users, or Disable to remove the password and allowed map

Storage details:

• The parental control state is stored locally in your browser's LocalStorage under the key idlegames-parental-v1.
• The password is hashed (SHA-256) with a randomized salt before storing. No server-side storage or transmission occurs.

Security note:

• This is a client-side convenience feature intended to prevent casual access. It is not a replacement for device-level parental controls. Because data and logic live in the browser, a technically capable user could bypass or reset the controls by clearing LocalStorage or editing the files.

Browser Compatibility

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Mobile browsers (iOS Safari, Chrome Mobile)
• Progressive enhancement for older browsers

Performance Optimized

• RequestAnimationFrame for smooth animations
• Efficient canvas rendering techniques
• Optimized asset loading and memory usage

🚀 Getting Started

Play Online

Simply visit https://timelessp.github.io/idlegames/ to start playing immediately.

Run Locally

Idle Games uses plain npm for tooling and scripts—no bundlers or task runners beyond what ships in this repository. The workflow below mirrors what the CI pipeline executes.

1. Clone this repository:

   git clone https://github.com/TimelessP/idlegames.git
   cd idlegames

2. Install dependencies with npm (Node.js 20 LTS recommended, Node.js ≥18 supported):

   npm install

3. Build the offline bundle into dist/ (vendors Three.js examples, fonts, service worker, etc.):

   npm run build

4. Preview locally with caching behaviours intact (rebuilds and serves dist/ on port 4173):

   npm run serve

   The generated dist/ folder is the exact payload deployed to GitHub Pages or any other static host.

🚢 Release Process

The service worker caches by version, so every public release needs a fresh build tied to a new semantic version.

1. Bump the version. Update the version field in package.json (e.g. 1.0.5). Bump by +0.0.1 regardless of semantic versioning rules.
2. Build & Update Lockfile. Run npm install && npm run build. The install updates package-lock.json with the new version number, and the build updates the version in the app itself (regenerating assets/js/version.js and dist/).
3. Commit and Push. Commit the changes (package.json, package-lock.json, assets/js/version.js) and push to GitHub.

# 1. Update package.json version manually
# 2. Run build pipeline
npm install && npm run build

# 3. Commit and push
git add package.json package-lock.json assets/js/version.js
git commit -m "Release v1.0.109"
git push origin main

The GitHub Actions workflow (build-and-deploy.yml) will automatically pick up the push, build the project again (ensuring a clean environment), and deploy the dist/ folder to GitHub Pages.

❤️ Love Letter Pro Tip: Solving the Race Condition

If you ever see two workflows running in parallel on GitHub Actions ("pages build and deployment" vs "Build and Deploy PWA") and getting 404 errors for sw.js:

The Problem: GitHub's default "Deploy from a branch" setting triggers a standard Pages workflow that competes with our custom PWA build workflow. If the default one wins, it deploys the raw source (ignoring dist/), breaking the app.

The Fix: Go to Settings > Pages in the repository. Under Build and deployment, change the Source from "Deploy from a branch" to "GitHub Actions". This disables the default workflow and lets our custom build-and-deploy.yml handle everything perfectly. No more race conditions! <3

🎮 Categories

Games

• 🧩 Puzzle & Strategy: Fit the Shapes, Jigsaw Puzzle, Sheepdog, Yahtzee, Garden Grower
• 🧪 Physics & Simulation: Strange Pebbles, Ballistic Warfare
• 🚀 Action & Adventure: Space Trader, Space Scroller, Lumen Drift, Fossil Hunter
• 🎄 Seasonal: Tree Decorator, Festive Advent

Tools

• 🎙️ Audio: AM Radio Console, Dictaphone, RPM Disc Encoder
• 🛠️ Productivity: Feed Cycle, Personal Organiser, Timers Studio
• 🎨 Creative: Voxel Paint Studio, Smart Spinners
• 🔧 Utilities: QR Loop, Space Trader Starmap

🤝 Contributing

This is a personal collection of games, but feedback and suggestions are welcome! Feel free to:

• Report bugs or issues
• Suggest new features
• Share your high scores
• Create pull requests for improvements

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎯 Project Goals

This collection aims to provide:

• Relaxing gameplay for stress relief and mental breaks
• Accessible gaming that works on any device
• Quality over quantity with polished, well-designed experiences
• Educational value through physics simulations and puzzle-solving

---

🌟 Enjoy the games and happy playing! 🌟

Built with ❤️ and 🤖 for the joy of simple, elegant gaming experiences.