@woosh/meep-engine 3.60.4 → 3.60.6

package/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+`meep` is a proprietary, source-available engine — the full source ships in the npm package, but it is not open source. That being said - if you really would like to contribute to the engine's development - please reach out to me personally.
+
+Contributing to the engine will always assume full right transfer, as it is a proprietary project. See [LICENSE](LICENSE) for the terms the engine itself is distributed under. If you like what we do and want to work with us - it's best if you reach out to us.
+
+- Alex Goldring
+
+[Company Named](https://company-named.com)

package/MIGRATION_2_TO_3.md

@@ -0,0 +1,136 @@
+# Migrating 2.170.0 → 3.1.0
+
+There is no compatibility layer and no dual-boot. three.js is gone from the tree and from the
+dependency list; the renderer is Shade, on WebGPU.
+
+Read [RENDERER_CONTRACT.md](src/shade/RENDERER_CONTRACT.md) first if you touch rendering at all —
+it is the replacement for most of what is listed below.
+
+> **The names below carry a `3` that the current release does not.** These tables give the 3.1.0
+> spellings. In 4.0.0 the transition-era suffix was dropped: `GraphicsEngine3` is `GraphicsEngine`,
+> `MeshSystem3` is `MeshSystem`, and so on for every `*System3` in §2 and §4. The suffixed names
+> are still exported from their original modules as deprecated aliases, so everything written here
+> keeps working — but write the unsuffixed name in new code.
+
+---
+
+## 1. Before you start
+
+- **Your target needs WebGPU** with `indirect-first-instance`, `float32-blendable`, ≥10 storage
+  buffers per shader stage and ≥32 colour-attachment bytes per sample. There is no fallback: below
+  the floor, `Renderer.initialize()` rejects with a `ShadeDeviceFailure` carrying a message written
+  to be shown.
+- **Drop `three` from your own dependencies** if you had it only for meep. meep no longer declares
+  it, even optionally.
+- **Any code of yours that imports three must be ported.** meep exports no three types, and no
+  adapter is provided.
+
+## 2. Engine and renderer
+
+| 2.170.0 | 3.1.0 |
+|---|---|
+| `GraphicsEngine` | `GraphicsEngine3` |
+| `graphics.scene` (a three `Scene`) | **There is no scene getter, deliberately.** `GraphicsEngine3.set_scene(scene)` says which scene to draw; entities reach it through `MeshSystem3`, which owns the placement |
+| `graphics.layers`, `RenderLayer` | **No replacement.** Draw order is the renderer's; use a render extension's phase to place your own work |
+| `graphics.getMaterialManager()` | **No replacement.** Materials are `ShadeMaterial` / `StandardShadeMaterial`, held on the mesh |
+| `graphics.camera` (a three camera) | The `Camera` component. `Camera.object` is gone; frustum planes come from `camera_active_frustum` |
+| `renderer.add_pass` / `remove_pass`, `FramePhase`, `FramePassContext` | `RenderExtension` + `Renderer.add_extension`. See the contract, §6 |
+| `WebGLRendererPool`, `renderObjectToSampler2D` | `Renderer.render_to_target`, or `GraphicsEngine3.render_to_sampler` |
+| `WebGLContextMonitor` and the WebGL context-loss shims | `Renderer.onDeviceFailure` / `on.contextLost`. **Device loss is not recovered** — surface it and reload |
+| `?renderer=` switch | **Gone.** There is one renderer |
+
+## 3. Components
+
+| 2.170.0 | 3.1.0 |
+|---|---|
+| `Renderable` (v0), `Mesh` (v1) | `SGMesh` |
+| `Mesh.opacity` | **No replacement.** Per-instance opacity is not implemented |
+| A model as a tree inside one component | A model **expands into entities**; the nodes that draw carry `ShadedGeometry` |
+| `AnimationGraph` | **No replacement as a component.** Author state machines in your own layer; playback is `ClipListPlayer` / `AnimationGraphController` |
+| `Trail2D` | The component still exists but **nothing draws it**, and it was never serializable (`Trail2D.serializable = false`, no adapter), so no saved data references it. Use `Trail3D` |
+| `MeshFlags.InView` | **No replacement.** `SGMeshFlags` has no `InView`; nothing computes per-entity visibility on the CPU |
+
+**Level and save data.** `Mesh` components in shipped `level.bin` files were converted to `SGMesh`
+in-place. If you have your own level binaries written by 2.x, convert them the same way — through
+the engine's serializer, not by hand. There is no runtime upgrader: the component was replaced, not
+versioned.
+
+## 4. Systems
+
+| 2.170.0 | 3.1.0 |
+|---|---|
+| `RenderSystem`, `MeshSystem` | `MeshSystem3` (+ `ShadedGeometrySystem3`) |
+| `AnimationSystem`, `AnimationGraphSystem` | `AnimationGraphSystem3`, `GPUAnimationManager` |
+| `LightSystem` | **No replacement needed.** Lights live on the Shade scene; the "Shadow Quality" option this system fed is gone |
+| `CameraSystem` | `CameraSystem3` |
+| `ParticleEmitterSystem` (legacy) | `ParticleEmitterSystem3` |
+| `Trail2DSystem` | `Trail3DSystem3` |
+
+## 5. Geometry, materials, textures
+
+| 2.170.0 | 3.1.0 |
+|---|---|
+| three `BufferGeometry` | `Geometry` (authoring) → `meshlet_geometry_build_from_geometry` → `MeshletGeometry` (what a `Mesh` carries) |
+| three `Material`, `MeshStandardMaterial` | `ShadeMaterial`, `StandardShadeMaterial` |
+| three `Texture`, `DataTexture` | `ShadeTexture` over a `ShadeImage`. `Sampler2D` is still the CPU-side pixel type |
+| three `Plane` | `Vector4` — `x, y, z` normal, `w` constant |
+| `computeTextureEquality`, `computeTextureHash`, `TextureCoalescer`, `StaticMaterialCache` | **No replacement.** `ShadeTexture` and `ShadeImage` carry their own `equals`/`hash` and the renderer de-duplicates uploads |
+| three `DoubleSide`, `BackSide` | `ShadeMaterial.draw_side` — `ShadeDrawSide.Double` / `.Back`, against a `.Front` default. Back faces are shaded with a flipped normal. glTF `doubleSided` maps across on load |
+| DDS, DRACO | **No replacement.** Use the glTF PNG base sources. Compressed textures return later as their own feature |
+| `TopoMesh` | The `bt_*` binary-topology functions. Migration map: `src/core/geom/3d/topology/TOPO_MESH_RETIREMENT_PLAN.md` |
+
+**Content that rewrites its vertices every frame** — trails, ribbons, CPU particles, debug lines —
+goes down the dynamic-mesh path (`DynamicMesh` + `GPUDynamicMeshRenderer`), not through
+`MeshletGeometry`. Contract §8.
+
+## 6. Loading
+
+| 2.170.0 | 3.1.0 |
+|---|---|
+| three's `GLTFLoader` | `load_gltf(url, { assetManager, scope })` → `SceneBundle` |
+| A loaded model used directly in several places | `instantiate_scene_bundle(bundle)` per placement — a bundle is the model as loaded, not a placement of it |
+| The deferred texture loader | **No replacement.** It had no consumer |
+
+`load_gltf` requires an `AssetManager` — a glTF is several files, and they go back through the
+manager so they are cached, counted and cancellable. Two loaders are enough: `ArrayBuffer` and
+`ImageBitmap`.
+
+## 7. Baking and GI
+
+| 2.170.0 | 3.1.0 |
+|---|---|
+| meep's lightmap baker, LPG, LPV | Shade's **brick4** volumetric GI, and Shade's own LPV. meep's copies were backports and are deleted |
+| The terrain AO bake | **No replacement.** It is removed and generation no longer needs a GPU |
+| `renderObjectToSampler2D` previews | `GraphicsEngine3.render_to_sampler` |
+
+## 8. Smaller things
+
+- **Bone and socket positions**: `query_entity_node_world_pose(result, entity_manager, entity, node_name)`.
+  Reading a matrix off a skeleton is gone; a bone is a `Transform` + `TransformAttachment` pair.
+- **Attachment sockets are gone entirely** — `Attachment`, `AttachmentSystem`, `AttachmentSockets`
+  and the rest of `ecs/attachment` and `ecs/sockets`, along with `AttachmentSocketsAssetLoader` and
+  `GameAssetType.AttachmentSockets`. The API predated `TransformAttachment` and composed
+  `parent x socket x attachment` where `TransformAttachment` composes `parent x local`.
+  - A **transform socket** becomes a `TransformAttachment` whose `transform` is the socket's offset
+    composed with the attachment's own. The system handles parent destruction, keeps a
+    parent-to-children index, and recomposes on write instead of once a frame.
+  - A **bone socket** has no declarative replacement. Bones of a skinned or animated model are not
+    entities — a model expands into entities only when it has no skin and no clips — so ask
+    `query_entity_node_world_pose` for the bone and write the result yourself.
+  - `attachment-sockets.json` files are no longer an engine format. If you want to keep the named
+    anchor tables, load them as plain JSON in your own code and resolve the names at spawn time.
+- **`Animations.fade`**: the mesh half is dropped — a faded-out entity pops. No replacement;
+  per-instance opacity does not exist.
+- **Picking** is async and batched (`Pickable`, `PickingQuery`). There is no synchronous entry point,
+  by design.
+- **`stats.js`** is a peer dependency by its own name; it was three's bundled copy before.
+- **`gl-matrix`** is no longer a dependency; meep's own `m4_*` / `v3_*` functions replace it.
+- **`.d.ts` files** are not in the source tree. Run `npm run generate-types`; they land in
+  `publish/src`.
+
+## 9. If you are stuck
+
+The renderer contract is the reference for everything in §2 and §5–§7, including a worked example of
+putting a model on the screen and of adding your own work to a frame. Design documents for the parts
+with real depth sit next to the code: `renderer/extension/RENDER_EXTENSION_DESIGN.md`,
+`renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md`, `renderer/geometry/meshlet/README.md`.

package/SECURITY.md

@@ -0,0 +1,4 @@
+# Security
+
+Report a suspected vulnerability to **info@company-named.com** rather than disclosing it publicly.
+Include the engine version and the smallest reproduction you have.

package/editor/EditorCameraNavigation.d.ts

@@ -1,6 +1,7 @@
 /**
  * Always-on viewport camera navigation for the editor: right-drag orbits, middle-drag pans,
- * wheel zooms. Editing tools keep the primary button to themselves.
+ * wheel zooms, through an {@link OrbitalCameraRig}. Editing tools keep the primary button to
+ * themselves.
  *
  * The editor camera is driven here, per engine tick, straight from its controller state —
  * the TopDownCameraControllerSystem stays disabled while editing so controller-bearing

package/editor/EditorCameraNavigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EditorCameraNavigation.d.ts","sourceRoot":"","sources":["../../editor/EditorCameraNavigation.js"],"names":[],"mappings":"AAuCA;;;;;;;GAOG;AACH;IA2CI;;;;;;OAMG;IACH,mCAJW,uBAAuB,qDAqCjC;IAED,eAmBC;;CAqDJ;oCAxMmC,sEAAsE"}
+{"version":3,"file":"EditorCameraNavigation.d.ts","sourceRoot":"","sources":["../../editor/EditorCameraNavigation.js"],"names":[],"mappings":"AA0BA;;;;;;;;GAQG;AACH;IAqDI;;;;;;OAMG;IACH,mCAJW,uBAAuB,qDA+CjC;IAED,eAsBC;;CAoCJ;oCAjMM,sEAAsE"}

package/editor/EditorCameraNavigation.js

@@ -1,16 +1,12 @@
 import { assert } from "../src/core/assert.js";
-import Vector2 from "../src/core/geom/Vector2.js";
 import Vector3 from "../src/core/geom/Vector3.js";
-import { clamp } from "../src/core/math/clamp.js";
-import TopDownCameraController from "../src/engine/graphics/ecs/camera/topdown/TopDownCameraController.js";
-import {
+import { OrbitalCameraRig } from "../src/engine/graphics/camera/orbital/OrbitalCameraRig.js";
+import TopDownCameraController, {
     computeTopDownTransform
-} from "../src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js";
-import { decodeMouseEventButtons } from "../src/engine/input/devices/mouse/decodeMouseEventButtons.js";
+} from "../src/engine/graphics/ecs/camera/topdown/TopDownCameraController.js";
+import { MouseEventButtons } from "../src/engine/input/devices/mouse/MouseEventButtons.js";
 import { PointerDevice } from "../src/engine/input/devices/PointerDevice.js";
 
-const ORBIT_SENSITIVITY = 0.008;
-
 /**
  * Pitch 0 looks along the horizon, PI/2 looks straight down. Below 0 the camera swings
  * under the ground plane, where the terrain is backfacing and the scene is invisible;
@@ -21,13 +17,6 @@ const PITCH_MIN = 0.05;
 
 const PITCH_MAX = Math.PI / 2;
 
-/**
- * Wheel deltas reach us normalized to -1/0/+1 by {@link PointerDevice}, so a notch is a
- * multiplicative step on the orbit distance rather than a function of the raw pixel delta.
- * @type {number}
- */
-const ZOOM_STEP = 1.1;
-
 /**
  * The orbit pivot belongs on the ground plane — lifting it makes every subsequent orbit
  * swing about a point floating in the air. Panning therefore moves it in XZ only.
@@ -35,11 +24,10 @@ const ZOOM_STEP = 1.1;
  */
 const v3_pan_axis = new Vector3(1, 0, 1);
 
-const v2_pan_delta = new Vector2();
-
 /**
  * Always-on viewport camera navigation for the editor: right-drag orbits, middle-drag pans,
- * wheel zooms. Editing tools keep the primary button to themselves.
+ * wheel zooms, through an {@link OrbitalCameraRig}. Editing tools keep the primary button to
+ * themselves.
  *
  * The editor camera is driven here, per engine tick, straight from its controller state —
  * the TopDownCameraControllerSystem stays disabled while editing so controller-bearing
@@ -61,6 +49,11 @@ export class EditorCameraNavigation {
      */
     #controller = null;
 
+    /**
+     * @type {OrbitalCameraRig|null}
+     */
+    #rig = null;
+
     /**
      * the editor camera's transform, written every tick
      * @type {Transform|null}
@@ -84,7 +77,12 @@ export class EditorCameraNavigation {
      */
     #context_menu_suppressor = null;
 
-    #handleTick = () => {
+    /**
+     * @param {number} time_delta seconds
+     */
+    #handleTick = (time_delta) => {
+        this.#rig.update(time_delta);
+
         computeTopDownTransform(this.#controller, this.#camera_transform);
     };
 
@@ -103,10 +101,18 @@ export class EditorCameraNavigation {
         this.#camera_transform = camera_transform;
         this.#camera = camera;
 
+        this.#rig = new OrbitalCameraRig(controller, {
+            orbit_buttons: MouseEventButtons.secondary,
+            pan_buttons: MouseEventButtons.auxiliary,
+            pitch_min: PITCH_MIN,
+            pitch_max: PITCH_MAX,
+            pan_axes: v3_pan_axis
+        });
+
         engine.ticker.onTick.add(this.#handleTick);
 
         // apply the current controller state immediately, ticks may be a frame away
-        this.#handleTick();
+        computeTopDownTransform(controller, camera_transform);
 
         const graphics = engine.graphics;
 
@@ -122,7 +128,9 @@ export class EditorCameraNavigation {
 
         const pointer = new PointerDevice(dom);
 
+        pointer.on.dragStart.add(this.#handleDragStart, this);
         pointer.on.drag.add(this.#handleDrag, this);
+        pointer.on.dragEnd.add(this.#handleDragEnd, this);
         pointer.on.wheel.add(this.#handleWheel, this);
 
         pointer.start();
@@ -134,7 +142,9 @@ export class EditorCameraNavigation {
         this.#engine.ticker.onTick.remove(this.#handleTick);
 
         if (this.#pointer !== null) {
+            this.#pointer.on.dragStart.remove(this.#handleDragStart, this);
             this.#pointer.on.drag.remove(this.#handleDrag, this);
+            this.#pointer.on.dragEnd.remove(this.#handleDragEnd, this);
             this.#pointer.on.wheel.remove(this.#handleWheel, this);
             this.#pointer.stop();
             this.#pointer = null;
@@ -147,44 +157,36 @@ export class EditorCameraNavigation {
 
         this.#engine = null;
         this.#controller = null;
+        this.#rig = null;
         this.#camera_transform = null;
         this.#camera = null;
     }
 
+    /**
+     * @param {Vector2} origin
+     * @param {MouseEvent} event
+     */
+    #handleDragStart(origin, event) {
+        this.#rig.begin(event.buttons);
+    }
+
     /**
      *
      * @param {Vector2} position
      * @param {Vector2} origin
      * @param {Vector2} previousPosition
-     * @param {MouseEvent} event
      */
-    #handleDrag(position, origin, previousPosition, event) {
-        const buttons = decodeMouseEventButtons(event.buttons);
-
-        const controller = this.#controller;
-
-        if (buttons[1]) {
-            // secondary (right) button: orbit
-            const dx = position.x - previousPosition.x;
-            const dy = position.y - previousPosition.y;
-
-            controller.yaw += dx * ORBIT_SENSITIVITY;
-            controller.pitch = clamp(controller.pitch + dy * ORBIT_SENSITIVITY, PITCH_MIN, PITCH_MAX);
-        } else if (buttons[2]) {
-            // auxiliary (middle) button: pan
-            const graphics = this.#engine.graphics;
-
-            v2_pan_delta.copy(previousPosition);
-            v2_pan_delta.sub(position);
-
-            TopDownCameraController.pan(
-                v2_pan_delta,
-                controller,
-                graphics.viewport.size.y,
-                this.#camera.fov.getValue(),
-                v3_pan_axis
-            );
-        }
+    #handleDrag(position, origin, previousPosition) {
+        this.#rig.move(
+            position.x - previousPosition.x,
+            position.y - previousPosition.y,
+            this.#engine.graphics.viewport.size.y,
+            this.#camera.fov.getValue()
+        );
+    }
+
+    #handleDragEnd() {
+        this.#rig.end();
     }
 
     /**
@@ -192,14 +194,6 @@ export class EditorCameraNavigation {
      * @param {Vector3} delta
      */
     #handleWheel(delta) {
-        const controller = this.#controller;
-
-        const factor = Math.pow(ZOOM_STEP, delta.y);
-
-        controller.distance = clamp(
-            controller.distance * factor,
-            controller.distanceMin,
-            controller.distanceMax
-        );
+        this.#rig.dolly(delta.y);
     }
 }

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.60.4",
+  "version": "3.60.6",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",
@@ -41,7 +41,11 @@
     "editor",
     "samples",
     "package.json",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "MIGRATION_2_TO_3.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
   ],
   "dependencies": {
     "opentype.js": "1.3.4",

package/src/engine/EngineHarness.d.ts

@@ -75,10 +75,9 @@ export class EngineHarness {
      * @param {number} [params.cameraFarDistance]
      * @param {boolean} [params.cameraController=true]
      * @param {boolean} [params.cameraAutoClip]
-     * @param {number} [params.shadowmapResolution]
      * @param {boolean} [params.showFps]
      */
-    static buildBasics({ engine, focus, heightMap, heightRange, pitch, yaw, distance, terrainSize, terrainResolution, enableWater, enableTerrain, enableLights, enableShadows, cameraFieldOfView, cameraFarDistance, cameraController, cameraAutoClip, shadowmapResolution, showFps }: {
+    static buildBasics({ engine, focus, heightMap, heightRange, pitch, yaw, distance, terrainSize, terrainResolution, enableWater, enableTerrain, enableLights, enableShadows, cameraFieldOfView, cameraFarDistance, cameraController, cameraAutoClip, showFps }: {
         engine: Engine;
         focus?: {
             x: number;
@@ -103,14 +102,12 @@ export class EngineHarness {
         cameraFarDistance?: number;
         cameraController?: boolean;
         cameraAutoClip?: boolean;
-        shadowmapResolution?: number;
         showFps?: boolean;
     }): Promise<void>;
     /**
      * @param {Object} param
      * @param {Engine} param.engine
      * @param {EntityComponentDataset} [param.ecd]
-     * @param {number} [param.shadowmapResolution]
      * @param {boolean} [param.castShadow]
      * @param {Color} [param.sun]
      * @param {number} [param.sunIntensity]
@@ -119,10 +116,9 @@ export class EngineHarness {
      * @param {number} [param.ambientIntensity]
      * @param {number} [param.sunShadowDistance] Maximum draw distance for sun's shadow. Allows better use of shadowmap resolution.
      */
-    static buildLights({ engine, ecd, shadowmapResolution, castShadow, sun, sunIntensity, sunDirection, sunShadowDistance, ambient, ambientIntensity }: {
+    static buildLights({ engine, ecd, castShadow, sun, sunIntensity, sunDirection, sunShadowDistance, ambient, ambientIntensity }: {
         engine: Engine;
         ecd?: EntityComponentDataset;
-        shadowmapResolution?: number;
         castShadow?: boolean;
         sun?: Color;
         sunIntensity?: number;
@@ -135,14 +131,12 @@ export class EngineHarness {
      * @param {Object} param
      * @param {number} [param.cameraEntity]
      * @param {Engine} param.engine
-     * @param {number} [param.sensitivity]
      * @param {EntityComponentDataset} [param.ecd]
      * @returns {Promise<Entity>}
      */
-    static buildOrbitalCameraController({ cameraEntity, engine, ecd, sensitivity }: {
+    static buildOrbitalCameraController({ cameraEntity, engine, ecd, }: {
         cameraEntity?: number;
         engine: Engine;
-        sensitivity?: number;
         ecd?: EntityComponentDataset;
     }): Promise<Entity>;
     /**

package/src/engine/EngineHarness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EngineHarness.d.ts","sourceRoot":"","sources":["../../../src/engine/EngineHarness.js"],"names":[],"mappings":"AAoFA;IAmBI;;;;;OAKG;IACH;QAHmE,aAAa,GAArE,CAAC,MAAM,EAAC,mBAAmB,EAAC,MAAM,EAAC,MAAM,QAAI;QAC5C,QAAQ,MAAM,CAAC,CAM1B;IAED;;;;;;;;;OASG;IACH,0BAHW,MAAM,GACJ,KAAK,CAYjB;IAED;;;;;;;;;OASG;IACH,6BAHW,MAAM,GACJ,aAAa,CAQzB;IAkED;;;;;;;;;;;;;OAaG;IACH;QAZyB,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACN,MAAM,GAAtB,OAAO;QACQ,QAAQ,GAAvB,MAAM;QACS,KAAK,GAApB,MAAM;QACS,GAAG,GAAlB,MAAM;QACU,QAAQ,GAAxB,OAAO;QACQ,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACJ,MAAM,CA+DlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QApB0B,MAAM,EAArB,MAAM;QACgC,KAAK,GAA3C;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC;QACrB,SAAS;QACT,WAAW;QACF,KAAK,GAArB,MAAM;QACU,GAAG,GAAnB,MAAM;QACU,QAAQ,GAAxB,MAAM;QACwB,WAAW,GAAzC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAC,CAAC,EAAC,MAAM,CAAA;SAAC;QACJ,iBAAiB,GAAjC,MAAM;QACW,WAAW,GAA5B,OAAO;QACU,aAAa,GAA9B,OAAO;QACU,YAAY,GAA7B,OAAO;QACU,aAAa,GAA9B,OAAO;QACS,iBAAiB,GAAjC,MAAM;QACU,iBAAiB,GAAjC,MAAM;QACW,gBAAgB,GAAjC,OAAO;QACU,cAAc,GAA/B,OAAO;QACS,mBAAmB,GAAnC,MAAM;QACW,OAAO,GAAxB,OAAO;sBA0EjB;IAGD;;;;;;;;;;;;OAYG;IACH;QAXyB,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACP,mBAAmB,GAAlC,MAAM;QACU,UAAU,GAA1B,OAAO;QACO,GAAG,GAAjB,KAAK;QACU,YAAY,GAA3B,MAAM;QACU,YAAY,GAA5B,OAAO;QACO,OAAO,GAArB,KAAK;QACU,gBAAgB,GAA/B,MAAM;QACS,iBAAiB,GAAhC,MAAM;sBA2DhB;IAED;;;;;;;OAOG;IACH;QAN0B,YAAY,GAA3B,MAAM;QACQ,MAAM,EAApB,MAAM;QACS,WAAW,GAA1B,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACpB,QAAQ,MAAM,CAAC,CA6C3B;IAGD;;;;;;;;;;OAUG;IACH;QAR2B,MAAM,EAAtB,MAAM;QACY,IAAI,GAAtB,OAAO;QACU,QAAQ;QACR,UAAU,GAA3B,MAAM;QACW,UAAU,GAA3B,MAAM;QACY,WAAW,GAA7B,OAAO;QACL,OAAO,CAwEnB;IAngBD;;;OAGG;IACH,YAFU,eAAQ,IAAI,CAEb;IAGL;;;OAGG;IACH,QAFU,MAAM,CAEiC;IA2DrD;;;;;OAKG;IACH;QAJkE,aAAa,GAApE,CAAC,MAAM,EAAC,mBAAmB,EAAC,MAAM,EAAC,MAAM,QAAI;QAC5B,mBAAmB,GAApC,OAAO;QACL,QAAQ,MAAM,CAAC,CA0D3B;CAgYJ;;IAID;;;OAGG;IACH,uCAMC;;qCA3jBY,OAAO,iCAAiC,EAAE,sBAAsB;mBA7B1D,aAAa;oCACI,0BAA0B;sBAQxC,kCAAkC;8BAlB1B,mCAAmC;oBAD7C,yBAAyB;mBAK1B,iBAAiB;sBATd,wBAAwB;oBAG1B,yBAAyB;oBAQzB,8BAA8B"}
+{"version":3,"file":"EngineHarness.d.ts","sourceRoot":"","sources":["../../../src/engine/EngineHarness.js"],"names":[],"mappings":"AAqFA;IAmBI;;;;;OAKG;IACH;QAHmE,aAAa,GAArE,CAAC,MAAM,EAAC,mBAAmB,EAAC,MAAM,EAAC,MAAM,QAAI;QAC5C,QAAQ,MAAM,CAAC,CAM1B;IAED;;;;;;;;;OASG;IACH,0BAHW,MAAM,GACJ,KAAK,CAYjB;IAED;;;;;;;;;OASG;IACH,6BAHW,MAAM,GACJ,aAAa,CAQzB;IAkED;;;;;;;;;;;;;OAaG;IACH;QAZyB,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACN,MAAM,GAAtB,OAAO;QACQ,QAAQ,GAAvB,MAAM;QACS,KAAK,GAApB,MAAM;QACS,GAAG,GAAlB,MAAM;QACU,QAAQ,GAAxB,OAAO;QACQ,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACJ,MAAM,CA+DlB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH;QAnB0B,MAAM,EAArB,MAAM;QACgC,KAAK,GAA3C;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC;QACrB,SAAS;QACT,WAAW;QACF,KAAK,GAArB,MAAM;QACU,GAAG,GAAnB,MAAM;QACU,QAAQ,GAAxB,MAAM;QACwB,WAAW,GAAzC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAC,CAAC,EAAC,MAAM,CAAA;SAAC;QACJ,iBAAiB,GAAjC,MAAM;QACW,WAAW,GAA5B,OAAO;QACU,aAAa,GAA9B,OAAO;QACU,YAAY,GAA7B,OAAO;QACU,aAAa,GAA9B,OAAO;QACS,iBAAiB,GAAjC,MAAM;QACU,iBAAiB,GAAjC,MAAM;QACW,gBAAgB,GAAjC,OAAO;QACU,cAAc,GAA/B,OAAO;QACU,OAAO,GAAxB,OAAO;sBAwEjB;IAGD;;;;;;;;;;;OAWG;IACH;QAVyB,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACN,UAAU,GAA1B,OAAO;QACO,GAAG,GAAjB,KAAK;QACU,YAAY,GAA3B,MAAM;QACU,YAAY,GAA5B,OAAO;QACO,OAAO,GAArB,KAAK;QACU,gBAAgB,GAA/B,MAAM;QACS,iBAAiB,GAAhC,MAAM;sBA0DhB;IAED;;;;;;OAMG;IACH;QAL0B,YAAY,GAA3B,MAAM;QACQ,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACpB,QAAQ,MAAM,CAAC,CAgD3B;IAGD;;;;;;;;;;OAUG;IACH;QAR2B,MAAM,EAAtB,MAAM;QACY,IAAI,GAAtB,OAAO;QACU,QAAQ;QACR,UAAU,GAA3B,MAAM;QACW,UAAU,GAA3B,MAAM;QACY,WAAW,GAA7B,OAAO;QACL,OAAO,CAwEnB;IAhgBD;;;OAGG;IACH,YAFU,eAAQ,IAAI,CAEb;IAGL;;;OAGG;IACH,QAFU,MAAM,CAEiC;IA2DrD;;;;;OAKG;IACH;QAJkE,aAAa,GAApE,CAAC,MAAM,EAAC,mBAAmB,EAAC,MAAM,EAAC,MAAM,QAAI;QAC5B,mBAAmB,GAApC,OAAO;QACL,QAAQ,MAAM,CAAC,CA0D3B;CA6XJ;;IAID;;;OAGG;IACH,uCAMC;;qCAxjBY,OAAO,iCAAiC,EAAE,sBAAsB;mBA7B1D,aAAa;oCACI,0BAA0B;sBAQxC,kCAAkC;8BAnB1B,mCAAmC;oBAD7C,yBAAyB;mBAK1B,iBAAiB;sBATd,wBAAwB;oBAG1B,yBAAyB;oBASzB,8BAA8B"}

package/src/engine/EngineHarness.js

@@ -9,6 +9,7 @@ import { JsonAssetLoader } from "./asset/loaders/JsonAssetLoader.js";
 import { SerializationMetadata } from "./ecs/components/SerializationMetadata.js";
 import Tag from "./ecs/components/Tag.js";
 import Entity from "./ecs/Entity.js";
+import ScriptSystem from "./ecs/systems/ScriptSystem.js";
 import { TerrainLayer } from "./ecs/terrain/ecs/layers/TerrainLayer.js";
 import Terrain from "./ecs/terrain/ecs/Terrain.js";
 import { Transform64 } from "./ecs/transform/Transform64.js";
@@ -313,7 +314,6 @@ export class EngineHarness {
      * @param {number} [params.cameraFarDistance]
      * @param {boolean} [params.cameraController=true]
      * @param {boolean} [params.cameraAutoClip]
-     * @param {number} [params.shadowmapResolution]
      * @param {boolean} [params.showFps]
      */
     static async buildBasics({
@@ -334,7 +334,6 @@ export class EngineHarness {
                                  cameraFarDistance,
                                  cameraController = true,
                                  cameraAutoClip = true,
-                                 shadowmapResolution,
                                  showFps = false
                              }) {
 
@@ -345,7 +344,6 @@ export class EngineHarness {
         if (enableLights) {
             await EngineHarness.buildLights({
                 engine: engine,
-                shadowmapResolution,
                 castShadow: enableShadows,
             });
         }
@@ -395,7 +393,6 @@ export class EngineHarness {
      * @param {Object} param
      * @param {Engine} param.engine
      * @param {EntityComponentDataset} [param.ecd]
-     * @param {number} [param.shadowmapResolution]
      * @param {boolean} [param.castShadow]
      * @param {Color} [param.sun]
      * @param {number} [param.sunIntensity]
@@ -407,7 +404,6 @@ export class EngineHarness {
     static async buildLights({
                                  engine,
                                  ecd = engine.entityManager.dataset,
-                                 shadowmapResolution = 2048,
                                  castShadow = true,
                                  sun = DEFAULT_SUNLIGHT_COLOR,
                                  sunIntensity = 0.9,
@@ -467,7 +463,6 @@ export class EngineHarness {
      * @param {Object} param
      * @param {number} [param.cameraEntity]
      * @param {Engine} param.engine
-     * @param {number} [param.sensitivity]
      * @param {EntityComponentDataset} [param.ecd]
      * @returns {Promise<Entity>}
      */
@@ -475,7 +470,6 @@ export class EngineHarness {
                                                   cameraEntity,
                                                   engine,
                                                   ecd = engine.entityManager.dataset,
-                                                  sensitivity = 1
                                               }) {
 
         if (cameraEntity === undefined) {
@@ -490,6 +484,11 @@ export class EngineHarness {
             await em.addSystem(new InputControllerSystem(engine.devices));
         }
 
+        // the orbit's throw and the keyboard pan advance in scripts
+        if (em.getSystem(ScriptSystem) === null) {
+            await em.addSystem(new ScriptSystem());
+        }
+
         if (!ecd.isComponentTypeRegistered(SerializationMetadata)) {
             ecd.registerComponentType(SerializationMetadata);
         }
@@ -505,7 +504,6 @@ export class EngineHarness {
             camera_entity: cameraEntity,
             ecd,
             dom_element: domElement,
-            sensitivity
         });
 
         eb.add(Tag.fromJSON(['CameraController']));

package/src/engine/graphics/camera/makeOrbitalCameraController.d.ts

@@ -1,17 +1,20 @@
 /**
+ * Pointer navigation for a camera entity's {@link TopDownCameraController}: drag with the primary
+ * button (or a touch) to orbit, with the secondary to pan, the wheel to zoom. A drag moves the camera
+ * as it happens and throws on release; see {@link OrbitalCameraRig}.
+ *
+ * The orbit swings all the way round, under the target included, short of turning over at the poles.
  *
  * @param {Object} options
- * @param {number} options.camera_entity
+ * @param {number} options.camera_entity carries the {@link TopDownCameraController} and {@link Camera}
  * @param {EntityComponentDataset} options.ecd
- * @param {HTMLElement} options.dom_element
- * @param {number} [options.sensitivity]
- * @return {Entity}
+ * @param {HTMLElement} options.dom_element the viewport, measured for its height
+ * @return {Entity} transient, to be built into the dataset
  */
-export function makeOrbitalCameraController({ camera_entity, ecd, dom_element, sensitivity }: {
+export function makeOrbitalCameraController({ camera_entity, ecd, dom_element, }: {
     camera_entity: number;
     ecd: EntityComponentDataset;
     dom_element: HTMLElement;
-    sensitivity?: number;
 }): Entity;
 import Entity from "../../ecs/Entity.js";
 //# sourceMappingURL=makeOrbitalCameraController.d.ts.map

package/src/engine/graphics/camera/makeOrbitalCameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"makeOrbitalCameraController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/camera/makeOrbitalCameraController.js"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AACH;IAN2B,aAAa,EAA7B,MAAM;IAC0B,GAAG;IACd,WAAW,EAAhC,WAAW;IACM,WAAW,GAA5B,MAAM;IACL,MAAM,CA8FjB;mBA3GkB,qBAAqB"}
+{"version":3,"file":"makeOrbitalCameraController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/camera/makeOrbitalCameraController.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;GAYG;AACH;IAL2B,aAAa,EAA7B,MAAM;IAC0B,GAAG;IACd,WAAW,EAAhC,WAAW;IACV,MAAM,CA4DjB;mBA9EkB,qBAAqB"}