incanto 0.36.2 → 0.38.0

package/bin/incanto-feel.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * incanto-feel — what your controls actually FEEL like, as numbers.
+ *
+ *   bunx incanto-feel src/game.scene.json
+ *
+ * `capture()` and `framing()` are snapshots. Game feel lives on the time axis:
+ * how high the jump really goes, how many frames a turn costs, how wide the
+ * coyote window really is. This drives the player through scripted probes and
+ * reports the measurements.
+ *
+ * The windows are MEASURED by probing, not read off the schema — so a
+ * `coyoteSeconds` the controller never consults reports 0 ms. That was a real
+ * bug in this engine's own 3D controller, and the JSON looked correct
+ * throughout.
+ *
+ * It reports numbers and does not grade them: "good" jump feel is a genre
+ * decision, and a PASS/FAIL table against invented bands would be confidently
+ * wrong for most games.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--behaviors') args.behaviors = argv[++i];
+    else if (a === '--move') args.move = argv[++i];
+    else if (a === '--jump') args.jump = argv[++i];
+    else if (a === '--json') args.json = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (a.startsWith('--')) {
+      console.error(`unknown flag: ${a}`);
+      args.help = true;
+    } else if (!args.scene) args.scene = a;
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || !args.scene) {
+  console.error(`Usage: incanto-feel <scene.json> [options]
+
+  --behaviors FILE  your Behavior subclasses (.ts works on node >= 23.6 / bun)
+  --move ACTION     the vector action to move with (default: the first vector2)
+  --jump ACTION     the button to jump with (default: "jump")
+  --json            the report as JSON instead of prose`);
+  process.exit(args.help && args.scene !== undefined ? 0 : 1);
+}
+
+const { feelReport, feelText } = await import(pathToFileURL(join(PKG, 'dist', 'test.js')).href);
+const incanto = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
+
+const behaviors = {};
+if (args.behaviors) {
+  let mod;
+  try {
+    mod = await import(pathToFileURL(resolve(args.behaviors)).href);
+  } catch (e) {
+    console.error(`could not load --behaviors '${args.behaviors}' (${e?.message ?? e}).`);
+    process.exit(1);
+  }
+  for (const [name, value] of Object.entries(mod)) {
+    if (typeof value === 'function' && value.prototype instanceof incanto.Behavior) {
+      behaviors[name] = value;
+    }
+  }
+}
+
+const scenePath = resolve(args.scene);
+const sceneDir = dirname(scenePath);
+const sceneJson = JSON.parse(readFileSync(scenePath, 'utf-8'));
+
+let report;
+try {
+  report = await feelReport(sceneJson, {
+    behaviors,
+    stubMissingBehaviors: !args.behaviors,
+    ...(args.move ? { moveAction: args.move } : {}),
+    ...(args.jump ? { jumpAction: args.jump } : {}),
+    resolveScene: (p) => JSON.parse(readFileSync(resolve(sceneDir, p), 'utf-8')),
+  });
+} catch (e) {
+  console.error(`feel failed: ${e?.message ?? e}`);
+  process.exit(1);
+}
+
+process.stdout.write(args.json ? `${JSON.stringify(report, null, 2)}\n` : `${feelText(report)}\n`);
+process.exit(report.player ? 0 : 1);

