retro-pong-game 1.1.3 → 2.0.0

package/README.md

@@ -37,9 +37,28 @@ The game appends a `<canvas>` inside this element automatically.
 
 ### 2. Import and create the game
 
+**Recommended for first-time setup** — start with `isAdmin: true` to configure the game visually:
+
 ```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'
+);
+```
+
+**Already know your config?** Pass it directly:
+
+```js
 const game = new PongGame(
   {
     canvasWidth: 600,
@@ -235,6 +254,8 @@ The config is deep-merged in this order (later layers win):
 | `difficultyLevel` | `number` | `1` | Starting AI difficulty — higher = faster and more precise |
 | `particleBounce` | `boolean` | `true` | Particle burst when the ball hits a paddle |
 | `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)) |
 | `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 |
@@ -349,7 +370,7 @@ 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:
 
@@ -359,6 +380,32 @@ localStorage.removeItem('chriscreativecode.com');
 
 ---
 
+## 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;
 }
 
 /**