punter.js 1.0.1 → 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

@@ -14,7 +14,7 @@ A simple, dependency-free 2D game engine for the browser. No build step, no fram
 - [Install](#install)
 - [Run the Example](#run-the-example)
 - [How it Works](#how-it-works)
-- [punter.init()](#punter-init)
+- [Setup](#setup)
 - [Scenes](#scenes)
 - [Events](#events)
 - [Sprites](#sprites)
@@ -47,36 +47,35 @@ 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
 
 Every punter.js game follows the same three-step pattern:
 
-1. **init** - specify which canvas to use and which images/sounds to preload
+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
-punter.init({
+punter.setup({
   canvas: '#game',
-  sprites: { player: 'images/player.png' },
+  images: { player: 'images/player.png' },
   sounds:  { jump: 'sounds/jump.mp3' }
 });
 
 // 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,27 +83,21 @@ 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');
 ```
 
-## `punter.init()`
+## Setup
 
 Call this once at the start. The `ready` event fires once all assets have loaded.
 
 ```js
-punter.init({
+punter.setup({
   canvas: '#game',   // CSS selector or HTMLCanvasElement
   debug: false,      // true = show FPS and bounding boxes
-  sprites: {
+  images: {
     player: 'images/player.png',
     coin:   'images/coin.png'
   },
@@ -117,13 +110,13 @@ punter.init({
 Option    | Required | Description
 ----------|----------|------------------------------------------------
 `canvas`  | Yes      | CSS selector (`'#game'`) or `HTMLCanvasElement`
-`sprites` | No       | Key/path pairs of images to preload
+`images`  | No       | Key/path pairs of images to preload
 `sounds`  | No       | Key/path pairs of audio files to preload
 `debug`   | No       | Enables the debug overlay. Default: `false`
 
 ## 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.sprites`. 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
 });
 
@@ -294,7 +289,7 @@ punter.on('update', function () {
 ## Sound
 
 ```js
-punter.init({
+punter.setup({
   sounds: { jump: 'sounds/jump.mp3', music: 'sounds/theme.mp3' }
 });
 
@@ -419,7 +414,7 @@ html:not([data-punter-loading]) #loader { display: none; }
 ## Debug Mode
 
 ```js
-punter.init({ canvas: '#game', debug: true }); // enable at startup
+punter.setup({ canvas: '#game', debug: true }); // enable at startup
 punter.debug = true;                            // or toggle at runtime
 ```
 

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>