@ludra/three 0.92.0 → 0.94.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as THREE from "three";
 import { type Entity, type GameEvent, type RenderContext, type SceneDef } from "@ludra/core";
-import type { Renderer3D, Renderer3DFactory } from "@ludra/core/browser";
+import type { CameraView, Renderer3D, Renderer3DFactory } from "@ludra/core/browser";
 /**
  * The 3D renderer for Ludra: Three.js draws every entity with a `mesh` and lights the scene
  * with its `light` entities, seen through a `camera3d`. It only reads the world, so it can
@@ -18,6 +18,12 @@ export declare const createRenderer3D: Renderer3DFactory;
 export declare class ThreeRenderer implements Renderer3D {
     readonly canvas: HTMLCanvasElement;
     debug: boolean;
+    view: CameraView | undefined;
+    hidden: ReadonlySet<string> | undefined;
+    /** The map view's camera, fitted to the level every frame. */
+    private readonly mapCamera;
+    /** Lights the map evenly, so a night scene reads as well as a day one. */
+    private readonly mapLight;
     /** Three.js itself, for render hooks and anything else (step 4 hands these to scripts). */
     readonly renderer: THREE.WebGLRenderer;
     readonly scene: THREE.Scene<THREE.Object3DEventMap>;
@@ -58,6 +64,21 @@ export declare class ThreeRenderer implements Renderer3D {
     step(world: WorldView): void;
     reset(world: WorldView): void;
     render(world: WorldView): void;
+    /** Hides what the hidden entities show. Their lights stay on: what's behind them must look the same. */
+    private conceal;
+    /** In the map view: every entity with a body or mesh, at its place on the map. Ground-sized ones are left out. */
+    labels(world: WorldView): {
+        text: string;
+        x: number;
+        y: number;
+    }[];
+    /** Free view: from a fixed point, looking at a point or following an entity. */
+    private placeFreeCamera;
+    /**
+     * Map view: straight down on everything drawn, north (-z) up, with no perspective so
+     * distances read true. Fog is off and the light is even: the map is about where things are.
+     */
+    private renderMap;
     /** Waits for every addon render hooks asked for, and for what their callbacks start in turn. */
     settle(): Promise<void>;
     private track;

package/dist/index.js

@@ -31,6 +31,12 @@ export const createRenderer3D = async (scene, options) => {
 export class ThreeRenderer {
     canvas;
     debug = false;
+    view;
+    hidden;
+    /** The map view's camera, fitted to the level every frame. */
+    mapCamera = new THREE.OrthographicCamera();
+    /** Lights the map evenly, so a night scene reads as well as a day one. */
+    mapLight = new THREE.AmbientLight(0xffffff, 3);
     /** Three.js itself, for render hooks and anything else (step 4 hands these to scripts). */
     renderer;
     scene = new THREE.Scene();
@@ -172,12 +178,98 @@ export class ThreeRenderer {
         const rig = this.rig;
         this.camera.position.copy(rig.position);
         this.camera.lookAt(rig.look);
+        if (this.view?.mode === "free")
+            this.placeFreeCamera(world, this.view);
         this.poseModels(world);
         this.runRenderHooks(world);
-        if (this.customRender)
+        const concealed = this.conceal();
+        if (this.view?.mode === "map")
+            this.renderMap();
+        else if (this.customRender)
             this.customRender();
         else
             this.renderer.render(this.scene, this.camera);
+        for (const object of concealed)
+            object.visible = true;
+    }
+    /** Hides what the hidden entities show. Their lights stay on: what's behind them must look the same. */
+    conceal() {
+        const concealed = [];
+        if (!this.hidden?.size)
+            return concealed;
+        const roots = [...this.objects, ...this.hookGroups].filter(([e]) => this.hidden.has(e.id));
+        for (const [, root] of roots) {
+            root.traverse((object) => {
+                const shape = object;
+                if (!object.visible || !(shape.isMesh || shape.isLine || shape.isPoints || shape.isSprite))
+                    return;
+                object.visible = false;
+                concealed.push(object);
+            });
+        }
+        return concealed;
+    }
+    /** In the map view: every entity with a body or mesh, at its place on the map. Ground-sized ones are left out. */
+    labels(world) {
+        if (this.view?.mode !== "map")
+            return [];
+        const { width, height } = this.canvas;
+        const cam = this.mapCamera;
+        const mapArea = (cam.right - cam.left) * (cam.top - cam.bottom);
+        const labels = [];
+        const size = new THREE.Vector3();
+        for (const e of world.entities) {
+            if (!e.body && !e.mesh)
+                continue;
+            const object = this.objects.get(e);
+            if (object && new THREE.Box3().setFromObject(object).getSize(size) && size.x * size.z > mapArea * 0.2)
+                continue;
+            const point = new THREE.Vector3(e.transform.x, e.transform.y, e.transform.z).project(cam);
+            if (Math.abs(point.x) > 1 || Math.abs(point.y) > 1)
+                continue;
+            labels.push({ text: e.id, x: ((point.x + 1) / 2) * width, y: ((1 - point.y) / 2) * height });
+        }
+        return labels;
+    }
+    /** Free view: from a fixed point, looking at a point or following an entity. */
+    placeFreeCamera(world, view) {
+        this.camera.position.set(view.from.x, view.from.y, view.from.z);
+        if (typeof view.at === "string") {
+            const target = world.entities.find((e) => e.id === view.at);
+            const t = target?.transform ?? { x: 0, y: 0, z: 0 };
+            this.camera.lookAt(t.x, t.y, t.z);
+        }
+        else
+            this.camera.lookAt(view.at.x, view.at.y, view.at.z);
+    }
+    /**
+     * Map view: straight down on everything drawn, north (-z) up, with no perspective so
+     * distances read true. Fog is off and the light is even: the map is about where things are.
+     */
+    renderMap() {
+        const bounds = new THREE.Box3();
+        for (const object of this.objects.values())
+            if (object.visible)
+                bounds.expandByObject(object);
+        if (bounds.isEmpty())
+            bounds.set(new THREE.Vector3(-10, 0, -10), new THREE.Vector3(10, 0, 10));
+        const center = bounds.getCenter(new THREE.Vector3());
+        const size = bounds.getSize(new THREE.Vector3());
+        const aspect = this.canvas.width / this.canvas.height;
+        const halfWidth = Math.max(size.x / 2, (size.z / 2) * aspect, 1) * 1.08;
+        const cam = this.mapCamera;
+        Object.assign(cam, { left: -halfWidth, right: halfWidth, top: halfWidth / aspect, bottom: -halfWidth / aspect, near: 0.1, far: size.y + 40 });
+        cam.position.set(center.x, bounds.max.y + 20, center.z);
+        cam.up.set(0, 0, -1);
+        cam.lookAt(center.x, bounds.min.y, center.z);
+        cam.updateProjectionMatrix();
+        cam.updateMatrixWorld();
+        const fog = this.scene.fog;
+        this.scene.fog = null;
+        this.scene.add(this.mapLight);
+        this.renderer.render(this.scene, cam);
+        this.scene.remove(this.mapLight);
+        this.scene.fog = fog;
     }
     /** Waits for every addon render hooks asked for, and for what their callbacks start in turn. */
     async settle() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludra/three",
-  "version": "0.92.0",
+  "version": "0.94.0",
   "description": "The 3D renderer for Ludra: Three.js meshes, PBR materials, lights, shadows, cameras and environments for 3D scenes.",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "src"
   ],
   "dependencies": {
-    "@ludra/core": "0.92.0",
+    "@ludra/core": "0.94.0",
     "three": "0.186.1"
   },
   "devDependencies": {

package/src/index.ts

@@ -18,7 +18,7 @@ import {
   type RenderContext,
   type SceneDef,
 } from "@ludra/core";
-import type { Renderer3D, Renderer3DFactory } from "@ludra/core/browser";
+import type { CameraView, Renderer3D, Renderer3DFactory } from "@ludra/core/browser";
 
 /**
  * The 3D renderer for Ludra: Three.js draws every entity with a `mesh` and lights the scene
@@ -78,6 +78,12 @@ interface Rig {
 export class ThreeRenderer implements Renderer3D {
   readonly canvas: HTMLCanvasElement;
   debug = false;
+  view: CameraView | undefined;
+  hidden: ReadonlySet<string> | undefined;
+  /** The map view's camera, fitted to the level every frame. */
+  private readonly mapCamera = new THREE.OrthographicCamera();
+  /** Lights the map evenly, so a night scene reads as well as a day one. */
+  private readonly mapLight = new THREE.AmbientLight(0xffffff, 3);
   /** Three.js itself, for render hooks and anything else (step 4 hands these to scripts). */
   readonly renderer: THREE.WebGLRenderer;
   readonly scene = new THREE.Scene();
@@ -227,10 +233,86 @@ export class ThreeRenderer implements Renderer3D {
     const rig = this.rig!;
     this.camera.position.copy(rig.position);
     this.camera.lookAt(rig.look);
+    if (this.view?.mode === "free") this.placeFreeCamera(world, this.view);
     this.poseModels(world);
     this.runRenderHooks(world);
-    if (this.customRender) this.customRender();
+    const concealed = this.conceal();
+    if (this.view?.mode === "map") this.renderMap();
+    else if (this.customRender) this.customRender();
     else this.renderer.render(this.scene, this.camera);
+    for (const object of concealed) object.visible = true;
+  }
+
+  /** Hides what the hidden entities show. Their lights stay on: what's behind them must look the same. */
+  private conceal(): THREE.Object3D[] {
+    const concealed: THREE.Object3D[] = [];
+    if (!this.hidden?.size) return concealed;
+    const roots = [...this.objects, ...this.hookGroups].filter(([e]) => this.hidden!.has(e.id));
+    for (const [, root] of roots) {
+      root.traverse((object) => {
+        const shape = object as Partial<THREE.Mesh & THREE.Line & THREE.Points & THREE.Sprite>;
+        if (!object.visible || !(shape.isMesh || shape.isLine || shape.isPoints || shape.isSprite)) return;
+        object.visible = false;
+        concealed.push(object);
+      });
+    }
+    return concealed;
+  }
+
+  /** In the map view: every entity with a body or mesh, at its place on the map. Ground-sized ones are left out. */
+  labels(world: WorldView): { text: string; x: number; y: number }[] {
+    if (this.view?.mode !== "map") return [];
+    const { width, height } = this.canvas;
+    const cam = this.mapCamera;
+    const mapArea = (cam.right - cam.left) * (cam.top - cam.bottom);
+    const labels: { text: string; x: number; y: number }[] = [];
+    const size = new THREE.Vector3();
+    for (const e of world.entities) {
+      if (!e.body && !e.mesh) continue;
+      const object = this.objects.get(e);
+      if (object && new THREE.Box3().setFromObject(object).getSize(size) && size.x * size.z > mapArea * 0.2) continue;
+      const point = new THREE.Vector3(e.transform.x, e.transform.y, e.transform.z).project(cam);
+      if (Math.abs(point.x) > 1 || Math.abs(point.y) > 1) continue;
+      labels.push({ text: e.id, x: ((point.x + 1) / 2) * width, y: ((1 - point.y) / 2) * height });
+    }
+    return labels;
+  }
+
+  /** Free view: from a fixed point, looking at a point or following an entity. */
+  private placeFreeCamera(world: WorldView, view: Extract<CameraView, { mode: "free" }>): void {
+    this.camera.position.set(view.from.x, view.from.y, view.from.z);
+    if (typeof view.at === "string") {
+      const target = world.entities.find((e) => e.id === view.at);
+      const t = target?.transform ?? { x: 0, y: 0, z: 0 };
+      this.camera.lookAt(t.x, t.y, t.z);
+    } else this.camera.lookAt(view.at.x, view.at.y, view.at.z);
+  }
+
+  /**
+   * Map view: straight down on everything drawn, north (-z) up, with no perspective so
+   * distances read true. Fog is off and the light is even: the map is about where things are.
+   */
+  private renderMap(): void {
+    const bounds = new THREE.Box3();
+    for (const object of this.objects.values()) if (object.visible) bounds.expandByObject(object);
+    if (bounds.isEmpty()) bounds.set(new THREE.Vector3(-10, 0, -10), new THREE.Vector3(10, 0, 10));
+    const center = bounds.getCenter(new THREE.Vector3());
+    const size = bounds.getSize(new THREE.Vector3());
+    const aspect = this.canvas.width / this.canvas.height;
+    const halfWidth = Math.max(size.x / 2, (size.z / 2) * aspect, 1) * 1.08;
+    const cam = this.mapCamera;
+    Object.assign(cam, { left: -halfWidth, right: halfWidth, top: halfWidth / aspect, bottom: -halfWidth / aspect, near: 0.1, far: size.y + 40 });
+    cam.position.set(center.x, bounds.max.y + 20, center.z);
+    cam.up.set(0, 0, -1);
+    cam.lookAt(center.x, bounds.min.y, center.z);
+    cam.updateProjectionMatrix();
+    cam.updateMatrixWorld();
+    const fog = this.scene.fog;
+    this.scene.fog = null;
+    this.scene.add(this.mapLight);
+    this.renderer.render(this.scene, cam);
+    this.scene.remove(this.mapLight);
+    this.scene.fog = fog;
   }
 
   /** Waits for every addon render hooks asked for, and for what their callbacks start in turn. */