incanto 0.37.0 → 0.38.0

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-5o1EkbLD.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-iGq2PT_k.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-DmGc-Mrn.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-DFSW2Y30.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-C8Hi40qb.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-5o1EkbLD.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-iGq2PT_k.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-pPrqtlWS.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";
@@ -3125,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
@@ -3222,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;
@@ -3236,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-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-DWHxLHM5.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-QqrrK3yr.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-C0mWoWXC.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-5o1EkbLD.d.ts → behavior-B5PJ32eu.d.ts}

@@ -1091,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 {
@@ -1122,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
@@ -1139,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, 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.
+* 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`.
+*
+* 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
@@ -1195,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`
@@ -1306,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-DmGc-Mrn.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-r49nDwB4.js";
-import { h as Engine, m as AudioPlayer } from "./register-DOWGnxe1.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-CsJDUQh_.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-DFSW2Y30.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-C8Hi40qb.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
 /**