package/bin/incanto-playtest.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * incanto-playtest — the engine plays your game and tells you whether it works.
+ *
+ *   bunx incanto-playtest src/game.scene.json --runs 20 --seconds 60
+ *
+ * `incanto-check` answers "will it load". This answers "is it a game": can it
+ * be finished, which destinations are unreachable, which wires never fire, and
+ * whether anything in it can hurt the player.
+ *
+ * Runs are seeded and headless — no renderer, no browser — so twenty minutes of
+ * simulated play costs a second or two. A run that did NOT win is written out
+ * as a replay you can watch:
+ *
+ *   bunx incanto-play src/game.scene.json --commands .incanto/playtest/fell-seed7.txt
+ *
+ * Without --behaviors, unregistered scripts are stubbed: the structure plays,
+ * your game logic does not. Pass the file that exports your Behavior subclasses
+ * to test the real thing.
+ *
+ * Exit code 1 when no run reached a win, so CI can gate on it.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function parseArgs(argv) {
+  const args = { runs: 20, seconds: 60, seed: 1, out: '.incanto/playtest' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--behaviors') args.behaviors = argv[++i];
+    else if (a === '--runs') args.runs = Number(argv[++i]);
+    else if (a === '--seconds') args.seconds = Number(argv[++i]);
+    else if (a === '--seed') args.seed = Number(argv[++i]);
+    else if (a === '--out') args.out = argv[++i];
+    else if (a === '--no-replays') args.noReplays = true;
+    else if (a === '--json') args.json = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (a.startsWith('--')) {
+      console.error(`unknown flag: ${a}`);
+      args.help = true;
+    } else if (!args.scene) args.scene = a;
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || !args.scene) {
+  console.error(`Usage: incanto-playtest <scene.json> [options]
+
+  --runs N          independent seeded runs (default 20)
+  --seconds N       simulated seconds per run before calling it stuck (default 60)
+  --seed N          first seed; run i uses seed+i (default 1)
+  --behaviors FILE  your Behavior subclasses (.ts works on node >= 23.6 / bun)
+  --out DIR         where failing replays go (default .incanto/playtest)
+  --no-replays      report only, write nothing
+  --json            the full report as JSON instead of prose
+
+Exits 1 when no run reached a win.`);
+  process.exit(args.help && args.scene !== undefined ? 0 : 1);
+}
+
+const { playtest, playtestText, failingReplays } = await import(
+  pathToFileURL(join(PKG, 'dist', 'test.js')).href
+);
+const incanto = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
+
+const behaviors = {};
+if (args.behaviors) {
+  let mod;
+  try {
+    mod = await import(pathToFileURL(resolve(args.behaviors)).href);
+  } catch (e) {
+    console.error(
+      `could not load --behaviors '${args.behaviors}' (${e?.message ?? e}). ` +
+        'Pass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.',
+    );
+    process.exit(1);
+  }
+  for (const [name, value] of Object.entries(mod)) {
+    if (typeof value === 'function' && value.prototype instanceof incanto.Behavior) {
+      behaviors[name] = value;
+    }
+  }
+  if (Object.keys(behaviors).length === 0) {
+    console.error(`warning: no Behavior subclasses exported from ${args.behaviors}`);
+  }
+}
+
+const scenePath = resolve(args.scene);
+const sceneJson = JSON.parse(readFileSync(scenePath, 'utf-8'));
+const sceneDir = dirname(scenePath);
+
+let report;
+try {
+  report = await playtest(sceneJson, {
+    runs: args.runs,
+    seconds: args.seconds,
+    seed: args.seed,
+    behaviors,
+    stubMissingBehaviors: !args.behaviors,
+    // sub-scenes resolve relative to the scene file, as the loader does
+    resolveScene: (p) => JSON.parse(readFileSync(resolve(sceneDir, p), 'utf-8')),
+  });
+} catch (e) {
+  console.error(`playtest failed: ${e?.message ?? e}`);
+  process.exit(1);
+}
+
+if (args.json) {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else {
+  process.stdout.write(`${playtestText(report)}\n`);
+}
+
+// A failing run is only useful if you can watch it. One file per outcome kind —
+// twenty identical "stuck" replays teach nothing that the first one does not.
+if (!args.noReplays && !args.json) {
+  const seen = new Set();
+  const written = [];
+  for (const { seed, outcome, replay } of failingReplays(report)) {
+    if (seen.has(outcome)) continue;
+    seen.add(outcome);
+    const file = join(resolve(args.out), `${outcome}-seed${seed}.json`);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(replay, null, 2));
+    written.push(file);
+  }
+  if (written.length > 0) {
+    process.stdout.write(`\n  replays: ${written.join('\n           ')}\n`);
+  }
+}
+
+process.exit(report.runs.some((r) => r.outcome === 'won') ? 0 : 1);

package/dist/2d.d.ts

@@ -1,7 +1,7 @@
-import { N as Scene$1, S as Scheduler, T as RendererStats, Tt as Node, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-DibCwrW7.js";
+import { N as Scene$1, S as Scheduler, T as RendererStats, Tt as Node, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-B5PJ32eu.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DVwIGZdK.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
-import { t as LoadSceneOptions } from "./loader-BqigZsfF.js";
+import { t as LoadSceneOptions } from "./loader-DSMdqasu.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-D-StzrTj.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-COGCNitr.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-B4v39hca.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-C4t5gVhc.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-DnB9m7Rl.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-OfKb0PV_.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
-import { N as Scene$1, S as Scheduler, T as RendererStats, Tt as Node, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-DibCwrW7.js";
+import { N as Scene$1, S as Scheduler, T as RendererStats, Tt as Node, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-B5PJ32eu.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DVwIGZdK.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
-import { t as LoadSceneOptions } from "./loader-BqigZsfF.js";
+import { t as LoadSceneOptions } from "./loader-DSMdqasu.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-B3QtdhvZ.js";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-BrE5Uec6.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
@@ -1058,6 +1058,12 @@ declare class CharacterController3D extends Node3D {
   sprintMultiplier: number;
   jumpVelocity: number;
   sprintJumpMultiplier: number;
+  coyoteSeconds: number;
+  jumpBufferSeconds: number;
+  jumpCutMultiplier: number;
+  maxJumps: number;
+  airControl: number;
+  fallGravity: number;
   floatHeight: number;
   mouseLook: boolean;
   zoomMin: number;
@@ -1093,6 +1099,11 @@ declare class CharacterController3D extends Node3D {
   /** idle | walk | run | fastRun | airborne — drive animations from this. */
   state: "idle" | "walk" | "run" | "fastRun" | "airborne";
   grounded: boolean;
+  /** @internal Feel timers — see the jump block for what each one buys. */
+  private coyoteLeft;
+  private bufferLeft;
+  private jumpsUsed;
+  private rising;
   private get body();
   override onEnterTree(): void;
   override fixedUpdate(dt: number): void;
@@ -3114,6 +3125,19 @@ interface Renderer3DOptions {
   /** Defaults to `window.devicePixelRatio` capped at 2. */
   pixelRatio?: number;
   /**
+  * Starting point for the rendering knobs, from the player's quality tier.
+  *
+  * DEFAULTS, not overrides: a scene's own `environment.rendering` is a decision
+  * about that scene and still wins, and an explicit `pixelRatio` option wins
+  * over both. This only decides what a device that has said nothing gets —
+  * which for `antialias` is the only chance there is, since it is a WebGL
+  * context attribute and cannot change after the context exists.
+  */
+  qualityDefaults?: {
+    antialias: boolean;
+    pixelRatio: number;
+  };
+  /**
   * Keep the frame rate by rendering at fewer pixels when frames run slow, and
   * hand them back when they recover (default ON). A retina display asks for
   * 4× the pixels; shaded water is fragment-heavy; the honest answer is fewer
@@ -3211,6 +3235,8 @@ declare class Renderer3D {
   /** The pixel ratio the scene ASKED for — the governor scales this, never replaces it. */
   private readonly basePixelRatio;
   private readonly adaptive;
+  private renderScale;
+  private adaptiveScale;
   private lastFrameAt;
   private readonly debugLines;
   private readonly selectionLines;
@@ -3225,6 +3251,21 @@ declare class Renderer3D {
   */
   private governResolution;
   /**
+  * The player's resolution multiplier, on top of whatever the scene and the
+  * quality tier resolved to.
+  *
+  * The cheapest lever there is on a weak GPU: at 0.66 the fragment shaders run
+  * over 44% of the pixels for a soft image and nothing else, where dropping a
+  * quality tier costs the shadows outright. Live — a settings menu writes it
+  * mid-game — and it multiplies with the adaptive governor rather than
+  * fighting it, so a player who has already scaled down does not get scaled
+  * down twice as hard.
+  */
+  setRenderScale(scale: number): void;
+  /** Judge frames against `fps` — see AdaptiveResolution.setTarget. */
+  setFrameTarget(fps: number): void;
+  private applyPixelRatio;
+  /**
   * Compile the scene's GPU programs off the critical path.
   *
   * The compile itself is unavoidable — a dressed outdoor scene is 40+ programs

package/dist/3d.js

@@ -1,36 +1,8 @@
-import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-C0MUMSak.js";
-import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-fK9oyrrR.js";
-import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-DnOu2aAa.js";
+import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-CsJDUQh_.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-C0Axpfth.js";
+import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-DqY2lMBc.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DFJVMYET.js";
-//#region src/3d/environment-runtime.ts
-/**
-* Live environment editing — the renderer re-applies `scene.environment`
-* every frame (cheap when unchanged), so changing the LOOK at runtime is
-* just writing that object. This helper does it safely:
-*
-*   setEnvironment3D(engine, { sky: { elevationDeg: 4 }, exposure: 0.8 });
-*   setEnvironment3D(engine, { fog: null });          // null DELETES a key
-*
-* - one-level deep merge (patching `sky.elevationDeg` keeps the other sky keys)
-* - hard-validates the merged result NOW (in your call stack), so a bad patch
-*   throws where you wrote it — never inside the render loop
-*/
-function setEnvironment3D(engine, patch) {
-	const scene = engine.scene;
-	if (!scene) throw new IncantoError("BAD_FORMAT", "setEnvironment3D: the engine has no scene.");
-	const merged = { ...scene.environment ?? {} };
-	for (const [key, value] of Object.entries(patch)) if (value === null) delete merged[key];
-	else if (typeof value === "object" && !Array.isArray(value) && typeof merged[key] === "object" && merged[key] !== null && !Array.isArray(merged[key])) merged[key] = {
-		...merged[key],
-		...value
-	};
-	else merged[key] = value;
-	parseEnvironment3D(merged);
-	scene.environment = merged;
-}
-//#endregion
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-C8242nXr.js";
 //#region src/3d/terrain-nav.ts
 function buildTerrainNav(terrain, opts) {
 	const cellSize = opts?.cellSize ?? 2;

package/dist/{behavior-DibCwrW7.d.ts → behavior-B5PJ32eu.d.ts}

@@ -670,6 +670,17 @@ declare class InputMap {
   * scripted gameplay tests and touch buttons drive the game by intent
   * (`press('jump')`) instead of reverse-engineering keybinds.
   */
+  /**
+  * Every action this scene declared, with its kind.
+  *
+  * A scene states its own control vocabulary in `input{}`, which means a tool
+  * can drive a game it has never seen — the automated playtester's entire
+  * premise. Nothing else could ask: `actions` was private.
+  */
+  declaredActions(): Array<{
+    name: string;
+    type: "button" | "vector2";
+  }>;
   pressAction(action: string): void;
   /** Release an injected button action (yields one justReleased frame). */
   releaseAction(action: string): void;
@@ -1080,6 +1091,21 @@ interface SettingsValues {
   * does not translate falls back to English, silently and on purpose.
   */
   language: string;
+  /**
+  * Has a HUMAN chosen the quality tier?
+  *
+  * Without this, a first boot cannot tell "the default happens to be high" from
+  * "the player picked high", so device auto-detection would either never run or
+  * would overwrite a deliberate choice on every launch.
+  */
+  qualityChosen: boolean;
+  /** Frames per second to draw at most. 0 = uncapped (draw every rAF). */
+  maxFps: number;
+  /**
+  * Extra multiplier on the render resolution, on top of the tier's pixel ratio.
+  * 1 = as the tier says. Below 1 trades sharpness for frame rate.
+  */
+  renderScale: number;
 }
 /** What a device probe can see without a GPU context. */
 interface DeviceHints {
@@ -1111,6 +1137,43 @@ declare class Settings {
   /** Back to defaults, on disk too. */
   reset(): void;
   /**
+  * Choose a starting tier from the device, ONCE.
+  *
+  * Only on a first visit: after someone has picked a tier, re-detecting on
+  * every launch would silently undo their choice — which is the behaviour every
+  * player experiences as "the settings do not save".
+  */
+  autoQuality(hints?: DeviceHints): QualityTier;
+  /** Record that the tier came from a person, not from the device probe. */
+  chooseQuality(tier: QualityTier): void;
+  /**
+  * Apply the saved quality tier to a live scene, and keep applying it.
+  *
+  * The same shape as `bindAudio` and `bindLocale`. Until 0.38 this did not
+  * exist: `settings.quality` was written to disk and read by NOBODY, and
+  * `qualityEnvironment` — the function that turns a tier into something the
+  * renderer understands — emitted patches the environment parser rejects, for
+  * all three tiers. Both were public, documented and never once called.
+  */
+  bindQuality(apply: (patch: Record<string, JsonValue>) => void): () => void;
+  /**
+  * Apply the saved frame cap, and again whenever it changes.
+  *
+  * Separate from `bindQuality` because it is not a tier: a player caps the
+  * frame rate to keep a phone cool or a battery alive, on the highest visual
+  * settings the device can hold, and those two choices do not belong on one
+  * slider. 0 means uncapped. Returns the unsubscribe.
+  */
+  bindFrameCap(apply: (fps: number) => void): () => void;
+  /**
+  * Apply the saved resolution multiplier, and again whenever it changes.
+  *
+  * The lever that buys the most frames per unit of ugliness on a weak GPU —
+  * shading 44% of the pixels at 0.66 costs a soft image and nothing else,
+  * while dropping a quality tier costs shadows entirely.
+  */
+  bindRenderScale(apply: (scale: number) => void): () => void;
+  /**
   * Apply the saved language, and keep it in step both ways.
   *
   * The same shape as `bindAudio`: a game that writes
@@ -1128,13 +1191,22 @@ declare class Settings {
   bindAudio(audio: AudioBuses): () => void;
 }
 /**
-* What a quality tier MEANS, as an environment patch.
+* What a quality tier MEANS, as a LIVE environment patch.
+*
+* Only the levers that actually cost: shadows, post, bloom and clouds.
+* Deliberately an `environment` patch, because `setEnvironment3D(engine, patch)`
+* already applies one live and validated — this is not a second rendering
+* pipeline, it is three presets for the one that exists.
+*
+* The `off` spelling matters and got this wrong for three releases: every tier
+* emitted `{ enabled: false }`, which the environment parser rejects
+* (`environment.bloom has unknown key 'enabled'`). Nothing called this function,
+* so nothing found out. In a live patch `null` DELETES a key — that is how a
+* stage is turned off — and `shadows` alone takes a real `false`.
 *
-* Only the levers that actually cost: shadows, post, clouds, and the resolution
-* the renderer draws at. Deliberately an `environment` patch, because
-* `setEnvironment3D(engine, patch)` already applies one live and validated —
-* this is not a second rendering pipeline, it is three presets for the one that
-* exists.
+* Antialiasing and pixel ratio are NOT here: `antialias` is a WebGL context
+* attribute and cannot change without rebuilding the renderer. See
+* `qualityRendering`.
 */
 declare function qualityEnvironment(tier: QualityTier): Record<string, JsonValue>;
 //#endregion
@@ -1184,6 +1256,8 @@ interface EngineOptions {
   scheduler?: Scheduler;
   /** Seed for `engine.rng` — set it to make a run reproducible (default: random). */
   seed?: number;
+  /** Frame cap in fps; 0 (default) runs at whatever the display offers. */
+  maxFps?: number;
 }
 /**
 * The game loop: drives a Scene's tree with fixed-timestep `fixedUpdate`
@@ -1295,6 +1369,32 @@ declare class Engine {
   setScene(scene: Scene): void;
   start(): void;
   /**
+  * The frame cap: fps, or 0 for "as fast as the display goes" (the default).
+  *
+  * Live — a settings menu writes it mid-game. It gates the whole frame, not
+  * just the render: an uncapped loop on a 144 Hz phone burns battery running
+  * game logic nobody sees.
+  *
+  * `tick()` is deliberately NOT gated. A headless harness driving its own
+  * clock asked for that frame; the cap is about the real-time loop.
+  */
+  maxFps: number;
+  private nextFrameAt;
+  private lastOfferedAt;
+  private displayPeriodMs;
+  /**
+  * Should this display frame run?
+  *
+  * The obvious `if (now - last < interval) return` is wrong in a way that only
+  * shows up between the round numbers: a 45 fps cap on a 60 Hz display misses
+  * every other deadline by a fraction of a millisecond, waits a whole display
+  * frame more, and delivers 30 — asking for 45 makes the game slower than not
+  * capping at all. The fix is to allow a frame that is within half a display
+  * period of its deadline, and to advance the deadline by the interval rather
+  * than from `now`, so the error does not accumulate.
+  */
+  private frameIsDue;
+  /**
   * A frame threw somewhere outside a single node (a renderer, physics, a
   * signal handler). Report the first one and count the rest: a broken frame
   * repeats sixty times a second, and sixty identical traces a second is how

package/dist/{create-game-D-StzrTj.js → create-game-C4t5gVhc.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { n as loadScene, o as computeViewport, s as resolveViewport, v as diagnose, w as registerBehavior } from "./loader-DAZlgqeC.js";
-import { h as Engine, m as AudioPlayer } from "./register-BHAwM4bK.js";
+import { n as loadScene, o as computeViewport, s as resolveViewport, v as diagnose, w as registerBehavior } from "./loader-r49nDwB4.js";
+import { h as Engine, m as AudioPlayer } from "./register-Dm7nrd-E.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { i as openBundledEditor, n as crossFade, r as devServerLibrary, t as teardown } from "./teardown-CCtAMDLB.js";
-import { n as registerGameplayBehaviors } from "./gameplay-C0MUMSak.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-COGCNitr.js";
+import { n as registerGameplayBehaviors } from "./gameplay-CsJDUQh_.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-DnB9m7Rl.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-B4v39hca.js";
+import { n as enablePhysics2D } from "./physics-2d-OfKb0PV_.js";
 import { Box3, BufferAttribute, BufferGeometry, Color, LineBasicMaterial, LineSegments, LinearFilter, NearestFilter, OrthographicCamera, Raycaster, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
 //#region src/2d/assets.ts
 /**