@waica/engine 0.28.0 → 0.29.0

package/dist/scene-camera-3d.js

@@ -1,3 +1,5 @@
+import { orbitCameraIssues, resolveOrbit } from './scene-camera-orbit.js';
+import { isFiniteNumber, shown } from './scene-field-issues.js';
 export const PERSPECTIVE_DEFAULTS = {
     position: [0, 5, 10],
     target: [0, 0, 0],
@@ -18,8 +20,13 @@ export function resolvePerspectiveCamera(json = { kind: 'perspective' }) {
         fov: json.fov ?? PERSPECTIVE_DEFAULTS.fov,
         near: json.near ?? PERSPECTIVE_DEFAULTS.near,
         far: json.far ?? PERSPECTIVE_DEFAULTS.far,
+        ...orbitOf(json),
     };
 }
+function orbitOf(json) {
+    const orbit = resolveOrbit(json);
+    return orbit ? { orbit } : {};
+}
 /** Points `camera` as the resolved block says, at the given aspect ratio. */
 export function placePerspectiveCamera(camera, resolved, aspect) {
     camera.fov = resolved.fov;
@@ -31,11 +38,7 @@ export function placePerspectiveCamera(camera, resolved, aspect) {
     camera.updateProjectionMatrix();
     camera.updateMatrixWorld();
 }
-/** A JSON value as a message quotes it: strings in quotes, everything else as `String()` shows it. */
-export const shown = (value) => (typeof value === 'string' ? JSON.stringify(value) : String(value));
-export function isFiniteNumber(value) {
-    return typeof value === 'number' && Number.isFinite(value);
-}
+export { isFiniteNumber, shown } from './scene-field-issues.js';
 function vectorIssue(field, value, issues) {
     if (value === undefined)
         return;
@@ -76,9 +79,8 @@ function planeIssues(near, far, issues) {
         issues.push({ field: 'camera.far', message: `camera.far must be a number above near (${nearValue}); got ${shown(far)}.` });
     }
 }
-/** The orthographic block's fields, which a perspective block does not accept. */
+/** The orthographic block's fields, which a perspective block does not accept (`follow` it does, issue #181). */
 const ORTHOGRAPHIC_ONLY_FIELDS = [
-    'follow',
     'zoom',
     'deadzoneWidth',
     'deadzoneHeight',
@@ -96,9 +98,10 @@ function orthographicFieldIssues(block, issues) {
 }
 /**
  * Every field of a perspective camera block outside its range: `fov` in
- * (0, 180), `near` above 0, `far` above `near`, and `position` and `target`
- * three finite numbers, and none of the orthographic block's fields. Anything
- * that is not a perspective block reports none.
+ * (0, 180), `near` above 0, `far` above `near`, `position` and `target`
+ * three finite numbers, the orbit fields (orbitCameraIssues), and none of the
+ * orthographic block's other fields. Anything that is not a perspective block
+ * reports none.
  */
 export function perspectiveCameraIssues(camera) {
     if (typeof camera !== 'object' || camera === null)
@@ -113,5 +116,6 @@ export function perspectiveCameraIssues(camera) {
     aimIssue(block, issues);
     planeIssues(block.near, block.far, issues);
     orthographicFieldIssues(block, issues);
+    issues.push(...orbitCameraIssues(block));
     return issues;
 }

package/dist/scene-camera-orbit.d.ts

@@ -0,0 +1,72 @@
+import { type SceneFieldIssue } from './scene-field-issues.js';
+/**
+ * The orbit fields of a scene's perspective camera block (issue #181, ADR
+ * 0031): with `follow`, the camera orbits that entity instead of staying
+ * where `position` and `target` put it. Angles are degrees; `yaw` 0 looks
+ * toward -z (the camera sits on +z), 90 toward +x; `pitch` is the camera's
+ * height above the look point, positive looking down.
+ */
+export interface OrbitCameraJson {
+    /** The entity to orbit; absent or empty keeps the camera fixed. */
+    follow?: string;
+    /** The chosen distance from the look point. Default 6. */
+    distance?: number;
+    /** The wheel's closest distance. Default 2. */
+    minDistance?: number;
+    /** The wheel's farthest distance. Default 12. */
+    maxDistance?: number;
+    /** Initial yaw, in degrees. Default 0. */
+    yaw?: number;
+    /** Initial pitch, in degrees, in (-89, 89). Default 20. */
+    pitch?: number;
+    /** Lowest pitch, in (-89, 89). Default -10. */
+    minPitch?: number;
+    /** Highest pitch, in (-89, 89). Default 70. */
+    maxPitch?: number;
+    /** How far above the followed entity's position the camera looks. Default 1.2. */
+    lookHeight?: number;
+    /** Degrees of orbit per CSS pixel of locked mouse movement. Default 0.2. */
+    sensitivity?: number;
+    /** Degrees per second the orbit Actions turn at full value. Default 120. */
+    orbitSpeed?: number;
+    /** Flips the mouse's vertical orbit. Default false. */
+    invertY?: boolean;
+    /** The Action that orbits left (yaw down). Default `look_left`. */
+    orbitLeftAction?: string;
+    /** The Action that orbits right (yaw up). Default `look_right`. */
+    orbitRightAction?: string;
+    /** The Action that looks up (pitch down). Default `look_up`. */
+    orbitUpAction?: string;
+    /** The Action that looks down (pitch up). Default `look_down`. */
+    orbitDownAction?: string;
+}
+/** Every orbit field resolved; `follow` names the entity. */
+export type ResolvedOrbit = Required<OrbitCameraJson>;
+export declare const ORBIT_DEFAULTS: {
+    readonly distance: 6;
+    readonly minDistance: 2;
+    readonly maxDistance: 12;
+    readonly yaw: 0;
+    readonly pitch: 20;
+    readonly minPitch: -10;
+    readonly maxPitch: 70;
+    readonly lookHeight: 1.2;
+    readonly sensitivity: 0.2;
+    readonly orbitSpeed: 120;
+    readonly invertY: false;
+    readonly orbitLeftAction: 'look_left';
+    readonly orbitRightAction: 'look_right';
+    readonly orbitUpAction: 'look_up';
+    readonly orbitDownAction: 'look_down';
+};
+/** The orbit a block declares with its defaults filled, or null for a fixed camera (no `follow`). */
+export declare function resolveOrbit(json: OrbitCameraJson): ResolvedOrbit | null;
+/**
+ * Every orbit field of a perspective block outside its range: the numbers
+ * (distances above 0, pitches in (-89, 89), speeds at least 0), `invertY`,
+ * the Action names, and a `minDistance` or `minPitch` above its maximum
+ * (errors); and a following camera's initial `distance` or `pitch` outside
+ * its own range (warnings). Whether `follow` names an entity of the scene is
+ * the scene validator's.
+ */
+export declare function orbitCameraIssues(block: Record<string, unknown>): SceneFieldIssue[];

package/dist/scene-camera-orbit.js

@@ -0,0 +1,155 @@
+import { isFiniteNumber, shown } from './scene-field-issues.js';
+const ACTION_FIELDS = ['orbitLeftAction', 'orbitRightAction', 'orbitUpAction', 'orbitDownAction'];
+export const ORBIT_DEFAULTS = {
+    distance: 6,
+    minDistance: 2,
+    maxDistance: 12,
+    yaw: 0,
+    pitch: 20,
+    minPitch: -10,
+    maxPitch: 70,
+    lookHeight: 1.2,
+    sensitivity: 0.2,
+    orbitSpeed: 120,
+    invertY: false,
+    orbitLeftAction: 'look_left',
+    orbitRightAction: 'look_right',
+    orbitUpAction: 'look_up',
+    orbitDownAction: 'look_down',
+};
+/** The orbit a block declares with its defaults filled, or null for a fixed camera (no `follow`). */
+export function resolveOrbit(json) {
+    if (!json.follow)
+        return null;
+    return { follow: json.follow, ...resolveFraming(json), ...resolveControls(json) };
+}
+/** Where the camera sits: distances, angles and the look height. */
+function resolveFraming(json) {
+    return {
+        distance: json.distance ?? ORBIT_DEFAULTS.distance,
+        minDistance: json.minDistance ?? ORBIT_DEFAULTS.minDistance,
+        maxDistance: json.maxDistance ?? ORBIT_DEFAULTS.maxDistance,
+        yaw: json.yaw ?? ORBIT_DEFAULTS.yaw,
+        pitch: json.pitch ?? ORBIT_DEFAULTS.pitch,
+        minPitch: json.minPitch ?? ORBIT_DEFAULTS.minPitch,
+        maxPitch: json.maxPitch ?? ORBIT_DEFAULTS.maxPitch,
+        lookHeight: json.lookHeight ?? ORBIT_DEFAULTS.lookHeight,
+    };
+}
+/** How input turns it: the mouse, the orbit Actions and their speed. */
+function resolveControls(json) {
+    return {
+        sensitivity: json.sensitivity ?? ORBIT_DEFAULTS.sensitivity,
+        orbitSpeed: json.orbitSpeed ?? ORBIT_DEFAULTS.orbitSpeed,
+        invertY: json.invertY ?? ORBIT_DEFAULTS.invertY,
+        orbitLeftAction: json.orbitLeftAction ?? ORBIT_DEFAULTS.orbitLeftAction,
+        orbitRightAction: json.orbitRightAction ?? ORBIT_DEFAULTS.orbitRightAction,
+        orbitUpAction: json.orbitUpAction ?? ORBIT_DEFAULTS.orbitUpAction,
+        orbitDownAction: json.orbitDownAction ?? ORBIT_DEFAULTS.orbitDownAction,
+    };
+}
+/** The rule each numeric orbit field must meet, and how its message says it. */
+const NUMBER_RULES = [
+    { field: 'distance', accepts: (value) => value > 0, rule: 'a number above 0' },
+    { field: 'minDistance', accepts: (value) => value > 0, rule: 'a number above 0' },
+    { field: 'maxDistance', accepts: (value) => value > 0, rule: 'a number above 0' },
+    { field: 'yaw', accepts: () => true, rule: 'a finite number' },
+    { field: 'pitch', accepts: (value) => Math.abs(value) < 89, rule: 'a number above -89 and below 89' },
+    { field: 'minPitch', accepts: (value) => Math.abs(value) < 89, rule: 'a number above -89 and below 89' },
+    { field: 'maxPitch', accepts: (value) => Math.abs(value) < 89, rule: 'a number above -89 and below 89' },
+    { field: 'lookHeight', accepts: () => true, rule: 'a finite number' },
+    { field: 'sensitivity', accepts: (value) => value >= 0, rule: 'a number of at least 0' },
+    { field: 'orbitSpeed', accepts: (value) => value >= 0, rule: 'a number of at least 0' },
+];
+function numberIssues(block, issues) {
+    for (const { field, accepts, rule } of NUMBER_RULES) {
+        const value = block[field];
+        if (value === undefined || (isFiniteNumber(value) && accepts(value)))
+            continue;
+        issues.push({ field: `camera.${field}`, message: `camera.${field} must be ${rule}; got ${shown(value)}.` });
+    }
+}
+function actionIssues(block, issues) {
+    for (const field of ACTION_FIELDS) {
+        const value = block[field];
+        if (value === undefined || (typeof value === 'string' && value.length > 0))
+            continue;
+        issues.push({ field: `camera.${field}`, message: `camera.${field} must be an Action name; got ${shown(value)}.` });
+    }
+}
+function fieldIssues(block, issues) {
+    if (block.follow !== undefined && typeof block.follow !== 'string') {
+        issues.push({ field: 'camera.follow', message: `camera.follow must be an entity name; got ${shown(block.follow)}.` });
+    }
+    numberIssues(block, issues);
+    if (block.invertY !== undefined && typeof block.invertY !== 'boolean') {
+        issues.push({ field: 'camera.invertY', message: `camera.invertY must be true or false; got ${shown(block.invertY)}.` });
+    }
+    actionIssues(block, issues);
+}
+function rangeIssue(block, [low, high], issues) {
+    const min = block[low];
+    const max = block[high];
+    const fallback = ORBIT_DEFAULTS;
+    const lowValue = min ?? fallback[low];
+    const highValue = max ?? fallback[high];
+    if (!isFiniteNumber(lowValue) || !isFiniteNumber(highValue) || lowValue <= highValue)
+        return;
+    issues.push({
+        field: `camera.${low}`,
+        message: `camera.${low} (${lowValue}) must not exceed camera.${high} (${highValue}).`,
+    });
+}
+/** A declared value or its default, when it is a number its rule accepts (else the field is already an error). */
+function numberOr(block, field) {
+    const fallback = ORBIT_DEFAULTS;
+    const value = block[field] ?? fallback[field];
+    const rule = NUMBER_RULES.find((entry) => entry.field === field);
+    return isFiniteNumber(value) && (rule?.accepts(value) ?? true) ? value : null;
+}
+/** The range each initial orbit number starts inside. */
+const START_RANGES = {
+    distance: ['minDistance', 'maxDistance'],
+    pitch: ['minPitch', 'maxPitch'],
+};
+/**
+ * A following camera's declared initial `distance` or `pitch` outside its
+ * valid range [low, high]: the camera clamps it, so it starts elsewhere than
+ * the scene says, a warning (issue #181, maintainer decision). An invalid
+ * value or an inverted range is already an error and is not repeated.
+ */
+function startIssue(block, field) {
+    const [low, high] = START_RANGES[field];
+    const value = block[field] === undefined ? null : numberOr(block, field);
+    const min = numberOr(block, low);
+    const max = numberOr(block, high);
+    if (!block.follow || value === null || min === null || max === null || min > max)
+        return null;
+    if (value >= min && value <= max)
+        return null;
+    return {
+        field: `camera.${field}`,
+        message: `camera.${field} (${value}) is outside [camera.${low} (${min}), camera.${high} (${max})]; the camera starts at ${Math.min(Math.max(value, min), max)}.`,
+        severity: 'warning',
+    };
+}
+/**
+ * Every orbit field of a perspective block outside its range: the numbers
+ * (distances above 0, pitches in (-89, 89), speeds at least 0), `invertY`,
+ * the Action names, and a `minDistance` or `minPitch` above its maximum
+ * (errors); and a following camera's initial `distance` or `pitch` outside
+ * its own range (warnings). Whether `follow` names an entity of the scene is
+ * the scene validator's.
+ */
+export function orbitCameraIssues(block) {
+    const issues = [];
+    fieldIssues(block, issues);
+    rangeIssue(block, ['minDistance', 'maxDistance'], issues);
+    rangeIssue(block, ['minPitch', 'maxPitch'], issues);
+    for (const field of ['distance', 'pitch']) {
+        const start = startIssue(block, field);
+        if (start)
+            issues.push(start);
+    }
+    return issues;
+}

package/dist/scene-field-issues.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What the scene validators share (the camera, orbit, render and simulation
+ * blocks): the issue they report and how a message quotes a JSON value. A
+ * leaf module, so the orbit fields can use them without importing the
+ * perspective camera that imports them.
+ */
+/** One field of a scene's render, camera or entity transform that is invalid, for validate_project: an error unless it is a `'warning'`. */
+export interface SceneFieldIssue {
+    field: string;
+    message: string;
+    /** A field the runtime accepts as written but adjusts (a clamp): reported as a warning. */
+    severity?: 'warning';
+}
+/** A JSON value as a message quotes it: strings in quotes, everything else as `String()` shows it. */
+export declare const shown: (value: unknown) => string;
+export declare function isFiniteNumber(value: unknown): value is number;

package/dist/scene-field-issues.js

@@ -0,0 +1,11 @@
+/**
+ * What the scene validators share (the camera, orbit, render and simulation
+ * blocks): the issue they report and how a message quotes a JSON value. A
+ * leaf module, so the orbit fields can use them without importing the
+ * perspective camera that imports them.
+ */
+/** A JSON value as a message quotes it: strings in quotes, everything else as `String()` shows it. */
+export const shown = (value) => (typeof value === 'string' ? JSON.stringify(value) : String(value));
+export function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}

package/dist/scene.js

@@ -133,14 +133,16 @@ export function loadScene(game, scene, registry) {
     game.registry = registry;
     game.setSceneRender(scene.render);
     game.setSceneSimulation(scene.simulation);
-    // A perspective camera has no follow target to wait for: components see it from their first onReady.
+    // A perspective camera is adopted first, so components see it from their first onReady.
     const adoptsBeforeSpawns = game.space === '3d';
     if (adoptsBeforeSpawns)
         game.setSceneCamera(scene.camera);
     for (const entityJson of scene.entities)
         spawnFromJson(game, entityJson, registry);
-    // After the spawns: with a follow target, the orthographic camera starts centered on it.
-    if (!adoptsBeforeSpawns)
+    // After the spawns, with a follow target: the orthographic camera starts centered on it, an orbit camera on its orbit.
+    if (adoptsBeforeSpawns)
+        game.placeSceneCamera();
+    else
         game.setSceneCamera(scene.camera);
     if (registry.ui)
         game.ui.defineAll(registry.ui);

package/dist/spatial-query-3d.d.ts

@@ -3,7 +3,7 @@ import type { Entity } from './entity.js';
 import type { Game } from './game.js';
 import { type Point3d, type QueryVolume3d } from './physics-3d/world-queries.js';
 import type { ComponentClasses, NearestSpatialQueryFilter, SpatialQueryFilter } from './spatial-query.js';
-export type { Point3d, QueryVolume3d } from './physics-3d/world-queries.js';
+export type { Point3d, QueryColliders3d, QueryVolume3d } from './physics-3d/world-queries.js';
 /** The first solid collider a 3D ray reached, with its entity and the crossing (issue #159 CA-21). */
 export interface RayHit3d<T extends Entity = Entity> {
     readonly entity: T;
@@ -18,7 +18,7 @@ type NearestFilter = NearestSpatialQueryFilter<ComponentClasses> | undefined;
 export interface EntityRules {
     matchesCommon(entity: Entity, filter: NearestFilter): boolean;
 }
-/** The 3D forms of `game.query` (ADR 0015's domains kept): `ray` reads solids, `area` and `point` read sensors, `nearest` reads transforms. */
+/** The 3D forms of `game.query` (ADR 0015's domains kept): `ray` reads solids, `area` and `point` read sensors (`area` every collider on request), `nearest` reads transforms. */
 export declare class SpatialQuery3d {
     private readonly game;
     private readonly rules;

package/dist/spatial-query-3d.js

@@ -1,9 +1,16 @@
 import { recordsAtPoint, recordsInVolume, worldRayHits } from './physics-3d/world-queries.js';
 const isPoint3d = (value) => typeof value === 'object' && value !== null && ['x', 'y', 'z'].every((axis) => Number.isFinite(Reflect.get(value, axis)));
 const isExtent = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0;
+/** An absent or known collider domain, and an absent or finite box yaw: the optional parts of a volume. */
+function hasValidOptions(value) {
+    const colliders = Reflect.get(value, 'colliders');
+    const yaw = Reflect.get(value, 'yaw');
+    const knownDomain = colliders === undefined || colliders === 'sensors' || colliders === 'all';
+    return knownDomain && (yaw === undefined || (typeof yaw === 'number' && Number.isFinite(yaw)));
+}
 /** A finite box or sphere with a place: anything else is a volume Rapier cannot test. */
 function isVolume3d(value) {
-    if (typeof value !== 'object' || value === null || !isPoint3d(Reflect.get(value, 'center')))
+    if (typeof value !== 'object' || value === null || !isPoint3d(Reflect.get(value, 'center')) || !hasValidOptions(value))
         return false;
     const shape = Reflect.get(value, 'shape');
     if (shape === 'sphere')
@@ -13,7 +20,7 @@ function isVolume3d(value) {
 }
 /** The farthest a nearest query looks: its `maxDistance`, or no limit. */
 const rangeOf = (filter) => filter?.maxDistance ?? Infinity;
-/** The 3D forms of `game.query` (ADR 0015's domains kept): `ray` reads solids, `area` and `point` read sensors, `nearest` reads transforms. */
+/** The 3D forms of `game.query` (ADR 0015's domains kept): `ray` reads solids, `area` and `point` read sensors (`area` every collider on request), `nearest` reads transforms. */
 export class SpatialQuery3d {
     game;
     rules;
@@ -40,7 +47,8 @@ export class SpatialQuery3d {
         const world = this.worldNow();
         if (!world || !isVolume3d(volume))
             return [];
-        return this.inEntityOrder(recordsInVolume(world, volume, (record) => this.eligible(record, filter, true)), filter);
+        const domain = volume.colliders === 'all' ? 'all' : true;
+        return this.inEntityOrder(recordsInVolume(world, volume, (record) => this.eligible(record, filter, domain)), filter);
     }
     point(at, filter) {
         const world = this.worldNow();
@@ -82,7 +90,8 @@ export class SpatialQuery3d {
      * Rapier's callback, so it reads the record and nothing else.
      */
     eligible(record, filter, sensors) {
-        return record.sensor === sensors && record.entity.alive && this.rules.matchesCommon(record.entity, filter);
+        const inDomain = sensors === 'all' || record.sensor === sensors;
+        return inDomain && record.entity.alive && this.rules.matchesCommon(record.entity, filter);
     }
     /** The user's `where`, run after Rapier has answered: it may throw, spawn or destroy without the world mid-query. */
     wanted(record, filter) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",