retro-pong-game 3.0.1 → 4.0.1

package/README.md

@@ -4,18 +4,36 @@ A retro-style Pong game that runs in any browser. Drop it onto your website with
 
 **[Live demo](https://chriscreativecode.com/retro-pong-game/)**
 
-![retro-pong-game screenshot](https://chriscreativecode.com/retro-pong-game/retro-pong-game-screenshot-v3.png?v=1)
+![retro-pong-game screenshot](https://chriscreativecode.com/retro-pong-game/screenshot-retro-pong-game-v4.png?v=1)
 
 - Animated starfield or nebular background
 - Particle effects on paddle hits
 - Countdown timer with configurable duration
 - Adaptive AI difficulty (auto-adjusts after scoring streaks)
+- Power-ups and power-downs that randomly appear in the field
 - In-game settings panel (changes saved to `localStorage`)
 - Stereo-panned sound effects
 - Fully configurable colors, sizes, and speeds
 - TypeScript types included
 
----
+## How to play
+
+You control the **bottom paddle** using the arrow keys. The **top paddle** is the AI opponent.
+
+**Goal:** score as many points as possible before the timer runs out. A point is scored when the ball passes the opponent's paddle and exits through their side of the field. The player with the most points when the timer reaches zero wins.
+
+**Controls:**
+
+| Key | Action |
+| --- | --- |
+| `←` Arrow Left or `A` | Move paddle left |
+| `→` Arrow Right or `D` | Move paddle right |
+| `P` or `Space` | Pause / resume |
+| `B` | Cycle ball image (planet → coin → face → ship → Star Wars → beer → none → …) |
+
+**Scoring streaks** affect the AI: if you score three times in a row the AI gets harder; if the AI scores three times in a row it gets easier, so the game stays competitive.
+
+**Power-ups and power-downs** appear randomly in the field every 12 seconds. Steer the ball into them to activate the effect. Power-ups (bright solid circles) give you a temporary advantage. Power-downs (dark circles with a rotating dashed ring) make the game harder for a few seconds. See [Power-ups & power-downs](#power-ups--power-downs) for the full list.
 
 ## Installation
 
@@ -23,8 +41,6 @@ A retro-style Pong game that runs in any browser. Drop it onto your website with
 npm install retro-pong-game
 ```
 
----
-
 ## Quick start
 
 ### 1. Add a container element to your HTML
@@ -37,7 +53,9 @@ The game appends a `<canvas>` inside this element automatically.
 
 ### 2. Import and create the game
 
-**New to this package?** Start with `isAdmin: true` to configure everything visually first:
+**New to this package?** Start with `isAdmin: true` to configure everything visually first.
+
+> **Fun tip:** press `B` during any game to cycle the ball through fun images (planet, coin, face, spaceship, Star Wars logo, beer). Press again to go to the next image; one more press after the last image clears it back to a plain ball.
 
 ```js
 import { PongGame } from 'retro-pong-game';
@@ -82,8 +100,6 @@ Call `destroy()` before removing the element from the page:
 game.destroy();
 ```
 
----
-
 ## CDN (no npm required)
 
 ```html
@@ -107,8 +123,6 @@ game.destroy();
 </html>
 ```
 
----
-
 ## Framework examples
 
 ### React
@@ -222,8 +236,6 @@ const config: PongGameConfig = {
 const game = new PongGame(config, '#game');
 ```
 
----
-
 ## Configuration
 
 All options are optional. Omitted values fall back to built-in defaults.
@@ -253,6 +265,7 @@ The config is deep-merged in this order (later layers win):
 | `paddleMoveStep` | `number` | `4` | Paddle speed while an arrow key is held (px per frame) |
 | `difficultyLevel` | `number` | `1` | Starting AI difficulty; higher = faster and more precise AI |
 | `particleBounce` | `boolean` | `true` | Particle burst when the ball hits a paddle |
+| `powerUps` | `boolean` | `true` | Enable power-ups and power-downs that randomly appear in the field |
 | `hasSound` | `boolean` | `false` | Enable sound effects |
 | `showSettings` | `boolean` | `true` | Show the gear icon that opens the in-game settings panel. Set to `false` to lock the settings from players |
 | `isAdmin` | `boolean` | `false` | Unlock difficulty and timing controls in the settings panel, plus a JSON export of the current config (see [Admin mode](#admin-mode)) |
@@ -299,8 +312,6 @@ The config is deep-merged in this order (later layers win):
 |---|---|---|---|
 | `particlesCount` | `number` | `20` | Number of particles spawned per paddle hit |
 
----
-
 ## Methods
 
 ```js
@@ -354,19 +365,47 @@ wireButton(document.getElementById('btn-right'),
   () => game.pressRight(), () => game.releaseRight());
 ```
 
----
-
 ## Keyboard controls
 
 | Key | Action |
-|---|---|
-| `←` Arrow Left | Move paddle left |
-| `→` Arrow Right | Move paddle right |
+| --- | --- |
+| `←` Arrow Left or `A` | Move paddle left |
+| `→` Arrow Right or `D` | Move paddle right |
 | `P` or `Space` | Pause / resume |
+| `B` | Cycle ball image (planet → coin → face → ship → Star Wars → beer → none → …) |
 
 The player controls the **bottom** paddle. The **top** paddle is the AI opponent.
 
----
+## Power-ups & power-downs
+
+Every 12 seconds a glowing item appears somewhere in the middle of the field. Hit it with the ball to activate its effect. The item then disappears and a new one spawns 12 seconds later.
+
+### How to tell them apart
+
+| Visual | Type |
+| --- | --- |
+| **Bright solid circle** — slow pulsing outer ring | Power-up — helps you |
+| **Dark circle with rotating dashed ring** — fast flickering | Power-down — hurts you |
+
+### Power-ups (beneficial)
+
+| Letter | Color | Effect | Duration |
+| --- | --- | --- | --- |
+| **W** | Green | Your paddle becomes twice as wide | 6 s |
+| **S** | Cyan | Ball speed is reduced by ~55% | 5 s |
+| **F** | Orange | The AI paddle is frozen and cannot move | 4 s |
+
+### Power-downs (detrimental)
+
+| Letter | Color | Effect | Duration |
+| --- | --- | --- | --- |
+| **N** | Red | Your paddle shrinks to half its normal width | 5 s |
+| **X** | Orange-red | Ball speed increases by 80% | 5 s |
+| **C** | Purple | The AI paddle becomes twice as wide | 5 s |
+
+A flash message appears on screen when an effect activates (e.g. **"CPU FROZEN!"** or **"NARROW PADDLE!"**) and fades out over the effect's duration so you always know what is active.
+
+Power-ups and power-downs can be disabled via the in-game settings panel (toggle **Power-ups**) or through the config option `powerUps: false`.
 
 ## Settings panel
 
@@ -378,8 +417,6 @@ To reset all saved settings back to defaults:
 localStorage.removeItem('chriscreativecode.com-retro-pong-game');
 ```
 
----
-
 ## Admin mode
 
 `isAdmin: true` is the recommended starting point when you are setting up the game for the first time. It unlocks the full settings panel so you can configure everything visually before committing to a config object.
@@ -404,8 +441,6 @@ In admin mode the settings panel exposes:
 
 Without `isAdmin`, these fields are hidden from players so they cannot alter the game balance. Do not ship `isAdmin: true` to end users.
 
----
-
 ## Resize handling
 
 ### Automatic (recommended)
@@ -440,14 +475,31 @@ window.addEventListener('resize', () => game.resizeGame());
 
 `autoSize: true` alone sizes the canvas once at startup. The game then has a fixed size until you call `resizeGame()` manually.
 
----
+## Troubleshooting
+
+### Upgrading from an older version
+
+If you previously had an older version installed on your site and are upgrading to a newer version, you may run into issues caused by stale data in `localStorage`. To fix this, clear the saved game data in your browser.
+
+**Option 1 — Clear all site data (quickest)**
+
+1. Open the page in Chrome
+2. Press `F12` to open DevTools
+3. Go to **Application**
+4. Click **Clear site data**
+
+**Option 2 — Remove only the game's localStorage entry (recommended if you have other data on the page)**
+
+1. Open DevTools (`F12`) and go to **Application → Local Storage**
+2. Find the key `chriscreativecode.com-retro-pong-game`
+3. Select that row and delete it (right-click → Delete, or press the Delete key)
+
+After clearing the entry the game will start fresh with default settings on the next page load.
 
 ## Browser support
 
 All modern browsers with HTML Canvas support (Chrome, Firefox, Safari, Edge). When importing the ES module build, a bundler (Vite, Webpack, esbuild, Parcel) is recommended for production use.
 
----
-
 ## License
 
 MIT © [Chris Schardijn](https://chriscreativecode.com)