@nano133/nanoterra 0.12.0 → 0.14.0

package/src/admin/switches.ts

@@ -1,5 +1,5 @@
 // The switches of the "Game" card in /admin, and the words that say what each does. The handler checks a press with `parsePatch`; the panel
-// draws the card from `SWITCHES` and `FRIENDS_CHOICES`. A switch changes ONLY these four settings; never a look, a price or an order.
+// draws the card from `SWITCHES` and `FRIENDS_CHOICES`. A switch changes ONLY these five settings; never a look, a price or an order.
 
 /** Which character the player is: Nanoterra's island character (the one the player has there) or the game's own. */
 export type Character = "nanoterra" | "own";
@@ -12,52 +12,72 @@ export type Signin = "exchange" | "ticket" | "none";
 export type Friends = "nanoterra" | "own" | "off";
 /** Whether the game shows Nanoterra's emotes ("@nano133/nanoterra/emotes"): the wheel's Nanoterra emotes and the other players' on their characters. Off leaves the game's own emotes. */
 export type Emotes = "on" | "off";
-/** The game's own words for the switches. `friends` and `emotes` may be left out: "nanoterra" and "on" then (on by default). */
-export type GameSettings = { character: Character; signin: Signin; friends?: Friends; emotes?: Emotes };
+/**
+ * Whether the game has free play. "off": a player pays in the game to play (the game asks for the payment; the switch does not). The listing file says it
+ * (`"freePlay": false`), and Nanoterra's listing then says "Paid" in place of "Free to play". The game's paid play, its prices and its risk are the creator's.
+ */
+export type FreePlay = "on" | "off";
+/** The game's own words for the switches. `friends`, `emotes` and `freePlay` may be left out: "nanoterra", "on" and "on" then (on by default). */
+export type GameSettings = { character: Character; signin: Signin; friends?: Friends; emotes?: Emotes; freePlay?: FreePlay };
 /** What a press can set: sign-in is on ("exchange": a game with a server) or off ("none"). */
-export type GamePatch = { character?: Character; signin?: "exchange" | "none"; friends?: Friends; emotes?: Emotes };
+export type GamePatch = { character?: Character; signin?: "exchange" | "none"; friends?: Friends; emotes?: Emotes; freePlay?: FreePlay };
 /** The settings as they are now, and which ones /admin has set (the others still have the game's default). */
-export type GameState = { character: Character; signin: Signin; friends: Friends; emotes: Emotes; fromAdmin: { character: boolean; signin: boolean; friends: boolean; emotes: boolean } };
+export type GameState = {
+  character: Character;
+  signin: Signin;
+  friends: Friends;
+  emotes: Emotes;
+  freePlay: FreePlay;
+  fromAdmin: { character: boolean; signin: boolean; friends: boolean; emotes: boolean; freePlay: boolean };
+};
 
 export const isCharacter = (v: unknown): v is Character => v === "nanoterra" || v === "own";
 export const isSigninChoice = (v: unknown): v is "exchange" | "none" => v === "exchange" || v === "none";
 export const isSignin = (v: unknown): v is Signin => v === "exchange" || v === "ticket" || v === "none";
 export const isFriends = (v: unknown): v is Friends => v === "nanoterra" || v === "own" || v === "off";
 export const isEmotes = (v: unknown): v is Emotes => v === "on" || v === "off";
+export const isFreePlay = (v: unknown): v is FreePlay => v === "on" || v === "off";
 /** The friends list a game shows while neither its own words nor /admin say: Nanoterra's. */
 export const DEFAULT_FRIENDS: Friends = "nanoterra";
 /** Nanoterra's emotes are on while neither the game's own words nor /admin say. */
 export const DEFAULT_EMOTES: Emotes = "on";
+/** Free play is on while neither the game's own words nor /admin say. */
+export const DEFAULT_FREE_PLAY: FreePlay = "on";
+/** The listing file's word for free play (`"freePlay": true` or `false`), from the settings. */
+export const freePlayOn = (s: Pick<GameSettings, "freePlay">): boolean => (s.freePlay ?? DEFAULT_FREE_PLAY) === "on";
 /** The sign-in switch is on for any way but "none". */
 export const signinOn = (s: Signin): boolean => s !== "none";
 
