retro-pong-game 1.1.3 → 3.0.0

package/README.md

@@ -4,7 +4,7 @@ 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.png)
+![retro-pong-game screenshot](https://chriscreativecode.com/retro-pong-game/retro-pong-game-screenshot.png?v=3)
 
 - Animated starfield or nebular background
 - Particle effects on paddle hits
@@ -37,9 +37,28 @@ 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:
+
 ```js
 import { PongGame } from 'retro-pong-game';
 
+const game = new PongGame({ isAdmin: true }, '#game');
+```
+
+Open the settings panel (gear icon), adjust colors, sizes, and speeds live, then click **Copy** at the bottom to export your config as JSON. Paste it into your constructor and remove `isAdmin`:
+
+```js
+const game = new PongGame(
+  {
+    /* paste your copied config here */
+  },
+  '#game'
+);
+```
+
+If you already know your config, pass it directly:
+
+```js
 const game = new PongGame(
   {
     canvasWidth: 600,
@@ -55,9 +74,9 @@ const game = new PongGame(
 );
 ```
 
-### 3. Clean up when done
+### 3. Clean up
 
-Always call `destroy()` before removing the element from the page:
+Call `destroy()` before removing the element from the page:
 
 ```js
 game.destroy();
@@ -225,17 +244,19 @@ The config is deep-merged in this order (later layers win):
 |---|---|---|---|
 | `autoSize` | `boolean` | `false` | Size the canvas to fill its container element at startup |
 | `autoResize` | `boolean` | `false` | Automatically resize the canvas when the container changes size (uses `ResizeObserver`) |
-| `canvasWidth` | `number` | `400` | Canvas width in px — ignored when `autoSize` is `true` |
-| `canvasHeight` | `number` | `300` | Canvas height in px — ignored when `autoSize` is `true` |
+| `canvasWidth` | `number` | `400` | Canvas width in px (ignored when `autoSize` is true) |
+| `canvasHeight` | `number` | `300` | Canvas height in px (ignored when `autoSize` is true) |
 | `paddleWidth` | `number` | `70` | Paddle width in px |
 | `paddleHeight` | `number` | `10` | Paddle height in px |
 | `ballDiameter` | `number` | `7` | Ball diameter in px |
 | `ballSpeed` | `number` | `3` | Starting ball speed (px per frame) |
 | `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 |
+| `difficultyLevel` | `number` | `1` | Starting AI difficulty; higher = faster and more precise AI |
 | `particleBounce` | `boolean` | `true` | Particle burst when the ball hits a paddle |
 | `hasSound` | `boolean` | `false` | Enable sound effects |
-| `onSoundToggle` | `(enabled: boolean) => void` | — | Called when the player toggles the sound icon |
+| `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)) |
+| `onSoundToggle` | `(enabled: boolean) => void` | - | Called when the player toggles the sound icon |
 | `timer` | [`TimerConfig`](#timerconfig) | see below | Countdown timer settings |
 | `colors` | [`ColorConfig`](#colorconfig) | see below | Colors for game elements |
 | `animatedBackground` | [`AnimatedBackgroundConfig`](#animatedbackgroundconfig) | see below | Background animation |
@@ -349,16 +370,42 @@ The player controls the **bottom** paddle. The **top** paddle is the AI opponent
 
 ## Settings panel
 
-The game includes a built-in settings panel (gear icon in the corner of the canvas). Players can change colors, background effects, difficulty, timer duration, and more. All changes are saved to `localStorage` and restored automatically on the next visit.
+The game includes a built-in settings panel (gear icon in the corner of the canvas). Players can change colors, background effects, and particle settings. All changes are saved to `localStorage` and restored automatically on the next visit.
 
 To reset all saved settings back to defaults:
 
 ```js
-localStorage.removeItem('chriscreativecode.com');
+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.
+
+```js
+const game = new PongGame({ isAdmin: true }, '#game');
+```
+
+**Workflow:**
+
+1. Start the game with `isAdmin: true`
+2. Open the settings panel (gear icon) — you will see all configurable fields including sizes, speeds, colors, timer, and difficulty
+3. Adjust the values and watch the changes live
+4. Scroll to the bottom of the panel and click **Copy** to copy the full config as JSON
+5. Paste the JSON into your constructor and remove `isAdmin`
+
+In admin mode the settings panel exposes:
+
+- **Difficulty fields** — `ballSpeed`, `paddleMoveStep`, `paddleWidth`, `paddleHeight`, `ballDiameter`, `difficultyLevel`
+- **Timer duration** — `timer.duration` (changing match length affects scoring opportunities)
+- **Config JSON export** — a read-only textarea at the bottom of the panel showing the full current config as JSON, with a **Copy** button
+
+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)

package/dist/pong-game.d.ts

@@ -105,6 +105,21 @@ export interface PongGameConfig {
   hasSound?: boolean;
   /** Called whenever the player toggles sound on or off via the in-game icon. */
   onSoundToggle?: (enabled: boolean) => void;
+  /**
+   * Show the settings gear button that lets players open the in-game settings panel.
+   * Set to `false` to hide it and prevent players from changing game settings.
+   * The sound icon repositions to the right edge when this is `false`.
+   * Default: `true`
+   */
+  showSettings?: boolean;
+  /**
+   * When `true`, the settings panel also shows difficulty-related fields
+   * (`ballSpeed`, `paddleMoveStep`, `paddleWidth`, `paddleHeight`, `ballDiameter`,
+   * `difficultyLevel`) and a JSON export of the current config.
+   * Intended for developers/integrators — set in the constructor config, not by end users.
+   * Default: `false`
+   */
+  isAdmin?: boolean;
 }
 
 /**