@waica/engine 0.24.0 → 0.26.0

package/dist/scene-space.js

@@ -0,0 +1,103 @@
+import { isFiniteNumber, perspectiveCameraIssues, shown } from './scene-camera-3d.js';
+export const SCENE_SPACES = ['2d', '3d'];
+/** The scene's space: 3d only when `render.space` says exactly so. */
+export function resolveSceneSpace(render) {
+    return recordOf(render).space === '3d' ? '3d' : '2d';
+}
+/**
+ * What a scene's render block makes of the draw-order options at runtime. A
+ * 3D scene has no y-sort and no isometric projection whatever the block
+ * says (`validate_project` reports them); a 2D scene reads them as always.
+ */
+export function resolveRenderPolicy(render) {
+    const block = recordOf(render);
+    const space = resolveSceneSpace(block);
+    const flat = space === '2d';
+    return {
+        space,
+        sort: flat && block.sort === 'y' ? 'y' : null,
+        projection: flat && block.projection === 'isometric' ? 'isometric' : null,
+    };
+}
+/** The space a component class belongs to; a class that declares none is `'both'`. */
+export function componentSpaceOf(Class) {
+    return Class.space ?? 'both';
+}
+/**
+ * True when a component of this class does not belong in a scene of this
+ * space: a `'2d'` component in 3d, a `'3d'` one in 2d. Reads the class's
+ * `static space` marker, so engine, behavior and project-owned components
+ * answer the same way. A class the caller does not know (undefined) is
+ * space-neutral.
+ */
+export function componentSpaceMismatch(space, Class) {
+    if (Class === undefined)
+        return false;
+    const own = componentSpaceOf(Class);
+    return own !== 'both' && own !== space;
+}
+function recordOf(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? { ...value } : {};
+}
+/** Fields of `render` that only mean something in a 2D scene. */
+const TWO_D_RENDER_FIELDS = ['sort', 'projection', 'batch'];
+function cameraKindIssue(space, camera, issues) {
+    if (camera === undefined || camera === null)
+        return;
+    const kind = recordOf(camera).kind;
+    if (kind !== undefined && kind !== 'orthographic' && kind !== 'perspective') {
+        issues.push({ field: 'camera.kind', message: `camera.kind must be 'orthographic' or 'perspective'; got ${shown(kind)}.` });
+        return;
+    }
+    if (space === '2d' && kind === 'perspective') {
+        issues.push({ field: 'camera.kind', message: `A perspective camera needs render.space '3d'; this scene is 2d.` });
+    }
+    if (space === '3d' && kind !== 'perspective') {
+        issues.push({ field: 'camera.kind', message: `A 3d scene needs a perspective camera (kind: 'perspective'); got an orthographic one.` });
+    }
+}
+/**
+ * Every invalid field of a scene's `render.space`, its camera block and the
+ * render options a 3d scene cannot use: a space outside `'2d' | '3d'`, a
+ * camera that does not match the space, a perspective camera out of range
+ * and `render.sort`, `render.projection` or `render.batch` under 3d. Other
+ * render fields are `sceneRenderIssues`'s.
+ */
+export function sceneSpaceIssues(render, camera) {
+    const block = recordOf(render);
+    const issues = [];
+    if (block.space !== undefined && block.space !== '2d' && block.space !== '3d') {
+        issues.push({ field: 'render.space', message: `render.space must be '2d' or '3d'; got ${shown(block.space)}.` });
+    }
+    const space = resolveSceneSpace(block);
+    cameraKindIssue(space, camera, issues);
+    issues.push(...perspectiveCameraIssues(camera));
+    if (space === '3d') {
+        for (const field of TWO_D_RENDER_FIELDS) {
+            if (block[field] === undefined)
+                continue;
+            issues.push({ field: `render.${field}`, message: `render.${field} is a 2D option and has no meaning in a 3d scene.` });
+        }
+    }
+    return issues;
+}
+function tupleIssue(issues, { field, lengths }, value) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value) && lengths.includes(value.length) && value.every(isFiniteNumber))
+        return;
+    const need = lengths.join(' or ');
+    issues.push({ field, message: `${field} must be ${need} finite numbers; got ${JSON.stringify(value)}.` });
+}
+/**
+ * An entity's `position` (2 or 3 finite numbers), `rotation` (degrees) and
+ * `scale` (3 finite numbers each) that are anything else.
+ */
+export function entityTransformIssues(entity) {
+    const json = recordOf(entity);
+    const issues = [];
+    tupleIssue(issues, { field: 'position', lengths: [2, 3] }, json.position);
+    tupleIssue(issues, { field: 'rotation', lengths: [3] }, json.rotation);
+    tupleIssue(issues, { field: 'scale', lengths: [3] }, json.scale);
+    return issues;
+}