-/** A request body for a press: only the two known words, at least one. Anything else is refused, with the reason in words. */
+/** A request body for a press: only the known words, at least one. Anything else is refused, with the reason in words. */
 export function parsePatch(body: unknown): { ok: true; patch: GamePatch } | { ok: false; error: string } {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: 'Send an object with "character", "signin", "friends" or "emotes".' };
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: 'Send an object with "character", "signin", "friends", "emotes" or "freePlay".' };
   const patch: GamePatch = {};
   for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
     if (key === "character" && isCharacter(value)) patch.character = value;
     else if (key === "signin" && isSigninChoice(value)) patch.signin = value;
     else if (key === "friends" && isFriends(value)) patch.friends = value;
     else if (key === "emotes" && isEmotes(value)) patch.emotes = value;
+    else if (key === "freePlay" && isFreePlay(value)) patch.freePlay = value;
     else if (key === "friends") return { ok: false, error: '"friends" must be "nanoterra", "own" or "off".' };
     else if (key === "emotes") return { ok: false, error: '"emotes" must be "on" or "off".' };
+    else if (key === "freePlay") return { ok: false, error: '"freePlay" must be "on" or "off".' };
     else if (key === "character") return { ok: false, error: '"character" must be "nanoterra" or "own".' };
     else if (key === "signin") return { ok: false, error: '"signin" must be "exchange" or "none".' };
     else return { ok: false, error: `"${key}" is not a game switch.` };
   }
-  if (!Object.keys(patch).length) return { ok: false, error: 'Send "character", "signin", "friends" or "emotes".' };
+  if (!Object.keys(patch).length) return { ok: false, error: 'Send "character", "signin", "friends", "emotes" or "freePlay".' };
   return { ok: true, patch };
 }
 
 /** The settings from what the store kept and the game's defaults. A stored value that is not one of the known words is ignored. */
-export function mergeSettings(stored: { character?: unknown; signin?: unknown; friends?: unknown; emotes?: unknown }, defaults: GameSettings): GameState {
+export function mergeSettings(stored: { character?: unknown; signin?: unknown; friends?: unknown; emotes?: unknown; freePlay?: unknown }, defaults: GameSettings): GameState {
   return {
     character: isCharacter(stored.character) ? stored.character : defaults.character,
     signin: isSigninChoice(stored.signin) ? stored.signin : defaults.signin,
     friends: isFriends(stored.friends) ? stored.friends : isFriends(defaults.friends) ? defaults.friends : DEFAULT_FRIENDS,
     emotes: isEmotes(stored.emotes) ? stored.emotes : isEmotes(defaults.emotes) ? defaults.emotes : DEFAULT_EMOTES,
-    fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin), friends: isFriends(stored.friends), emotes: isEmotes(stored.emotes) },
+    freePlay: isFreePlay(stored.freePlay) ? stored.freePlay : isFreePlay(defaults.freePlay) ? defaults.freePlay : DEFAULT_FREE_PLAY,
+    fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin), friends: isFriends(stored.friends), emotes: isEmotes(stored.emotes), freePlay: isFreePlay(stored.freePlay) },
   };
 }
 
@@ -76,7 +96,7 @@ export const FRIENDS_CHOICES: Record<Friends, { name: string; note: string }> =
 };
 
 /** One switch of the card: its title, and one plain sentence for each state. */
