punter.js 1.1.0 → 1.2.0

package/.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Start dev server",
+            "type": "node",
+            "request": "launch",
+            "runtimeExecutable": "npx",
+            "runtimeArgs": ["serve", ".", "-l", "4000"],
+            "cwd": "${workspaceFolder}",
+            "console": "integratedTerminal",
+            "skipFiles": ["<node_internals>/**"]
+        }
+    ]
+}

package/README.MD

@@ -47,15 +47,14 @@ Download `punter.js` and include it with a script tag before your game code:
 
 ## Run the Example
 
-The repo includes a Pong game in `games/pong.html`. Open it with a local web server - browsers block local file loading without one.
+**VS Code (recommended):**
+1. Open this folder in VS Code
+2. Run → Start Debugging
+3. Open http://localhost:4000/games/pong.html
 
-```bash
-npm start
-```
-
-Then open **http://localhost:3000/games/pong.html** in your browser.
-
-> `npm start` uses `npx serve` - no install step needed beyond having Node.js.
+**Terminal:**
+1. Run `npm start`
+2. Open http://localhost:4000/games/pong.html
 
 ## How it Works
 
@@ -63,7 +62,7 @@ Every punter.js game follows the same three-step pattern:
 
 1. **setup** - specify which canvas to use and which images/sounds to preload
 2. **scene** - define a named scene (level, menu, etc.) with update/draw logic
-3. **ready** - switch to a scene once everything has loaded
+3. **go** - call `punter.go()` to start
 
 ```js
 // 1. Load assets
@@ -76,7 +75,7 @@ punter.setup({
 // 2. Define a scene
 punter.scene('level1', function () {
 
-  var player = punter.createSprite({ id: 'player', key: 'player', x: '50%', y: '50%' });
+  var player = punter.createSprite({ id: 'player', image: 'player', x: '50%', y: '50%' });
 
   punter.on('update', function () {
     if (punter.keys['ArrowRight']) player.moveX(3);
@@ -84,16 +83,10 @@ punter.scene('level1', function () {
     if (punter.keys['ArrowUp'])    player.moveY(-3);
     if (punter.keys['ArrowDown'])  player.moveY(3);
   });
-
-  punter.on('draw', function () {
-    player.draw(this); // 'this' is the canvas 2D context
-  });
 });
 
-// 3. Start when ready
-punter.on('ready', function () {
-  punter.go('level1');
-});
+// 3. Go! (waits for assets to finish loading automatically)
+punter.go('level1');
 ```
 
 ## Setup
@@ -123,7 +116,7 @@ Option    | Required | Description
 
 ## Scenes
 
