dotframe 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.6
+
+From the Craft Ones native port.
+
+- Native: mouse buttons read 0 while the window lacks input focus, so clicks in other apps no longer reach the game. The pointer position stays global, so aiming is unchanged.
+- Templates: `src/setup.ts` reads the pointer and touches with a hold-to-charge, release-to-act pattern (a charge meter while holding, a tone on release), on web and native. Each `game.ts` declares the `POINTER_BIT` a release sets.
+- Skills: the macos guide gains "Porting existing TypeScript" (what scriptc rejects and the fix for each, plus runtime traps such as structural coercion copying and out-of-range reads) and "Debugging a native crash" with lldb. Netplay warns against checksums built on `JSON.stringify`.
+
 ## 0.1.5
 
 - Native builds follow the entry's import graph instead of copying the game folder: relative imports that leave the game root and workspace packages that resolve to source are staged with their relative layout and rewritten to relative paths, so ports inside monorepos compile.

package/native/df_native.c

@@ -227,6 +227,8 @@ static void mouse_relative(double *nx, double *ny) {
 // Field 0 x, 1 y (normalized), 2 buttons (bit 0 left, bit 1 middle, bit 2 right).
 double df_mouse(int32_t field) {
   if (field == 2) {
+    // Clicks in other apps must not reach the game: buttons count only while the window has input focus.
+    if (!(SDL_GetWindowFlags(g_window) & SDL_WINDOW_INPUT_FOCUS)) return 0;
     SDL_MouseButtonFlags flags = SDL_GetGlobalMouseState(NULL, NULL);
     return (flags & SDL_BUTTON_LMASK ? 1 : 0) | (flags & SDL_BUTTON_MMASK ? 2 : 0) | (flags & SDL_BUTTON_RMASK ? 4 : 0);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotframe",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "TS-first game engine and agent-first CLI: one codebase for web, Discord, iOS and native binaries",
   "license": "MIT",
   "type": "module",

package/skill-data/macos/SKILL.md

@@ -39,6 +39,33 @@ scriptc compiles a subset of TypeScript. What tripped the templates:
 
 Run `dotframe build macos` early and after each feature: one scriptc error is a quick fix, ninety are a port.
 
+## Porting existing TypeScript
+
+What a real port (Craft Ones, 66 errors) hit, and the fix for each:
+
+| scriptc rejects | Do instead |
+|---|---|
+| `Object.assign(target, ...)` | Assign fields one by one |
+| `ArrayLike<T>` / `Iterable<T>` parameters | Take `T[]` |
+| `readonly T[]`, `.find`/`.filter` on readonly tuples, `for...of` over tuples | Plain arrays (`T[]`), indexed loops |
+| Destructuring an `unknown` network payload | Narrow field by field with `typeof` checks |
+| Non-literal index into a tuple | Make it an array |
+| Dynamic keyed reads on a record whose entries have different shapes | Give every entry the same shape (optional fields), or a `switch` |
+| `string[i]` | `s.charAt(i)` or `s.charCodeAt(i)` |
+| `Number.parseInt` in a static build | `parseInt` or `Math.trunc(Number(s))` |
+| `++`/`--` inside an expression | Its own statement |
+| `satisfies Record<K, Record<string, T>>` | A plain type annotation |
+
+Runtime traps (compile clean, fail when run):
+
+- **Structural coercion copies.** Passing a class instance, or a wider record, to a parameter typed as a narrower structural type passes a copy: the callee's writes to scalar fields are lost (arrays inside still alias). In Craft Ones every projectile froze mid-flight. Pass the exact type, or return the updated record and copy it back. Reported to scriptc.
+- **Out-of-range reads.** `rows[y - 1]?.[x]` typed as `string` but `undefined` at runtime crashes with "undefined is not representable in the target union". Bounds-check before reading.
+- **`JSON.stringify` key order** differed from JavaScript in Craft Ones (not reproduced in a minimal case). Never build checksums or netplay comparisons from it.
+
+## Debugging a native crash
+
+`--optimization dev` builds failed to link in Craft Ones (undefined `_main`; a template game links fine). When that happens, debug the release binary with lldb: `lldb ./dist/macos/<name>`, `breakpoint set -n scr_error_new`, `run`, then `bt` shows the TypeScript call site of a runtime error.
+
 ## Other notes
 
 - Benchmarks mean nothing while other processes load the machine. Check `top` first and say what else was running.

package/skill-data/netplay/SKILL.md

@@ -30,6 +30,8 @@ Run several seeds and a high latency (474 ms is what a transatlantic relay measu
 
 ## Rules
 
+- Build checksums from numbers in a fixed order, never from `JSON.stringify`: native builds can order keys differently from JavaScript, so a web peer and a native peer would report false desyncs.
+
 - The camera, effects, and HUD timers are simulation state if the simulation ever reads them. Update them once per step, never per drawn frame.
 - Render must restore any random state it uses, or use a separate visual generator.
 - Input delay (`--delay`, default 2) trades latency for fewer rollbacks.

package/templates/_base/src/setup.ts

@@ -1,27 +1,49 @@
-// Shared by main.web.ts and main.native.ts: fixed 60 Hz steps from the keyboard, then one render per frame.
+// Shared by main.web.ts and main.native.ts: keyboard and pointer to inputs, fixed 60 Hz steps, one render per frame.
 import { createDraw2D } from "dotframe/src/draw2d";
 import type { Frame, Setup } from "dotframe/src/gpu";
-import { Key } from "dotframe/src/input";
+import { Key, MouseButton } from "dotframe/src/input";
 import type { Platform } from "dotframe/src/platform";
-import { createGame, keyInput, PLAYERS, render, step, WINDOW } from "./game";
+import { createGame, keyInput, PLAYERS, POINTER_BIT, render, step, WINDOW } from "./game";
 
 const STEP = 1 / 60;
+// A full charge takes one second of holding.
+const FULL_CHARGE = 60;
 
 export function createSetup(): Setup {
-  return ({ gpu, input }: Platform): Frame => {
+  return ({ gpu, input, audio }: Platform): Frame => {
     const draw = createDraw2D(gpu, WINDOW.width, WINDOW.height);
     const game = createGame(Math.floor(Math.random() * 1e9));
     let simulated = -1;
+    // Hold to charge, release to act: the pattern most mouse and touch games need.
+    let charge = 0;
+    let wasDown = false;
     return (time: number): boolean => {
       if (simulated < 0) simulated = time;
-      // Fixed steps, so every target plays exactly what dotframe sim simulates.
       for (let n = 0; simulated + STEP <= time && n < 5; n++) {
+        const pointer = input.pointer();
+        const inside = pointer.x >= 0 && pointer.x <= 1 && pointer.y >= 0 && pointer.y <= 1;
+        const down = inside && ((pointer.buttons & MouseButton.Left) !== 0 || input.touches().length > 0);
+        let released = false;
+        if (down) charge = Math.min(FULL_CHARGE, charge + 1);
+        else if (wasDown) {
+          released = true;
+          // Audio is presentation, never simulation state: the pitch says how charged the release was.
+          audio.tone(220 + (charge / FULL_CHARGE) * 660, 0.12, 0.25);
+          charge = 0;
+        }
+        wasDown = down;
         const keys = [keyInput(input, [Key.A, Key.D, Key.W, Key.J]), keyInput(input, [Key.Left, Key.Right, Key.Up, Key.L])];
+        if (released) keys[0] = keys[0] | POINTER_BIT;
         step(game, keys.slice(0, PLAYERS));
         simulated += STEP;
       }
       draw.begin();
       render(game, draw);
+      if (charge > 0) {
+        // Charge meter under the play area.
+        draw.setFillStyle("#ffffff");
+        draw.fillRect(20, WINDOW.height - 16, (WINDOW.width - 40) * (charge / FULL_CHARGE), 6);
+      }
       draw.end({ r: 0, g: 0, b: 0 });
       return true;
     };

package/templates/blank/game.ts

@@ -4,6 +4,8 @@ import type { Draw2D } from "dotframe/src/draw2d";
 import type { Input } from "dotframe/src/input";
 
 export const WINDOW = { width: 960, height: 540, title: "__NAME__" };
+// The input bit a released mouse or touch press sets for player 1 (fires the action bit); see src/setup.ts.
+export const POINTER_BIT = 8;
 export const PLAYERS = 2;
 
 export interface Game {

package/templates/fighter/game.ts

@@ -11,6 +11,8 @@ const RIGHT = 2;
 const JUMP = 4;
 const ATTACK = 8;
 const GROUND = 440;
+// The input bit a released mouse or touch press sets for player 1 (attacks); see src/setup.ts.
+export const POINTER_BIT = ATTACK;
 const GRAVITY = 0.8;
 const SPEED = 5;
 const JUMP_SPEED = 15;

package/templates/platformer/game.ts

@@ -9,6 +9,8 @@ export const PLAYERS = 1;
 const LEFT = 1;
 const RIGHT = 2;
 const JUMP = 4;
+// The input bit a released mouse or touch press sets for player 1 (jumps); see src/setup.ts.
+export const POINTER_BIT = JUMP;
 const GRAVITY = 0.7;
 const SPEED = 4.5;
 const JUMP_SPEED = 13;