-export type SwitchId = "character" | "signin" | "emotes";
+export type SwitchId = "character" | "signin" | "emotes" | "freePlay";
 export const SWITCHES: Record<SwitchId, { title: string; on: string; off: string }> = {
   character: {
     title: "Players can play as their Nanoterra character",
@@ -93,6 +113,11 @@ export const SWITCHES: Record<SwitchId, { title: string; on: string; off: string
     on: "On: players can play Nanoterra's emotes (Wave, Dance, Sit and more) from the Emotes wheel, and see the other players' emotes.",
     off: "Off: the game shows no Nanoterra emote. The game's own emotes, if it has any, stay on the wheel.",
   },
+  freePlay: {
+    title: "Free play",
+    on: "On: players can play without paying. Nanoterra's listing says “Free to play”.",
+    off: "Off: there is no free play. A player must pay in your game to play, and Nanoterra's listing says “Paid”. Your game asks for the payment: this switch only says so. Your paid game, its prices and its risk are yours.",
+  },
 };
 
 /**
@@ -107,11 +132,15 @@ export const CHARACTER_SIGNIN_OFF = "Sign-in from Nanoterra is Off, so every pla
 export const REVIEW_NOTE =
   "Your choice is saved here at once. The sign-in word is part of your listing file, and Nanoterra's review decides what Nanoterra shows for a game that is listed. This page cannot see that review. Check it on Nanoterra's launch page (step 6).";
 export const REVIEW_LINK = "https://nano133.com/build/nanoterra/launch";
+/** Under the free play switch: the word is part of the listing file, as the sign-in word is, so Nanoterra's review decides what Nanoterra shows. */
+export const FREE_PLAY_NOTE = "Your choice is saved here at once. Free play is part of your listing file too, and Nanoterra's review decides what Nanoterra's listing says for a game that is listed.";
 
 /** The state of a switch from the settings, and the patch that a press sends (the other state). */
-export const stateOf = (id: SwitchId, s: GameSettings): boolean => (id === "character" ? s.character === "nanoterra" : id === "emotes" ? (s.emotes ?? DEFAULT_EMOTES) === "on" : signinOn(s.signin));
+export const stateOf = (id: SwitchId, s: GameSettings): boolean =>
+  id === "character" ? s.character === "nanoterra" : id === "emotes" ? (s.emotes ?? DEFAULT_EMOTES) === "on" : id === "freePlay" ? freePlayOn(s) : signinOn(s.signin);
 export function pressOf(id: SwitchId, s: GameSettings): GamePatch {
   if (id === "character") return { character: s.character === "nanoterra" ? "own" : "nanoterra" };
   if (id === "emotes") return { emotes: stateOf("emotes", s) ? "off" : "on" };
+  if (id === "freePlay") return { freePlay: freePlayOn(s) ? "off" : "on" };
   return { signin: signinOn(s.signin) ? "none" : "exchange" };
 }

package/src/input/index.ts

@@ -16,6 +16,11 @@
 // calls your `pause` when the player really left (a free round stops its clock and shows a Resume key). No package: plain browser events.
 //
 // A ROUND THAT COSTS MONEY must not pause: its deadline must not move. Keep `releaseWhenLost` (the character always stops) and leave `pauseWhenLeft` out.
+//
+// The camera's distance (the wheel, a pinch, the + and − keys, one curve) is `createZoom` and `listenZoom`, in ./zoom.ts.
+
+export { createZoom, listenZoom, pinchedTo, wheelNotches, zoomedBy, PINCH, ZOOM_CURVE, ZOOM_EASE, ZOOM_STEP } from "./zoom.js";
+export type { Zoom, ZoomRange } from "./zoom.js";
 
 type Listens = Pick<EventTarget, "addEventListener" | "removeEventListener">;
 

package/src/input/zoom.ts

@@ -0,0 +1,160 @@
+// The camera's distance for a game the player walks in: the mouse wheel, a trackpad's two-finger scroll or pinch, a two-finger pinch on a touch
+// screen, and the + and − keys move one number, the camera's distance from the eyes, along ONE curve. 0 is first person; below `first` the camera
+// is in the eyes. It eases to the distance asked for (at once with reduced motion). No package: plain browser events.
+//
+// THE FEEL is nano133.com's island (app/island/zoom.ts). Each notch moves the distance in proportion to it (`0.35 + 0.14 × distance` metres a
+// notch), so a notch feels the same near and far. Every bit of a scroll counts: a dead zone and a speed limit dropped most of a quick spin in
+// Echo Island, and its wheel needed about five times the spins of the island's (Wes, 2026-11-01). Close in, the last notch goes all the way to
+// the eyes; out of the eyes, the first notch goes past the switch, so the camera never rests half inside the head.
+//
+// THE PINCH follows the same curve: the curve is a constant ratio of `distance + 2.5`, so spreading the fingers to twice their start divides it
+// by 2^PINCH.power, wherever the camera is.
+
+/** Where the camera may be (metres from the eyes): the farthest, the default, and the switch: nearer than `first` it is in the eyes. */
+export type ZoomRange = { max: number; start: number; first: number };
+
+/** One notch: about one mouse-wheel click (100 px of scroll). The + and − keys move `key` notches. */
+export const ZOOM_STEP = { perPx: 0.006, perPxPinch: 0.03, linePx: 16, pagePx: 400, key: 1.2 } as const;
+/** The curve: a notch moves `base + scale × distance` metres. */
+export const ZOOM_CURVE = { base: 0.35, scale: 0.14 } as const;
+/** The touch pinch: twice the spread divides `distance + base/scale` by 2^power. */
+export const PINCH = { power: 1.3 } as const;
+/** How fast the camera eases to the distance asked for (1/s). */
+export const ZOOM_EASE = 9;
+
+const clamp = (r: ZoomRange, d: number) => Math.min(r.max, Math.max(0, d));
+
+/** One wheel event as notches (negative: in). A mouse notch arrives in lines or about 100 px, a trackpad in many small pixels, a pinch as a wheel with the ctrl key. */
+export function wheelNotches(e: { deltaY: number; deltaMode?: number; ctrlKey?: boolean }): number {
+  const px = e.deltaMode === 1 ? e.deltaY * ZOOM_STEP.linePx : e.deltaMode === 2 ? e.deltaY * ZOOM_STEP.pagePx : e.deltaY;
+  return px * (e.ctrlKey ? ZOOM_STEP.perPxPinch : ZOOM_STEP.perPx);
+}
+
+/** The snap: close in, a move into the switch goes to the eyes; out of the eyes, a move out goes past the switch. */
+function snapped(r: ZoomRange, from: number, to: number): number {
+  if (to < from && to < r.first) return 0;
+  if (to > from && from < r.first) return clamp(r, Math.max(to, r.first + 1));
+  return clamp(r, to);
+}
+
+/** The distance after `notches` (negative: in) from `want`. */
+export function zoomedBy(r: ZoomRange, want: number, notches: number): number {
+  return snapped(r, want, want + notches * (ZOOM_CURVE.base + want * ZOOM_CURVE.scale));
+}
+
+/** The distance during a touch pinch: `from` at the start, the fingers `spread0` apart then and `spread` now (px). Apart brings it in. */
+export function pinchedTo(r: ZoomRange, from: number, spread0: number, spread: number): number {
+  if (!(spread0 > 0) || !(spread > 0)) return from;
+  const k = ZOOM_CURVE.base / ZOOM_CURVE.scale;
+  return snapped(r, from, (from + k) * (spread0 / spread) ** PINCH.power - k);
+}
+
+export type Zoom = {
+  /** The distance asked for (metres from the eyes). */
+  want(): number;
+  /** The distance now, as the last `step` eased it. */
+  now(): number;
+  /** True while the camera is in the eyes (the distance now below `first`). */
+  eyes(): boolean;
+  /** Asks for a distance (clamped), writes it and tells the listeners. */
+  set(d: number): void;
+  /** Moves the distance by notches (negative: in), along the curve. */
+  by(notches: number): void;
+  /** A wheel event (or one like it) moves the distance. */
+  wheel(e: { deltaY: number; deltaMode?: number; ctrlKey?: boolean }): void;
+  /** A touch pinch starts with the fingers `spread` apart (px); `pinch` follows it; `pinchEnd` ends it. */
+  pinchStart(spread: number): void;
+  pinch(spread: number): void;
+  pinchEnd(): void;
+  /** One frame: the distance eases to the one asked for (at once when `calm`, reduced motion). Returns it. */
+  step(dt: number, calm: boolean): number;
+  /** Calls `on` when the distance asked for changes. Returns the function that stops it. */
+  subscribe(on: () => void): () => void;
+};
+
+/**
+ * The camera's distance of one game. `read` gives the kept distance (null: none, the default `start`), and is read the first time the distance is
+ * asked for, so the server never calls it; `write` keeps a new one (on every change: put a delay in it if your storage is slow).
+ */
+export function createZoom(r: ZoomRange, keep: { read?: () => number | null; write?: (d: number) => void } = {}): Zoom {
+  let want = r.start;
+  let now = r.start;
+  let loaded = false;
+  let pinchFrom: { d: number; spread: number } | null = null;
+  const listeners = new Set<() => void>();
+  const load = () => {
+    if (loaded) return;
+    loaded = true;
+    const v = keep.read?.();
+    if (typeof v === "number" && Number.isFinite(v)) want = now = clamp(r, v);
+  };
+  const set = (d: number) => {
+    load();
+    want = clamp(r, d);
+    keep.write?.(want);
+    for (const on of listeners) on();
+  };
+  const by = (notches: number) => {
+    load();
+    if (notches !== 0) set(zoomedBy(r, want, notches));
+  };
+  return {
+    want: () => (load(), want),
+    now: () => (load(), now),
+    eyes: () => (load(), now < r.first),
+    set,
+    by,
+    wheel: (e) => by(wheelNotches(e)),
+    pinchStart(spread) {
+      load();
+      pinchFrom = { d: want, spread };
+    },
+    pinch(spread) {
+      if (pinchFrom) set(pinchedTo(r, pinchFrom.d, pinchFrom.spread, spread));
+    },
+    pinchEnd() {
+      pinchFrom = null;
+    },
+    step(dt, calm) {
+      load();
+      now = calm ? want : now + (want - now) * (1 - Math.exp(-dt * ZOOM_EASE));
+      if (Math.abs(now - want) < 0.002) now = want;
+      return now;
+    },
+    subscribe(on) {
+      listeners.add(on);
+      return () => void listeners.delete(on);
+    },
+  };
+}
+
+type Listens = Pick<EventTarget, "addEventListener" | "removeEventListener">;
+
+/**
+ * The wheel over `el` (the game's canvas: the page does not scroll or zoom there) and the + and − keys on the window (also the number pad's) move
+ * `zoom`. A key with ctrl, alt or the command key is the browser's own zoom and is left alone, and so is a key typed in a field. `skip(e)` returns true
+ * for an event the game wants to keep from the zoom (a key the player is binding, a game that is paused). Returns the function that takes the listeners away.
+ * The touch pinch is yours to wire (`pinchStart`, `pinch`, `pinchEnd`), because the fingers are also your thumb stick and your look.
+ */
+export function listenZoom(zoom: Zoom, el: Listens, opts: { skip?: (e: Event) => boolean; keys?: boolean } = {}, win: Listens = window): () => void {
+  const wheel = (e: Event) => {
+    e.preventDefault();
+    if (opts.skip?.(e)) return;
+    zoom.wheel(e as WheelEvent);
+  };
+  const key = (e: Event) => {
+    const k = e as KeyboardEvent;
+    if (k.metaKey || k.altKey || k.ctrlKey || opts.skip?.(e)) return;
+    const t = k.target as HTMLElement | null;
+    if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName ?? ""))) return;
+    if (k.code === "Equal" || k.code === "NumpadAdd") zoom.by(-ZOOM_STEP.key);
+    else if (k.code === "Minus" || k.code === "NumpadSubtract") zoom.by(ZOOM_STEP.key);
+  };
+  el.addEventListener("wheel", wheel, { passive: false });
+  const keys = opts.keys !== false;
+  if (keys) win.addEventListener("keydown", key);
+  return () => {
+    el.removeEventListener("wheel", wheel);
+    if (keys) win.removeEventListener("keydown", key);
+  };
+}