package/dist/scene.d.ts

@@ -1,7 +1,10 @@
 import type { SceneCameraJson } from './camera.js';
 import type { ComponentClass } from './component.js';
 import type { Entity } from './entity.js';
+import { type TransformJson } from './entity-transform.js';
 import type { Game } from './game.js';
+import type { SceneSimulationJson } from './scene-simulation.js';
+import type { SceneSpace } from './scene-space.js';
 /**
  * Waica's scene format: declarative, git-friendly data, editable by the
  * visual editor. The scene is the source of truth; the Game is its live
@@ -11,9 +14,8 @@ export interface SceneComponentJson {
     type: string;
     props?: Record<string, unknown>;
 }
-export interface SceneEntityJson {
+export interface SceneEntityJson extends TransformJson {
     name: string;
-    position?: [number, number];
     /** Prefab ref like "characters/slime", resolved against SceneRegistry.prefabs. */
     prefab?: string;
     /** Per-component prop overrides on top of the prefab: componentType -> propName -> value. */
@@ -28,8 +30,43 @@ export interface PrefabJson {
     type: 'character' | 'object' | 'tile';
     components: SceneComponentJson[];
 }
+/**
+ * The scene's lighting (issue #78, ADR 0026). Declaring it — or spawning a
+ * Light — draws the scene lit; absent, the scene is drawn exactly as unlit.
+ */
+export interface SceneLightingJson {
+    /** Where no light reaches. Absent fields: `#ffffff` and 1, the art as drawn. */
+    ambient?: {
+        color?: string;
+        intensity?: number;
+    };
+}
+/** The scene's Post Effects, each off unless declared (issue #78). */
+export interface ScenePostJson {
+    /** Darkens the frame's edges: `intensity` 0..1 at the corners, starting at `radius` 0..1 from the centre. */
+    vignette?: {
+        intensity: number;
+        radius: number;
+    };
+    /** A `#rrggbb` tint multiplier, and contrast and saturation from 0 to 2 (1 leaves the frame unchanged). */
+    colorGrade?: {
+        tint?: string;
+        contrast?: number;
+        saturation?: number;
+    };
+}
 /** Scene-wide render options (v3). */
 export interface SceneRenderJson {
+    /**
+     * `'2d'` (the default) or `'3d'` (ADR 0027). A 3D scene makes `z` a world
+     * axis under a perspective camera with a depth buffer; there is no layer
+     * band, y-sort, isometric projection, sprite batch or light-map in it.
+     */
+    space?: SceneSpace;
+    /** Ambient Light; with it (or any Light) the scene is lit (ADR 0026). */
+    lighting?: SceneLightingJson;
+    /** Vignette and color grade; with either on, the frame renders through a render target. */
+    post?: ScenePostJson;
     /**
      * 'y' orders same-layer sprites by their render-space Y — lower Y renders
      * in front (top-down depth). Absent: spawn order breaks same-layer ties.
@@ -54,6 +91,8 @@ export interface SceneJson {
     camera?: SceneCameraJson;
     /** Draw-order policy (v3); absent = layer bands with spawn-order ties. */
     render?: SceneRenderJson;
+    /** The physics world's settings (v3, 3D scenes only): gravity. Absent = earth gravity. */
+    simulation?: SceneSimulationJson;
     entities: SceneEntityJson[];
     /** UI pieces (src/ui/*.html) mounted visible when the scene loads. */
     ui?: string[];

package/dist/scene.js

@@ -1,3 +1,4 @@
+import { applyTransformJson } from './entity-transform.js';
 /**
  * Own-property lookup. Scene JSON is data — a component or prefab named
  * "constructor" or "toString" must read as missing, not as whatever sits
@@ -69,6 +70,7 @@ const COMPONENT_MEMBERS = {
     onProjectionChange: true,
     onCollide: true,
     onContact: true,
+    onBodyContact: true,
     onInteract: true,
     onDestroy: true,
 };
@@ -91,8 +93,7 @@ function sceneProps(props, type, entityName) {
 }
 export function spawnFromJson(game, json, registry) {
     const entity = game.spawn(json.name);
-    if (json.position)
-        entity.position.set(json.position[0], json.position[1], 0);
+    applyTransformJson(entity, json);
     for (const comp of resolveEntityComponents(json, registry.prefabs)) {
         const Class = registryEntry(registry.components, comp.type);
         if (!Class) {
@@ -131,10 +132,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.
+    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 camera starts centered on it.
-    game.setSceneCamera(scene.camera);
+    // After the spawns: with a follow target, the orthographic camera starts centered on it.
+    if (!adoptsBeforeSpawns)
+        game.setSceneCamera(scene.camera);
     if (registry.ui)
         game.ui.defineAll(registry.ui);
     // Scene-scoped: Game.unloadScene() unmounts these along with the entities.

package/dist/simulation-phases.d.ts

@@ -0,0 +1,9 @@
+import type { Game } from './game.js';
+/**
+ * What a Simulation Step does after every component's `onUpdate` (issue #159
+ * CA-10), in this order: the 3D physics step (one `world.step()` of the live
+ * scene's Rapier world, a no-op in a 2D scene or while the module loads), the
+ * solid contacts it produced, the 2D Hitbox triggers, and the 3D sensor
+ * triggers. Kept out of `game.ts`, which is at the file-size tier.
+ */
+export declare function runSimulationPhases(game: Game): void;

package/dist/simulation-phases.js

@@ -0,0 +1,19 @@
+import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
+import { dispatchBodyContacts } from './physics-3d/body-contacts.js';
+import { dispatchSensorCollisions } from './physics-3d/sensor-dispatch.js';
+/**
+ * What a Simulation Step does after every component's `onUpdate` (issue #159
+ * CA-10), in this order: the 3D physics step (one `world.step()` of the live
+ * scene's Rapier world, a no-op in a 2D scene or while the module loads), the
+ * solid contacts it produced, the 2D Hitbox triggers, and the 3D sensor
+ * triggers. Kept out of `game.ts`, which is at the file-size tier.
+ */
+export function runSimulationPhases(game) {
+    const world = game.physics.world;
+    world?.step();
+    if (world)
+        dispatchBodyContacts(game, world);
+    dispatchHitboxCollisions(game);
+    if (world && game.physics.world === world)
+        dispatchSensorCollisions(game, world);
+}

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

@@ -0,0 +1,48 @@
+import type { Collider } from './components/collider.js';
+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';
+/** 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;
+    readonly collider: Collider;
+    readonly distance: number;
+    readonly point: Readonly<Point3d>;
+    readonly normal: Readonly<Point3d>;
+}
+type Filter = SpatialQueryFilter<ComponentClasses> | undefined;
+type NearestFilter = NearestSpatialQueryFilter<ComponentClasses> | undefined;
+/** The structural part of the entity filter the 2D forms use (`with`, `without`, `exclude`), shared with the 3D ones (`spatial-query.ts` owns it). */
+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. */
+export declare class SpatialQuery3d {
+    private readonly game;
+    private readonly rules;
+    constructor(game: Game, rules: EntityRules);
+    /** `direction` need not be a unit vector; `maxDistance` is in world units. */
+    ray(aim: {
+        origin: Point3d;
+        direction: Point3d;
+    }, maxDistance: number, filter?: Filter): RayHit3d | null;
+    area(volume: QueryVolume3d, filter?: Filter): Entity[];
+    point(at: Point3d, filter?: Filter): Entity[];
+    nearest(at: Point3d, filter?: NearestFilter): Entity | null;
+    /** How far the entity is from the search, when it is alive, passes the filter and lies within range. */
+    private distanceIfEligible;
+    /** The live world with its query structure current, or null while there is none. */
+    private worldNow;
+    /**
+     * A live entity's collider the query domain reads (solids for a ray, sensors
+     * for area and point) that passes the structural filter. Runs inside
+     * Rapier's callback, so it reads the record and nothing else.
+     */
+    private eligible;
+    /** The user's `where`, run after Rapier has answered: it may throw, spawn or destroy without the world mid-query. */
+    private wanted;
+    /** The entities of the records that pass `where`, once each, in the order they were spawned. */
+    private inEntityOrder;
+}

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

@@ -0,0 +1,96 @@
+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;
+/** 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')))
+        return false;
+    const shape = Reflect.get(value, 'shape');
+    if (shape === 'sphere')
+        return isExtent(Reflect.get(value, 'radius'));
+    const size = Reflect.get(value, 'size');
+    return shape === 'box' && typeof size === 'object' && size !== null && ['x', 'y', 'z'].every((axis) => isExtent(Reflect.get(size, axis)));
+}
+/** 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. */
+export class SpatialQuery3d {
+    game;
+    rules;
+    constructor(game, rules) {
+        this.game = game;
+        this.rules = rules;
+    }
+    /** `direction` need not be a unit vector; `maxDistance` is in world units. */
+    ray(aim, maxDistance, filter) {
+        const { origin, direction } = aim;
+        const world = this.worldNow();
+        const length = isPoint3d(direction) ? Math.hypot(direction.x, direction.y, direction.z) : 0;
+        if (!world || !isPoint3d(origin) || length === 0 || !(maxDistance >= 0) || !Number.isFinite(maxDistance))
+            return null;
+        const unit = { x: direction.x / length, y: direction.y / length, z: direction.z / length };
+        const hits = worldRayHits(world, { origin, direction: unit, maxDistance }, (record) => this.eligible(record, filter, false));
+        // The user's `where` runs here, outside Rapier's borrow of the world: the first hit it keeps wins.
+        const hit = hits.find(({ record }) => this.wanted(record, filter));
+        if (!hit)
+            return null;
+        return { entity: hit.record.entity, collider: hit.record.collider, distance: hit.distance, point: hit.point, normal: hit.normal };
+    }
+    area(volume, filter) {
+        const world = this.worldNow();
+        if (!world || !isVolume3d(volume))
+            return [];
+        return this.inEntityOrder(recordsInVolume(world, volume, (record) => this.eligible(record, filter, true)), filter);
+    }
+    point(at, filter) {
+        const world = this.worldNow();
+        if (!world || !isPoint3d(at))
+            return [];
+        return this.inEntityOrder(recordsAtPoint(world, at, (record) => this.eligible(record, filter, true)), filter);
+    }
+    nearest(at, filter) {
+        const maxDistance = rangeOf(filter);
+        if (!isPoint3d(at) || !(maxDistance >= 0))
+            return null;
+        let best = null;
+        for (const entity of this.game.entities) {
+            const distance = this.distanceIfEligible(entity, { at, filter, maxDistance });
+            if (distance !== null && (best === null || distance < best.distance))
+                best = { entity, distance };
+        }
+        return best?.entity ?? null;
+    }
+    /** How far the entity is from the search, when it is alive, passes the filter and lies within range. */
+    distanceIfEligible(entity, { at, filter, maxDistance }) {
+        if (!entity.alive || !this.rules.matchesCommon(entity, filter))
+            return null;
+        const { x, y, z } = entity.position;
+        const distance = Math.hypot(x - at.x, y - at.y, z - at.z);
+        if (Number.isNaN(distance) || distance > maxDistance)
+            return null;
+        return filter?.where && !filter.where(entity, { distance }) ? null : distance;
+    }
+    /** The live world with its query structure current, or null while there is none. */
+    worldNow() {
+        const world = this.game.physics.world;
+        world?.refreshQueries();
+        return world;
+    }
+    /**
+     * A live entity's collider the query domain reads (solids for a ray, sensors
+     * for area and point) that passes the structural filter. Runs inside
+     * 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);
+    }
+    /** The user's `where`, run after Rapier has answered: it may throw, spawn or destroy without the world mid-query. */
+    wanted(record, filter) {
+        return record.entity.alive && (!filter?.where || filter.where(record.entity));
+    }
+    /** The entities of the records that pass `where`, once each, in the order they were spawned. */
+    inEntityOrder(records, filter) {
+        const found = new Set(records.filter((record) => this.wanted(record, filter)).map((record) => record.entity));
+        return this.game.entities.filter((entity) => found.has(entity));
+    }
+}

package/dist/spatial-query.d.ts

@@ -4,7 +4,8 @@ import { Hitbox } from './components/hitbox.js';
 import { Solid } from './components/solid.js';
 import type { Entity } from './entity.js';
 import type { Game } from './game.js';
-type ComponentClasses = readonly ComponentClass[];
+import { type Point3d, type QueryVolume3d, type RayHit3d } from './spatial-query-3d.js';
+export type ComponentClasses = readonly ComponentClass[];
 type QueryEntity<Classes extends ComponentClasses> = Classes extends readonly [] ? Entity : EntityWith<Classes>;
 /** An Entity whose required component classes return non-optional instances. */
 export interface EntityWith<Classes extends ComponentClasses> extends Entity {
@@ -57,21 +58,34 @@ type NearestGuardFilter<Classes extends ComponentClasses, Narrowed extends Query
 /** Public logical-space spatial-query service owned by every Game. */
 export interface SpatialQuery {
     /** Hitbox owners with positive interior overlap, mask-agnostic and in Entity order. */
-    area<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(body: CollisionBody, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
-    area<Classes extends ComponentClasses = readonly []>(body: CollisionBody, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
-    area(body: CollisionBody, filter?: SpatialQueryFilter): Entity[];
+    area<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(body: CollisionBody | QueryVolume3d, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
+    /** In a 3D scene `area` takes a volume and returns the entities whose sensor colliders intersect it, in Entity order. */
+    area<Classes extends ComponentClasses = readonly []>(body: CollisionBody | QueryVolume3d, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
+    area(body: CollisionBody | QueryVolume3d, filter?: SpatialQueryFilter): Entity[];
     /** Hitbox owners that strictly contain a point, mask-agnostic and in Entity order. */
     point<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
     point<Classes extends ComponentClasses = readonly []>(x: number, y: number, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
     point(x: number, y: number, filter?: SpatialQueryFilter): Entity[];
+    /** 3D scenes: entities whose sensor colliders contain the point, in Entity order. */
+    point<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(at: Point3d, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
+    point<Classes extends ComponentClasses = readonly []>(at: Point3d, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
+    point(at: Point3d, filter?: SpatialQueryFilter): Entity[];
     /** Closest filtered logical transform; equal distances retain Entity order. */
     nearest<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, filter: NearestGuardFilter<Classes, Narrowed>): Narrowed | null;
     nearest<Classes extends ComponentClasses = readonly []>(x: number, y: number, filter: NearestSpatialQueryFilter<Classes>): QueryEntity<Classes> | null;
     nearest(x: number, y: number, filter?: NearestSpatialQueryFilter): Entity | null;
+    /** 3D scenes: the closest filtered transform, z included. */
+    nearest<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(at: Point3d, filter: NearestGuardFilter<Classes, Narrowed>): Narrowed | null;
+    nearest<Classes extends ComponentClasses = readonly []>(at: Point3d, filter: NearestSpatialQueryFilter<Classes>): QueryEntity<Classes> | null;
+    nearest(at: Point3d, filter?: NearestSpatialQueryFilter): Entity | null;
     /** First strict crossing of direct or source-derived Solid geometry. */
     ray<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, dx: number, dy: number, maxDistance: number, filter: SpatialGuardFilter<Classes, Narrowed>): RayHit<Narrowed> | null;
     ray<Classes extends ComponentClasses = readonly []>(x: number, y: number, dx: number, dy: number, maxDistance: number, filter: SpatialQueryFilter<Classes>): RayHit<QueryEntity<Classes>> | null;
     ray(x: number, y: number, dx: number, dy: number, maxDistance: number, filter?: SpatialQueryFilter): RayHit | null;
+    /** 3D scenes: the first solid collider along the ray (sensors never block it); `direction` need not be a unit vector. */
+    ray<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(origin: Point3d, direction: Point3d, maxDistance: number, filter: SpatialGuardFilter<Classes, Narrowed>): RayHit3d<Narrowed> | null;
+    ray<Classes extends ComponentClasses = readonly []>(origin: Point3d, direction: Point3d, maxDistance: number, filter: SpatialQueryFilter<Classes>): RayHit3d<QueryEntity<Classes>> | null;
+    ray(origin: Point3d, direction: Point3d, maxDistance: number, filter?: SpatialQueryFilter): RayHit3d | null;
 }
 export interface HitboxCandidate {
     readonly entity: Entity;

package/dist/spatial-query.js

@@ -3,6 +3,7 @@ import { collisionBounds, collisionOverlap, } from './collision-shape.js';
 import { Hitbox } from './components/hitbox.js';
 import { Solid } from './components/solid.js';
 import { createHitboxBroadphase, createSolidBroadphase, } from './spatial-broadphase.js';
+import { SpatialQuery3d } from './spatial-query-3d.js';
 import { collisionBodyContainsPoint, collisionBodyRay, SPATIAL_QUERY_EPSILON, usableCollisionBody, } from './spatial-query-geometry.js';
 function indexedCandidateProviders(game) {
     return {
@@ -162,7 +163,62 @@ class LinearSpatialQuery {
         return result;
     }
 }
+/** A volume names its place by `center`; a collision body by `x` and `y`. */
+const isVolume = (value) => typeof value === 'object' && value !== null && 'center' in value;
+const isRay3d = (args) => typeof args[0] === 'object';
+/**
+ * Sends each call to the form its arguments name and refuses the form of the
+ * other space with an error naming both (issue #159 CA-21): the 2D forms read
+ * Hitboxes and Solids and take numbers or a collision body; the 3D forms read
+ * the physics world and take `{ x, y, z }` objects.
+ */
+class SpaceSpatialQuery {
+    game;
+    flat;
+    solid;
+    constructor(game, flat) {
+        this.game = game;
+        this.flat = flat;
+        this.solid = new SpatialQuery3d(game, { matchesCommon: matchesCommonFilter });
+    }
+    area(first, filter) {
+        if (isVolume(first))
+            return this.in3d('area').area(first, filter);
+        this.require('area', '2d');
+        return this.flat.area(first, filter);
+    }
+    point(first, second, third) {
+        if (typeof first === 'object')
+            return this.in3d('point').point(first, typeof second === 'object' ? second : undefined);
+        this.require('point', '2d');
+        return this.flat.point(first, typeof second === 'number' ? second : Number.NaN, third);
+    }
+    nearest(first, second, third) {
+        if (typeof first === 'object')
+            return this.in3d('nearest').nearest(first, typeof second === 'object' ? second : undefined);
+        this.require('nearest', '2d');
+        return this.flat.nearest(first, typeof second === 'number' ? second : Number.NaN, third);
+    }
+    ray(...args) {
+        if (isRay3d(args)) {
+            const [origin, direction, maxDistance, filter] = args;
+            return this.in3d('ray').ray({ origin, direction }, maxDistance, filter);
+        }
+        this.require('ray', '2d');
+        return this.flat.ray(...args);
+    }
+    in3d(operation) {
+        this.require(operation, '3d');
+        return this.solid;
+    }
+    require(operation, space) {
+        // Only a 3D scene turns the 2D forms away; anything else (no scene, or a stand-in Game) is the 2D world.
+        if (space === '3d' ? this.game.space === '3d' : this.game.space !== '3d')
+            return;
+        throw new Error(`game.query.${operation}: the ${space === '3d' ? '3D' : '2D'} form needs a ${space} scene, and the live scene is ${this.game.space}.`);
+    }
+}
 /** Package-internal constructor; only the SpatialQuery interface is public. */
 export function createSpatialQuery(game, candidates = indexedCandidateProviders(game), instrumentation) {
-    return new LinearSpatialQuery(candidates, instrumentation);
+    return new SpaceSpatialQuery(game, new LinearSpatialQuery(candidates, instrumentation));
 }

package/dist/sprite-batch.js

@@ -1,5 +1,6 @@
 import { attribute, context, mat3, positionLocal, uv, vec3, vertexStage } from 'three/tsl';
 import * as THREE from 'three/webgpu';
+import { TRANSPARENT_TEXEL_ALPHA } from './render-layers.js';
 /** The first capacity of a batch's instance buffers; it doubles when full. */
 export const INITIAL_SPRITE_BATCH_CAPACITY = 16;
 /** The key's canonical string: equal keys share one batch. */
@@ -57,7 +58,7 @@ class SpriteBatchMaterial extends THREE.MeshBasicNodeMaterial {
 function createMaterial(key, textures) {
     // Double-sided: a flipped sprite mirrors through a negative x scale in its
     // matrix, exactly like its own mesh; per instance there is no winding flip.
-    const material = new SpriteBatchMaterial({ transparent: true, side: THREE.DoubleSide });
+    const material = new SpriteBatchMaterial({ transparent: true, side: THREE.DoubleSide, alphaTest: TRANSPARENT_TEXEL_ALPHA });
     material.forceSinglePass = true;
     if (key.texture === null)
         return { material, settled: null };
@@ -100,6 +101,9 @@ export class SpriteRunMesh {
         this.mesh.instanceColor = this.colors;
         // Drawn in an explicit renderOrder; its instances are already in view space.
         this.mesh.frustumCulled = false;
+        // A run is collected through its sprites' anchors, which carry their own
+        // layers (Emissive or not, ADR 0026): the run itself is on every layer.
+        this.mesh.layers.enableAll();
         this.mesh.matrixAutoUpdate = false;
         this.mesh.boundingSphere = new THREE.Sphere();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     }
   },
   "dependencies": {
+    "@dimforge/rapier3d-deterministic-compat": "0.21.0",
     "@types/three": "^0.186.0",
     "three": "^0.186.1"
   }