create-okona-game 0.3.0 → 0.5.0

package/README.md

@@ -4,8 +4,8 @@
 npm create okona-game my-party-game
 ```
 
-Scaffolds a phone-controlled multiplayer HTML5 game for [Okona](https://okonaonline.com): a lobby that shows the join code until the room is full, six seats with names and colours pushed to each phone, the frame loop, and a `game.js` with `start` / `update` / `draw` hooks holding a small sample (a coin-grab race) to replace with your game.
+Scaffolds a phone-controlled HTML5 game for [Okona](https://okonaonline.com): a lobby built to the [Okona game standards](https://okonaonline.com/developers/docs.html#standards) (a controller joins by pressing A, any joined player starts, the game freezes while the Okona menu is open, no join code: Okona shows it), six seats with names and colours pushed to each phone, the frame loop, and a `game.js` with `start` / `update` / `draw` hooks holding a small sample (a coin-grab race) to replace with your game.
 
-Open `index.html` in a browser and the keyboard is P1 — no build step, no `package.json`. Ship it with the [`okona` CLI](https://www.npmjs.com/package/okona-cli) (`npx okona-cli`, Node 18.17+): push to your sandbox first to try it with real phones, then submit it to the Okona catalog; once it's approved, players join by scanning the code on the TV.
+Open `index.html` in a browser and the keyboard is P1 — no build step, no `package.json`. Ship it with the [`okona` CLI](https://www.npmjs.com/package/okona-cli) (`npx okona-cli`, Node 18.17+): push to your sandbox first to try it with real phones, then submit it to the Okona catalog; once it's approved, players join in the Okona app with a phone or a gamepad.
 
 Zero dependencies. Docs: https://okonaonline.com/developers/docs.html#html5 · SDK reference: https://okonaonline.com/developers/docs.html#js-sdk

package/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// create-okona-game — scaffold a phone-controlled multiplayer game for Okona.
+// create-okona-game — scaffold a phone-controlled game for Okona.
 //
 //   npm create okona-game my-game        (or: npx create-okona-game my-game)
 //

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-okona-game",
-  "version": "0.3.0",
-  "description": "Scaffold a phone-controlled multiplayer HTML5 game for Okona: lobby, join code, six seats, and a game.js to make yours.",
+  "version": "0.5.0",
+  "description": "Scaffold a phone-controlled HTML5 game for Okona: lobby, join code, six seats, and a game.js to make yours.",
   "license": "MIT",
   "homepage": "https://okonaonline.com/developers/docs.html#html5",
   "bugs": {

package/template/README.md

@@ -1,8 +1,8 @@
 # {{NAME}}
 
-A phone-controlled multiplayer game for [Okona](https://okonaonline.com). Up to six people scan the code on screen and their phones become the gamepads.
+A multiplayer game for [Okona](https://okonaonline.com). Up to six people play with their phones or gamepads; each joins by pressing A.
 
-- `index.html` — the lobby, join code, seats and frame loop (rarely needs changes)
+- `index.html` — the lobby, seats and frame loop, built to the [Okona game standards](https://okonaonline.com/developers/docs.html#standards): A joins, any joined player starts, the game freezes while the Okona menu is open, and it draws no join code: Okona shows it (rarely needs changes)
 - `game.js` — **your game**: `start`, `update`, `draw`, and the join/leave/park/resume hooks
 - `icon.png` — the icon shown in the Okona portal (replace it)
 - `okona.json` — the catalog record: title, description, genre, keywords, the icon, screenshots. `okona push` syncs it
@@ -24,4 +24,4 @@ npx okona-cli push . --publish      # submit for review: Okona approves it into
 
 Screenshots: put up to six images in a `shots/` folder and add `"screenshots": "shots"` to `okona.json` — the next push uploads them in name order (1.png, 2.png, …). `npx okona-cli update --title "…"` changes a field without a build upload; `npx okona-cli game <id>` shows what the portal has.
 
-Docs: https://okonaonline.com/developers/docs.html#html5 · SDK reference: https://okonaonline.com/developers/docs.html#js-sdk · The contract in one line: `Okona.pads()`, `Okona.on('join'|'leave'|'park'|'resume'|'pairing')`, `Okona.drawQr()`, `Okona.players.setIdentity()`, `Okona.rumble()`, `Okona.track()`.
+Docs: https://okonaonline.com/developers/docs.html#html5 · SDK reference: https://okonaonline.com/developers/docs.html#js-sdk · The contract in one line: `Okona.pads()`, `Okona.on('join'|'leave'|'park'|'resume'|'menu')`, `Okona.menuOpen`, `Okona.players.setIdentity()`, `Okona.rumble()`, `Okona.track()`.

package/template/game.js

@@ -1,12 +1,15 @@
-// {{NAME}} — the game. index.html runs the lobby, the join code, the seats
+// {{NAME}} — the game. index.html runs the lobby (A joins), the seats
 // and the frame loop; it calls the hooks below. Replace the sample (a
 // coin-grab race) with your game. Everything is plain canvas — bring any
 // library you like, but bundle it (a venue's network may block CDNs).
 //
 // Coordinates: a 1920×1080 logical screen; index.html scales it to fit.
 // Pads: pad.axes.lx/ly (−1..1, +Y down), pad.buttons.a/b/x/y/lb/rb/lt/rt/
-//       select/start/l3/r3/up/down/left/right/home, pad.justPressed('a'),
+//       select/l3/r3/up/down/left/right, pad.justPressed('a') (start + home are
+//       Okona's: they never reach the game), player.joined (pressed A: a player),
 //       pad.triggers.lt/rt (0..1), pad.parked (controller away — seat held).
+// Saves: Okona.save.get/set keep data for the player's account, on any screen
+//       (the sample keeps its best round); read it after Okona.ready.
 var Game = {
   title: '{{NAME}}',
   subtitle: 'Grab the coins. Most coins after 45 seconds wins.',
@@ -17,14 +20,15 @@ var Game = {
   ROUND_SECONDS: 45,
 
   // ---- lifecycle ------------------------------------------------------------
-  onJoin: function (player, pad) {
+  onJoin: function (player, pad) {       // the controller pressed A: now a player
     player.x = 300 + player.index * 260; player.y = 540; player.vx = 0; player.vy = 0;
   },
-  onLeave: function (player, pad) {},
-  onPark: function (player, pad) {},     // controller went away; seat held — the sample just stops moving them
+  onLeave: function (player, pad) {},   // gone for good (seat given away, or still away when the round ended)
+  onPark: function (player, pad) {},     // controller went away; seat + score held until the round ends — the sample freezes them
   onResume: function (player, pad) {},
 
   start: function (players, pads) {
+    this.best = Okona.save.get('best', 0);   // the best round on this account, kept by Okona
     this.coins = [];
     for (var i = 0; i < 10; i++) this.spawnCoin();
     players.forEach(function (p) { p.x = 300 + p.index * 260; p.y = 540; p.vx = 0; p.vy = 0; });
@@ -38,7 +42,7 @@ var Game = {
   update: function (dt, players, pads, elapsed) {
     for (var i = 0; i < 6; i++) {
       var pad = pads[i], p = players[i];
-      if (!pad.connected || pad.parked) continue;
+      if (!p.joined || !pad.connected || pad.parked) continue;   // only players who are here
       var speed = pad.buttons.a ? 900 : 600;
       p.vx += pad.axes.lx * speed * dt * 6; p.vy += pad.axes.ly * speed * dt * 6;
       p.vx *= 0.88; p.vy *= 0.88;
@@ -54,7 +58,16 @@ var Game = {
         }
       }
     }
-    return elapsed >= this.ROUND_SECONDS;
+    var over = elapsed >= this.ROUND_SECONDS;
+    if (over) this.keepBest(players);
+    return over;
+  },
+
+  // A new best round goes in the save (it plays on fine if the save is unavailable).
+  keepBest: function (players) {
+    var top = 0;
+    players.forEach(function (p) { if (p.joined && p.score > top) top = p.score; });
+    if (top > this.best) { this.best = top; Okona.save.set('best', top); Okona.save.flush(); }
   },
 
   draw: function (ctx, players, pads, W, H) {
@@ -68,7 +81,7 @@ var Game = {
     // players
     for (var i = 0; i < 6; i++) {
       var pad = pads[i], p = players[i];
-      if (!pad.connected) continue;
+      if (!p.joined) continue;
       ctx.globalAlpha = pad.parked ? 0.3 : 1;
       ctx.fillStyle = p.color;
       ctx.beginPath(); ctx.arc(p.x, p.y, 40, 0, Math.PI * 2); ctx.fill();
@@ -79,5 +92,7 @@ var Game = {
     // HUD: big type — it is read from across the room
     ctx.fillStyle = '#E8A525'; ctx.textAlign = 'left'; ctx.font = 'bold 40px system-ui, sans-serif';
     ctx.fillText(this.title, 70, 100);
+    ctx.fillStyle = '#A0B4C8'; ctx.textAlign = 'right';
+    ctx.fillText('Best ' + this.best, W - 70, 100);
   }
 };

package/template/index.html

@@ -3,9 +3,13 @@
   {{NAME}} — an Okona game.
 
   This file is the LOBBY and the game loop; your game lives in game.js.
-  Six phones scan the code on screen and become gamepads. Submit it to the
-  Okona catalog when it's ready. Open this file in a browser and the keyboard is P1
-  (WASD/arrows, Space = A, Shift = B) so you can play what you build.
+  Six phones or gamepads connect through Okona, and each becomes a player by
+  pressing A. It follows the Okona game standards
+  (https://okonaonline.com/developers/docs.html#standards): A joins, any joined
+  player starts, the game freezes while the Okona menu is open, and it draws
+  no join code: Okona shows it, in the Okona app and in the sandbox.
+  Open this file in a browser and the keyboard is P1 (WASD/arrows,
+  Space = A, Shift = B) so you can play what you build.
 
   Submit:  npx okona-cli create && npx okona-cli push . --publish   (okona.json holds the title, icon, screenshots)
   Docs:    https://okonaonline.com/developers/docs.html#html5
@@ -22,7 +26,7 @@
 </head>
 <body>
 <canvas id="screen"></canvas>
-<!-- The Okona SDK: phones, pairing code, identity, rumble, analytics. -->
+<!-- The Okona SDK: phones and gamepads, identity, rumble, analytics. -->
 <script src="https://okonaonline.com/sdk/okona.js"></script>
 <script src="game.js"></script>
 <script>
@@ -41,54 +45,46 @@
   resize();
 
   // ---- players ------------------------------------------------------------
-  // Six seats. Okona holds a seat while its controller is away (pad.parked),
-  // so a player who closes their phone gets the same seat back.
+  // Six seats. A controller that connects is only CONNECTED; it becomes a
+  // player (joined) when it presses A. Okona holds a seat while its
+  // controller is away (pad.parked), so a player who closes their phone gets
+  // the same seat, and keeps their score, when they come back.
   var PALETTE = ['#E8A525', '#4FC3F7', '#81C784', '#F06292', '#BA68C8', '#FF8A65'];
   var players = [];
-  for (var i = 0; i < 6; i++) players.push({ index: i, color: PALETTE[i], name: 'P' + (i + 1), score: 0 });
+  for (var i = 0; i < 6; i++) players.push({ index: i, color: PALETTE[i], name: 'P' + (i + 1), score: 0, joined: false });
 
-  Okona.on('join', function (pad) {
-    var p = players[pad.index];
+  function joinPlayer(p, pad) {
+    p.joined = true;
+    p.score = 0;
     // What this player sees on their phone: name, emoji or image, accent.
     Okona.players.setIdentity(pad, { name: p.name, icon: Game.icons[pad.index] || '🎮', accent: p.color });
     Game.onJoin(p, pad);
-  });
-  Okona.on('leave', function (pad) { Game.onLeave(players[pad.index], pad); });
-  Okona.on('park', function (pad) { Game.onPark(players[pad.index], pad); });
-  Okona.on('resume', function (pad) { Game.onResume(players[pad.index], pad); });
+  }
+  function dropPlayer(p, pad) {
+    if (!p.joined) return;
+    p.joined = false;
+    Okona.players.clearIdentity(pad);
+    Game.onLeave(p, pad);
+  }
 
-  // ---- the pairing code ---------------------------------------------------
-  var qr = document.createElement('canvas');
-  qr.width = qr.height = 512;
-  Okona.on('pairing', function () { Okona.drawQr(qr); });
+  // 'leave' = the seat went to another controller: that player is gone.
+  Okona.on('leave', function (pad) { dropPlayer(players[pad.index], pad); });
+  Okona.on('park', function (pad) { if (players[pad.index].joined) Game.onPark(players[pad.index], pad); });
+  Okona.on('resume', function (pad) { if (players[pad.index].joined) Game.onResume(players[pad.index], pad); });
+
+  // No join code here: Okona shows it (the Okona app's Scan to play and
+  // Controllers; the sandbox's join code, which Start brings back).
 
   // ---- lobby → playing → results -----------------------------------------
   var state = 'lobby';
-  var startedAt = 0;
+  var elapsed = 0;                         // round time; stops while the Okona menu is open
 
-  function connected(pads) {
+  function count(pads, joinedOnly) {
     var n = 0;
-    for (var i = 0; i < pads.length; i++) if (pads[i].connected) n++;
+    for (var i = 0; i < pads.length; i++) if (pads[i].connected && (!joinedOnly || players[i].joined)) n++;
     return n;
   }
 
-  function drawJoinPanel(pads) {
-    var n = connected(pads);
-    if (n >= 6) return;
-    var size = state === 'lobby' ? 420 : 200;
-    var x = W - size - 70, y = 70;
-    ctx.fillStyle = '#FFFFFF';
-    ctx.fillRect(x - 16, y - 16, size + 32, size + 32);
-    ctx.drawImage(qr, x, y, size, size);
-    ctx.fillStyle = '#FFFFFF';
-    ctx.textAlign = 'center';
-    ctx.font = 'bold ' + (state === 'lobby' ? 40 : 24) + 'px system-ui, sans-serif';
-    ctx.fillText('Scan to join', x + size / 2, y + size + 66);
-    ctx.fillStyle = '#A0B4C8';
-    ctx.font = (state === 'lobby' ? 22 : 16) + 'px system-ui, sans-serif';
-    ctx.fillText(Okona.pairing.caption || (Okona.mode === 'standalone' ? 'Keyboard: WASD + Space' : ''), x + size / 2, y + size + 98);
-  }
-
   function drawLobby(pads) {
     ctx.fillStyle = '#E8A525';
     ctx.textAlign = 'left';
@@ -99,14 +95,22 @@
     ctx.fillText(Game.subtitle, 80, 205);
     for (var i = 0; i < 6; i++) {
       var p = players[i], pad = pads[i];
-      ctx.fillStyle = pad.connected ? p.color : '#2A4A6F';
+      var label = p.joined ? '● ' + p.name + (pad.parked ? '  away' : '')
+        : pad.connected ? '○ ' + p.name + '  press A to join'
+        : '○ ' + p.name + '  open';
+      ctx.fillStyle = p.joined ? p.color : (pad.connected ? '#A0B4C8' : '#2A4A6F');
       ctx.font = 'bold 34px system-ui, sans-serif';
-      ctx.fillText((pad.connected ? '● ' : '○ ') + p.name + (pad.connected ? '' : '  open'), 80, 300 + i * 56);
+      ctx.fillText(label, 80, 300 + i * 56);
     }
-    var n = connected(pads);
+    var n = count(pads, true);
     ctx.fillStyle = '#FFFFFF';
     ctx.font = '30px system-ui, sans-serif';
-    ctx.fillText(n === 0 ? 'Waiting for players…' : (n < Game.minPlayers ? 'Need ' + Game.minPlayers + ' to start' : 'P1: press A to start'), 80, 680);
+    ctx.fillText(n === 0 ? (count(pads, false) ? 'Press A to join' : 'Waiting for players…')
+      : (n < Game.minPlayers ? 'Need ' + Game.minPlayers + ' to start' : 'Press A to start · B to leave'), 80, 680);
+    if (Okona.mode === 'standalone') {
+      ctx.fillStyle = '#A0B4C8';
+      ctx.fillText('Keyboard: WASD + Space', 80, 730);
+    }
   }
 
   function drawResults() {
@@ -125,7 +129,7 @@
     }
     ctx.fillStyle = '#A0B4C8';
     ctx.font = '30px system-ui, sans-serif';
-    ctx.fillText('P1: press A to play again', W / 2, 900);
+    ctx.fillText('Press A to play again', W / 2, 900);
   }
 
   var last = performance.now();
@@ -133,7 +137,25 @@
     var dt = Math.min(0.05, (now - last) / 1000);
     last = now;
     var pads = Okona.pads();               // exactly once per frame — a second call (or Okona.pad(i)) resets justPressed()
-    for (var i = 0; i < 6; i++) if (pads[i].connected) players[i].joined = true;
+    var menuOpen = Okona.menuOpen === true;
+
+    // A connected controller becomes a player by pressing A (drop-in: in the
+    // lobby or mid-round). That press only joins; it never also starts the round.
+    var joinedNow = [];
+    for (var i = 0; i < 6; i++) {
+      var pad = pads[i], p = players[i];
+      if (!p.joined && pad.connected && !pad.parked && pad.justPressed('a') && !menuOpen) {
+        joinPlayer(p, pad);
+        joinedNow[i] = true;
+      }
+    }
+    // Any joined player who is here (never "P1 only": seat 1 may be empty).
+    function pressed(button) {
+      for (var j = 0; j < 6; j++) {
+        if (!joinedNow[j] && players[j].joined && pads[j].connected && !pads[j].parked && pads[j].justPressed(button)) return true;
+      }
+      return false;
+    }
 
     var sx = canvas.width / W, sy = canvas.height / H;
     ctx.setTransform(sx, 0, 0, sy, 0, 0);
@@ -142,31 +164,41 @@
 
     if (state === 'lobby') {
       drawLobby(pads);
-      drawJoinPanel(pads);
-      if (connected(pads) >= Game.minPlayers && pads[0].justPressed('a')) {
-        players.forEach(function (p) { p.score = 0; });
-        Game.start(players, pads);
-        startedAt = now;
-        state = 'playing';
-        Okona.track('round_start', { players: connected(pads) });
+      if (!menuOpen) {
+        // Lobby: B leaves.
+        for (var k = 0; k < 6; k++) {
+          if (!joinedNow[k] && players[k].joined && pads[k].connected && pads[k].justPressed('b')) dropPlayer(players[k], pads[k]);
+        }
+        if (count(pads, true) >= Game.minPlayers && pressed('a')) {
+          players.forEach(function (pl) { pl.score = 0; });
+          Game.start(players, pads);
+          elapsed = 0;
+          state = 'playing';
+          Okona.track('round_start', { players: count(pads, true) });
+        }
       }
     } else if (state === 'playing') {
-      var over = Game.update(dt, players, pads, (now - startedAt) / 1000);
+      // While the Okona menu is open the round freezes: no update, no clock.
+      var over = false;
+      if (!menuOpen) {
+        elapsed += dt;
+        over = Game.update(dt, players, pads, elapsed);
+      }
       Game.draw(ctx, players, pads, W, H);
-      drawJoinPanel(pads);                 // late joiners are welcome
       if (over) {
         state = 'results';
-        Okona.track('round_end', { seconds: Math.round((now - startedAt) / 1000) });
+        Okona.track('round_end', { seconds: Math.round(elapsed) });
+        // The round is over: let go of anyone still away.
+        for (var m = 0; m < 6; m++) if (players[m].joined && (!pads[m].connected || pads[m].parked)) dropPlayer(players[m], pads[m]);
       }
     } else {
       drawResults();
-      if (pads[0].justPressed('a')) state = 'lobby';
+      if (!menuOpen && pressed('a')) state = 'lobby';
     }
     requestAnimationFrame(frame);
   }
 
   Okona.ready(function () {
-    Okona.drawQr(qr);
     requestAnimationFrame(frame);
   });
 })();

package/template/okona.json

@@ -1,6 +1,6 @@
 {
   "title": "{{NAME}}",
-  "description": "A phone-controlled multiplayer game. Scan the code on screen to play.",
+  "description": "A multiplayer party game for phones and gamepads. Drop in any time: press A to join.",
   "genre": "multiplayer-party",
   "keywords": ["party", "multiplayer"],
   "controller": "basic",