-Scenes are the different screens in your game - a menu, level 1, game over. Define each with `punter.scene()`, then switch between them with `punter.go()`. Switching scenes automatically clears the previous update/draw handlers.
+Scenes are the different screens in your game - a menu, level 1, game over. Define each with `punter.scene()`, then switch between them with `punter.go()`. Switching scenes automatically clears the previous update/draw handlers and destroys all sprites from the previous scene.
 
 ```js
 punter.scene('menu', function () {
@@ -143,8 +136,8 @@ Register handlers with `punter.on()`. Each event can only have one handler at a
 
 ```js
 punter.on('ready', function () {
-  // fires once - all assets loaded, safe to create sprites
-  punter.go('level1');
+  // optional - fires once when all assets have loaded
+  // not needed for starting a scene; use punter.go() directly instead
 });
 
 punter.on('update', function () {
@@ -152,8 +145,10 @@ punter.on('update', function () {
 });
 
 punter.on('draw', function () {
-  // fires every frame - 'this' is the canvas 2D context
-  player.draw(this);
+  // optional - 'this' is the canvas 2D context
+  // sprites are drawn automatically before this runs, so use it for
+  // overlays: score text, HUD, shapes drawn on top of sprites
+  // backgrounds should be set via CSS on the canvas element
 });
 
 punter.on('resize', function () {
@@ -163,23 +158,23 @@ punter.on('resize', function () {
 
 ## Sprites
 
-A sprite is any image in your game - a character, enemy, coin, background tile. Create one with `punter.createSprite()`:
+A sprite is any image in your game - a character, enemy, coin, background tile. Create one with `punter.createSprite(options)`:
 
 ```js
 var player = punter.createSprite({
-  id:  'player',  // unique name - no two sprites can share one
-  key: 'player',  // matches a key from config.sprites
-  x:   '50%',    // position - number (pixels) or percent string
-  y:   '80%'
+  id:    'player',  // unique name - no two sprites can share one
+  image: 'player',  // name from config.images
+  x:     '50%',    // position - number (pixels) or percent string
+  y:     '80%'
 });
 ```
 
-### Creation Options
+### Options
 
 Option           | Default    | Description
 -----------------|------------|----------------------------------------------------------------------------------------------------
 `id`             | -          | **Required.** Unique name for this sprite.
-`key`            | -          | **Required.** Image key from `config.images`. Pass an array (`['frame1','frame2']`) for animation.
+`image`          | -          | **Required.** Image name from `config.images`. Pass an array (`['frame1','frame2']`) for animation.
 `x`              | -          | **Required.** Horizontal position in pixels or `'50%'`.
 `y`              | -          | **Required.** Vertical position in pixels or `'50%'`.
 `w`              | auto       | Width in pixels or percent. Inferred from the image if omitted.
@@ -191,7 +186,7 @@ Option           | Default    | Description
 `clipHeight`     | `null`     | Limit the drawn height in pixels - useful for health/fill bars.
 `clipFrom`       | `'bottom'` | Which end to clip from: `'top'` or `'bottom'`.
 
-### Sprite Properties
+### Properties
 
 Property    | Description
 ------------|-----------------------------------------------------------------------------------------
@@ -202,10 +197,10 @@ Property    | Description
 `frame`     | Override the current animation frame index. Set to `null` to let `animate()` control it.
 `destroyed` | `true` after `destroy()` has been called. Read-only.
 
-### Sprite Methods
+### Methods
 
 #### `sprite.draw(ctx)`
-Draws the sprite. Call inside your `draw` handler - `ctx` is `this`.
+Draws the sprite manually. Only needed when using a custom `draw` handler - for example, to control layer order alongside backgrounds or text.
 
 ```js
 punter.on('draw', function () {
@@ -235,12 +230,12 @@ player.center(0, -50);  // centred, 50px above the middle
 Use `sprite.centerX()` or `sprite.centerY()` to centre on one axis only.
 
 #### `sprite.animate(delayMs)`
-Advance to the next animation frame. Requires `key` to be an array of image keys.
+Advance to the next animation frame. Requires `image` to be an array of image names.
 
 ```js
 var run = punter.createSprite({
-  id:  'runner',
-  key: ['run1', 'run2', 'run3'],
+  id:    'runner',
+  image: ['run1', 'run2', 'run3'],
   x: 100, y: 200
 });
 

package/games/breakout.html

@@ -0,0 +1,297 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Breakout</title>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+
+      html, body {
+        width: 100%;
+        height: 100%;
+        background: #1e2230;
+        overflow: hidden;
+      }
+
+      canvas {
+        display: block;
+        cursor: none;
+        background: #1b2125;
+      }
+    </style>
+    <script src="../punter.js"></script>
+  </head>
+  <body>
+    <canvas id="game"></canvas>
+    <script>
+
+      // =========================================================
+      // COLORS
+      // =========================================================
+      var COLOR_TEXT = '#f5c518';
+      var COLOR_DIM  = '#2c3033';
+
+      // One image name per brick row (matches the images/ folder)
+      var BRICK_IMAGES = ['brickRed', 'brickOrange', 'brickYellow', 'brickGreen', 'brickBlue'];
+
+      // =========================================================
+      // HELPERS
+      // =========================================================
+      var DPR = punter.dpr;
+
+      function px(n) {
+        return n * DPR;
+      }
+
+      function clamp(value, min, max) {
+        return Math.max(min, Math.min(value, max));
+      }
+
+      // =========================================================
+      // GAME SETTINGS
+      // =========================================================
+      var PADDLE_W      = px(90);
+      var PADDLE_H      = px(14);
+      var BALL_SIZE     = px(16);
+      var BALL_SPEED    = px(6);
+      var PADDLE_SPEED  = px(8);
+      var BRICK_ROWS    = 5;
+      var BRICK_COLS    = 8;
+      var BRICK_H       = px(22);
+      var BRICK_PAD     = px(6);
+      var PADDLE_OFFSET = px(40); // distance from bottom
+
+      // =========================================================
+      // GAME STATE
+      // =========================================================
+      var paddleSprite, ballSprite, bricks, ballVel;
+      var score, lives, gameOver, won;
+
+      // =========================================================
+      // SETUP
+      // =========================================================
+      punter.setup({
+        canvas: '#game',
+        images: {
+          ball:        '../images/breakout/ball.png',
+          paddle:      '../images/breakout/paddle.png',
+          brickRed:    '../images/breakout/brick-red.png',
+          brickOrange: '../images/breakout/brick-orange.png',
+          brickYellow: '../images/breakout/brick-yellow.png',
+          brickGreen:  '../images/breakout/brick-green.png',
+          brickBlue:   '../images/breakout/brick-blue.png'
+        },
+        sounds: {
+          bounce: '../sounds/beep6.mp3',
+          brick:  '../sounds/click1.mp3',
+          die:    '../sounds/error2.mp3',
+          win:    '../sounds/fanfare1.mp3'
+        }
+      });
+
+      // =========================================================
+      // SCENE: play
+      // =========================================================
+      punter.scene('play', function () {
+
+        var w = punter.width;
+        var h = punter.height;
+
+        // Create the paddle and ball sprites
+        paddleSprite = punter.createSprite({ id: 'paddle', image: 'paddle', x: w / 2 - PADDLE_W / 2, y: h - PADDLE_OFFSET, w: PADDLE_W, h: PADDLE_H });
+        ballSprite   = punter.createSprite({ id: 'ball',   image: 'ball',   x: w / 2, y: h / 2, w: BALL_SIZE, h: BALL_SIZE });
+
+        // Set up game state for the first time
+        bricks   = [];
+        ballVel  = { x: 0, y: 0 };
+        score    = 0;
+        lives    = 3;
+        gameOver = false;
+        won      = false;
+
+        buildBricks();
+        resetBall();
+
+        // -------------------------------------------------------
+        // UPDATE — game logic, runs ~60 times per second
+        // -------------------------------------------------------
+        punter.on('update', function () {
+
+          // Restart on any input when the game has ended
+          if (gameOver || won) {
+            if (punter.keys[' '] || punter.mouse.clicked) {
+              punter.clearInput();
+              resetGame();
+            }
+            return;
+          }
+
+          var w = punter.width;
+          var h = punter.height;
+
+          // Keep paddle pinned to the correct Y on resize
+          paddleSprite.y = h - PADDLE_OFFSET;
+
+          // Paddle: keyboard
+          if (punter.keys['ArrowLeft']  || punter.keys['a']) paddleSprite.moveX(-PADDLE_SPEED);
+          if (punter.keys['ArrowRight'] || punter.keys['d']) paddleSprite.moveX(PADDLE_SPEED);
+
+          // Paddle: tap / click
+          if (punter.mouse.clicked) {
+            paddleSprite.x = punter.mouse.x - PADDLE_W / 2;
+          }
+
+          paddleSprite.x = clamp(paddleSprite.x, 0, w - PADDLE_W);
+
+          // Move ball
+          ballSprite.moveX(ballVel.x);
+          ballSprite.moveY(ballVel.y);
+
+          // Bounce off side walls and ceiling
+          if (ballSprite.x <= 0)               { ballSprite.x = 0;               ballVel.x =  Math.abs(ballVel.x); }
+          if (ballSprite.x + BALL_SIZE >= w)   { ballSprite.x = w - BALL_SIZE;   ballVel.x = -Math.abs(ballVel.x); }
+          if (ballSprite.y <= 0)               { ballSprite.y = 0;               ballVel.y =  Math.abs(ballVel.y); }
+
+          // Ball falls off the bottom — lose a life
+          if (ballSprite.y > h) {
+            lives--;
+            punter.playSound('die');
+            if (lives <= 0) { gameOver = true; punter.clearInput(); return; }
+            resetBall();
+            return;
+          }
+
+          // Ball vs paddle
+          if (ballVel.y > 0 && ballSprite.isCollidingWith(paddleSprite)) {
+            var hit   = (ballSprite.x + BALL_SIZE / 2 - paddleSprite.x) / PADDLE_W;
+            ballVel.x = (hit - 0.5) * BALL_SPEED * 2.5;
+            ballVel.y = -Math.abs(ballVel.y);
+            punter.playSound('bounce');
+          }
+
+          // Ball vs bricks
+          for (var i = 0; i < bricks.length; i++) {
+            if (ballSprite.isCollidingWith(bricks[i])) {
+              bricks[i].destroy();
+              bricks.splice(i, 1);
+              ballVel.y = -ballVel.y;
+              score += 10;
+              punter.playSound('brick');
+              break; // only hit one brick per frame
+            }
+          }
+
+          if (bricks.length === 0) {
+            won = true;
+            punter.playSound('win');
+            punter.clearInput();
+          }
+        });
+
+        // -------------------------------------------------------
+        // DRAW — runs after sprites are drawn; used for HUD and overlays
+        // -------------------------------------------------------
+        punter.on('draw', function () {
+          var ctx = this; // punter passes the canvas 2D context as 'this'
+          var w   = punter.width;
+          var h   = punter.height;
+
+          // HUD: score and lives
+          ctx.fillStyle    = COLOR_TEXT;
+          ctx.font         = 'bold ' + px(18) + 'px monospace';
+          ctx.textBaseline = 'top';
+          ctx.textAlign    = 'left';
+          ctx.fillText('Score: ' + score, px(12), px(12));
+          ctx.textAlign = 'right';
+          ctx.fillText('Lives: ' + lives, w - px(12), px(12));
+
+          // Controls hint
+          ctx.fillStyle    = COLOR_DIM;
+          ctx.font         = px(14) + 'px monospace';
+          ctx.textBaseline = 'bottom';
+          ctx.textAlign    = 'center';
+          ctx.fillText('Arrow keys or A / D  ·  tap to move', w / 2, h - px(12));
+
+          // Game over / win overlay
+          if (gameOver || won) {
+            ctx.fillStyle = 'rgba(0,0,0,0.55)';
+            ctx.fillRect(0, 0, w, h);
+            ctx.fillStyle    = COLOR_TEXT;
+            ctx.font         = 'bold ' + px(40) + 'px monospace';
+            ctx.textAlign    = 'center';
+            ctx.textBaseline = 'middle';
+            ctx.fillText(won ? 'YOU WIN!' : 'GAME OVER', w / 2, h / 2 - px(24));
+            ctx.font = px(18) + 'px monospace';
+            ctx.fillText('Press SPACE or tap to restart', w / 2, h / 2 + px(24));
+          }
+        });
+      });
+
+      /**
+       * Creates a fresh grid of brick sprites.
+       * Each brick is a sprite the engine draws automatically.
+       */
+      function buildBricks() {
+        var w      = punter.width;
+        var brickW = (w - BRICK_PAD * (BRICK_COLS + 1)) / BRICK_COLS;
+
+        for (var r = 0; r < BRICK_ROWS; r++) {
+          for (var c = 0; c < BRICK_COLS; c++) {
+            bricks.push(punter.createSprite({
+              id:    'brick-' + r + '-' + c,
+              image: BRICK_IMAGES[r],
+              x:   BRICK_PAD + c * (brickW + BRICK_PAD),
+              y:   px(50)    + r * (BRICK_H + BRICK_PAD),
+              w:   brickW,
+              h:   BRICK_H
+            }));
+          }
+        }
+      }
+
+      /**
+       * Puts the ball back in the centre aimed upward.
+       */
+      function resetBall() {
+        ballSprite.x = punter.width  / 2 - BALL_SIZE / 2;
+        ballSprite.y = punter.height / 2;
+        ballVel.x    = (Math.random() < 0.5 ? -1 : 1) * BALL_SPEED * 0.6;
+        ballVel.y    = -BALL_SPEED;
+      }
+
+      /**
+       * Destroys any remaining bricks and resets everything for a new game.
+       */
+      function resetGame() {
+        for (var i = 0; i < bricks.length; i++) { bricks[i].destroy(); }
+        bricks = [];
+
+        score    = 0;
+        lives    = 3;
+        gameOver = false;
+        won      = false;
+
+        paddleSprite.x = punter.width  / 2 - PADDLE_W / 2;
+        paddleSprite.y = punter.height - PADDLE_OFFSET;
+
+        buildBricks();
+        resetBall();
+      }
+
+      // Reposition paddle on resize
+      punter.on('resize', function () {
+        if (!paddleSprite) return;
+        paddleSprite.x = clamp(paddleSprite.x, 0, punter.width - PADDLE_W);
+        paddleSprite.y = punter.height - PADDLE_OFFSET;
+      });
+
+      punter.go('play');
+
+    </script>
+  </body>
+</html>

package/games/pong.html

@@ -20,6 +20,8 @@
 
       canvas {
         display: block;
+        cursor: none;
+        background: #1b2125;
       }
     </style>
     <script src="../punter.js"></script>
@@ -67,10 +69,11 @@
       // =========================================================
       // GAME SETTINGS
       // =========================================================
-      var MARGIN         = px(40); // gap between paddle and screen edge
-      var PADDLE_W       = px(14);
-      var PADDLE_H       = px(90);
-      var BALL_SIZE      = px(14);
+      var MARGIN         = px(20); // gap between paddle and screen edge
+      var PADDLE_W       = px(14); // width of paddle
+      var PADDLE_H       = px(90); // height of paddle
+      var AI_PADDLE_H    = px(90);
+      var BALL_SIZE      = px(24);
       var PADDLE_SPEED   = px(7);
       var AI_SPEED       = px(5);
       var BALL_SPEED     = px(5);
@@ -96,8 +99,12 @@
       punter.setup({
         canvas: '#game',
         images: {
-          paddle: '../images/pong/sprites/paddle.png',
-          ball:   '../images/pong/sprites/ball.png'
+          paddle: '../images/pong/paddle.png',
+          ball:   '../images/pong/ball.png'
+        },
+        sounds: {
+          bounce: '../sounds/beep6.mp3',
+          die: '../sounds/error2.mp3'
         }
       });
 
@@ -106,11 +113,13 @@
       // =========================================================
       punter.scene('play', function () {
 
+        score = { player: 0, ai: 0 };
+
         // Create the three sprites punter.js will draw each frame.
         // w/h set the draw size; the image is scaled to fit automatically.
-        playerSprite = punter.createSprite({ id: 'player', key: 'paddle', x: 0, y: 0, w: PADDLE_W, h: PADDLE_H });
-        aiSprite     = punter.createSprite({ id: 'ai',     key: 'paddle', x: 0, y: 0, w: PADDLE_W, h: PADDLE_H });
-        ballSprite   = punter.createSprite({ id: 'ball',   key: 'ball',   x: 0, y: 0, w: BALL_SIZE, h: BALL_SIZE });
+        playerSprite = punter.createSprite({ id: 'player', image: 'paddle', x: 0, y: 0, w: PADDLE_W, h: PADDLE_H });
+        aiSprite     = punter.createSprite({ id: 'ai',     image: 'paddle', x: 0, y: 0, w: PADDLE_W, h: AI_PADDLE_H });
+        ballSprite   = punter.createSprite({ id: 'ball',   image: 'ball',   x: 0, y: 0, w: BALL_SIZE, h: BALL_SIZE });
 
         // Place everything in the correct starting position
         resetPositions();
@@ -126,8 +135,8 @@
           aiSprite.x = w - MARGIN - PADDLE_W;
 
           // --- Player: keyboard ---
-          if (punter.keys['ArrowUp']   || punter.keys['w']) playerSprite.y -= PADDLE_SPEED;
-          if (punter.keys['ArrowDown'] || punter.keys['s']) playerSprite.y += PADDLE_SPEED;
+          if (punter.keys['ArrowUp']   || punter.keys['w']) playerSprite.moveY(-PADDLE_SPEED);
+          if (punter.keys['ArrowDown'] || punter.keys['s']) playerSprite.moveY(PADDLE_SPEED);
 
           // --- Player: tap / click ---
           if (punter.mouse.clicked) {
@@ -139,13 +148,13 @@
 
           // --- AI: follow the ball ---
           var aiCenterY = aiSprite.y + PADDLE_H / 2;
-          if (ballSprite.y < aiCenterY - 10) aiSprite.y -= AI_SPEED;
-          if (ballSprite.y > aiCenterY + 10) aiSprite.y += AI_SPEED;
+          if (ballSprite.y < aiCenterY - 10) aiSprite.moveY(-AI_SPEED);
+          if (ballSprite.y > aiCenterY + 10) aiSprite.moveY(AI_SPEED);
           aiSprite.y = clamp(aiSprite.y, 0, h - PADDLE_H);
 
           // --- Move the ball ---
-          ballSprite.x += ballVel.x;
-          ballSprite.y += ballVel.y;
+          ballSprite.moveX(ballVel.x);
+          ballSprite.moveY(ballVel.y);
 
           // Bounce off top and bottom walls
           if (ballSprite.y <= 0)              { ballVel.y =  Math.abs(ballVel.y); ballSprite.y = 0; }
@@ -159,6 +168,8 @@
             // Where on the paddle the ball hit: 0 = top edge, 1 = bottom edge, 0.5 = centre (flat return)
             var playerHit = (ballSprite.y + BALL_SIZE / 2 - playerSprite.y) / PADDLE_H;
             ballVel.y = (playerHit - 0.5) * BALL_SPEED * 2;
+
+            punter.playSound('bounce');
           }
 
           // --- Collision: ball hits AI paddle ---
@@ -169,6 +180,8 @@
             // Where on the paddle the ball hit: 0 = top edge, 1 = bottom edge, 0.5 = centre (flat return)
             var aiHit = (ballSprite.y + BALL_SIZE / 2 - aiSprite.y) / PADDLE_H;
             ballVel.y = (aiHit - 0.5) * BALL_SPEED * 2;
+
+            punter.playSound('bounce');
           }
 
           // Cap ball speed so the game stays playable
@@ -176,8 +189,17 @@
           if (ballVel.x < -MAX_BALL_SPEED) ballVel.x = -MAX_BALL_SPEED;
 
           // --- Scoring ---
-          if (ballSprite.x + BALL_SIZE < 0) { score.ai++;     resetBall(SERVE_RIGHT); }
-          if (ballSprite.x > w)             { score.player++; resetBall(SERVE_LEFT);  }
+          if (ballSprite.x + BALL_SIZE < 0) {
+            score.ai++;
+            punter.playSound('die');
+            resetBall(SERVE_RIGHT);
+          }
+
+          if (ballSprite.x > w) {
+            score.player++;
+            punter.playSound('die');
+            resetBall(SERVE_LEFT);
+          }
         });
 
         // -------------------------------------------------------
@@ -188,10 +210,6 @@
           var w   = punter.width;
           var h   = punter.height;
 
-          // Background
-          ctx.fillStyle = COLOR_BG;
-          ctx.fillRect(0, 0, w, h);
-
           // Dashed centre line
           ctx.setLineDash([px(8), px(10)]);
           ctx.strokeStyle = COLOR_NET;
@@ -202,11 +220,6 @@
           ctx.stroke();
           ctx.setLineDash([]);
 
-          // Sprites — punter.js scales and draws the PNG images
-          playerSprite.draw(ctx);
-          aiSprite.draw(ctx);
-          ballSprite.draw(ctx);
-
           // Scores
           ctx.fillStyle    = COLOR_SCORE;
           ctx.font         = 'bold ' + px(48) + 'px monospace';
@@ -260,13 +273,7 @@
         resetPositions();
       });
 
-      // =========================================================
-      // START — go to the play scene once everything is loaded
-      // =========================================================
-      punter.on('ready', function () {
-        score = { player: 0, ai: 0 };
-        punter.go('play');
-      });
+      punter.go('play');
 
     </script>
   </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "punter.js",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A simple, dependency-free 2D game engine for the browser. No build step, no frameworks - just one script tag.",
   "main": "punter.js",
   "directories": {