melonjs 20.3.0 → 20.5.0

package/build/renderable/instanced_mesh.d.ts

@@ -28,6 +28,32 @@
  * Requires a GPU backend (`renderer.supportsInstancing`). Under the Canvas
  * renderer the instances are drawn one at a time through the ordinary CPU
  * mesh path — correct, but without any of the benefit.
+ *
+ * ### When a plain {@link Mesh} each is the better answer
+ *
+ * One `InstancedMesh` is **one geometry and one material**, and four things
+ * move from per-object to per-group:
+ *
+ * - **Depth sorting.** The set has a single sort key — its own `pos` — so it
+ *   orders against the rest of the scene as one object. Opaque instances still
+ *   resolve against each other per pixel through the depth buffer; blended
+ *   ones cannot be sorted among themselves at all.
+ * - **Ground shadows.** {@link Mesh#castGroundShadow} becomes one instanced
+ *   shadow draw covering the whole set, not a blob computed per object.
+ * - **Removal.** {@link InstancedMesh#removeInstance} swaps the last instance
+ *   into the hole, so any index a caller was holding now refers to a different
+ *   object.
+ * - **Colour.** {@link Mesh#tint} applies to the set; per-instance colour has
+ *   to be declared up front with `instanceColors` and set through
+ *   {@link InstancedMesh#setInstanceColor}.
+ *
+ * So the question is not how many there are, but whether the game addresses
+ * them **individually**. Scenery — trees, rocks, grass, debris — instances
+ * cleanly, because nothing ever asks about one of them. Collision-tested props
+ * are fine too: the positions are yours either way and instancing only changes
+ * how they are drawn. Collectibles and enemies usually are not, because
+ * removing them one at a time makes the index swap the caller's problem, and
+ * at small counts a pooled `Mesh` each is less code and no slower.
  * @augments Mesh
  * @category Rendering
  * @example
@@ -53,28 +79,25 @@
  * forest.visibleInstanceCount = 1200;
  * app.world.addChild(forest, 10);
  */
+/**
+ * Everything {@link InstancedMesh} takes: the instancing settings, plus every
+ * {@link MeshSettings} — they are handed to {@link Mesh} whole, so the type
+ * says so by intersection rather than by copying the list.
+ * @typedef {object} InstancedMeshOwnSettings
+ * @property {number} [instanceCount=0] - number of instances to pre-allocate. Instances start at the group origin (identity transform) until placed; `addInstance` grows past this.
+ * @property {boolean} [instanceColors=false] - give each instance its own colour (16 bytes per instance), multiplied into the mesh tint
+ * @property {boolean} [instanceData=false] - give each instance an opaque `vec4` (16 bytes per instance). Read as emissive by the built-in lit shading, or as anything at all by a custom mesh shader.
+ */
+/**
+ * @typedef {InstancedMeshOwnSettings & import("./mesh.js").MeshSettings} InstancedMeshSettings
+ */
 export default class InstancedMesh extends Mesh {
     /**
      * @param {number} x - the x coordinate of the group origin
      * @param {number} y - the y coordinate of the group origin
-     * @param {object} settings - every {@link Mesh} setting, plus those below
-     * @param {number} [settings.instanceCount=0] - number of instances to pre-allocate. Instances start at the group origin (identity transform) until placed; `addInstance` grows past this.
-     * @param {boolean} [settings.instanceColors=false] - give each instance its own colour (16 bytes per instance), multiplied into the mesh tint
-     * @param {boolean} [settings.instanceData=false] - give each instance an opaque `vec4` (16 bytes per instance). Read as emissive by the built-in lit shading, or as anything at all by a custom mesh shader.
+     * @param {InstancedMeshSettings} settings - every {@link Mesh} setting, plus the instancing ones
      */
-    constructor(x: number, y: number, settings: {
-        instanceCount?: number | undefined;
-        instanceColors?: boolean | undefined;
-        instanceData?: boolean | undefined;
-    });
-    /**
-     * How this mesh's per-instance records are laid out — record width and
-     * the offset of each opt-in slot. Consumed by the batchers to describe
-     * the instance vertex buffer.
-     * @type {object}
-     * @ignore
-     */
-    instanceLayout: object;
+    constructor(x: number, y: number, settings: InstancedMeshSettings);
     /**
      * The packed instance records, `instanceLayout.floats` per instance.
      * Editable in place for bulk updates — announce those with
@@ -84,27 +107,6 @@ export default class InstancedMesh extends Mesh {
      * @type {Float32Array}
      */
     instanceBuffer: Float32Array;
-    /**
-     * bumped whenever the buffer is reallocated, so a renderer holding a
-     * GPU copy knows its capacity assumption is stale
-     * @type {number}
-     * @ignore
-     */
-    _instanceVersion: number;
-    /** @ignore */
-    _instanceRevision: number;
-    /** @ignore */
-    _spanFromRevision: number;
-    /** @ignore */
-    _dirtyFirst: number;
-    /** @ignore */
-    _dirtyLast: number;
-    /** @ignore */
-    _instanceCount: number;
-    /** @ignore */
-    _visibleInstanceCount: number;
-    /** @ignore */
-    _cullRevision: number;
     set instanceCount(count: number);
     /**
      * How many instances this mesh holds.
@@ -197,50 +199,6 @@ export default class InstancedMesh extends Mesh {
      * forest.needsInstanceUpdate = true;
      */
     set needsInstanceUpdate(value: any);
-    /**
-     * The dirty span, in floats, as `[first, lastExclusive)`. Empty when
-     * nothing changed since the last upload.
-     * @returns {number[]} the span
-     * @ignore
-     */
-    dirtyRange(): number[];
-    /**
-     * What one GPU buffer must upload to catch up, given the revision it last
-     * reached. Replaces a shared "clear the dirty flag" step, which the first
-     * consumer would drain out from under the second.
-     * @param {number} uploadedRevision - the revision that buffer holds
-     * @returns {object} `{first, count, full, revision}` — float span, or `full`
-     * @ignore
-     */
-    instanceUpload(uploadedRevision: number): object;
-    /**
-     * Called by the batcher once the dirty span has been uploaded.
-     * @ignore
-     */
-    clearInstanceDirty(): void;
-    /**
-     * The world-space bounding box of every instance, so the whole group
-     * frustum-culls as one object.
-     *
-     * Bounds the prototype geometry through each instance transform and then
-     * through the group placement — correct before the first draw, like the
-     * base implementation, and independent of what any draw left behind.
-     * @returns {AABB3d} the union of all instance bounds (reused instance)
-     */
-    /**
-     * Resize the renderable's own 2D bounds box so it encloses every
-     * instance.
-     *
-     * This is what makes the group frustum-cull correctly. `Camera3d.isVisible`
-     * tests a sphere derived from `getBounds()` — the flat width/height box —
-     * **not** {@link InstancedMesh#getBounds3d}. Left at the prototype's size,
-     * a forest scattered over thousands of units presents a box a few tens of
-     * pixels across at the group origin: pan the camera just past that origin
-     * and every instance disappears at once, while still on screen.
-     * @ignore
-     */
-    _refreshCullVolume(): any;
-    _cullRadius: number | undefined;
     /**
      * Draw the instanced mesh. Under a GPU backend this is one instanced
      * draw call; the Canvas renderer has no instancing, so each instance is
@@ -249,38 +207,27 @@ export default class InstancedMesh extends Mesh {
      * @param {Camera2d} [viewport] - the camera rendering this frame
      */
     draw(renderer: CanvasRenderer | WebGLRenderer, viewport?: Camera2d): void;
+}
+/**
+ * Everything {@link InstancedMesh} takes: the instancing settings, plus every
+ * {@link MeshSettings} — they are handed to {@link Mesh} whole, so the type
+ * says so by intersection rather than by copying the list.
+ */
+export type InstancedMeshOwnSettings = {
     /**
-     * Fallback for renderers without instancing (Canvas): walk the instances
-     * and draw the prototype once per instance, composing the group and
-     * instance transforms by hand. Correct, and as slow as the uninstanced
-     * scene it replaces — the point is that a scene authored for instancing
-     * still renders everywhere.
-     * @param {CanvasRenderer} renderer - a renderer instance
-     * @param {Camera2d} [viewport] - the camera rendering this frame
-     * @ignore
+     * - number of instances to pre-allocate. Instances start at the group origin (identity transform) until placed; `addInstance` grows past this.
      */
-    _drawInstancesIndividually(renderer: CanvasRenderer, viewport?: Camera2d): void;
+    instanceCount?: number;
     /**
-     * Release the instance records along with the mesh.
-     * @ignore
+     * - give each instance its own colour (16 bytes per instance), multiplied into the mesh tint
      */
+    instanceColors?: boolean;
     /**
-     * Draw a ground shadow for every visible instance — one call for the whole
-     * set, over the instance buffer the mesh itself just drew from (#1515).
-     *
-     * The group matrix is passed with its Y basis column zeroed and its
-     * translation Y set to the ground, so whatever Y the shadow vertex stage
-     * produces is flattened onto the floor. That is what lets the ground
-     * height reach the shader without a new uniform.
-     *
-     * One ground height serves the whole set — flat terrain. Per-instance
-     * ground height would have to ride the `instanceData` slot, which the
-     * built-in shading already reads as emissive.
-     * @param {WebGLRenderer} renderer - the active renderer
-     * @ignore
+     * - give each instance an opaque `vec4` (16 bytes per instance). Read as emissive by the built-in lit shading, or as anything at all by a custom mesh shader.
      */
-    _drawInstancedGroundShadow(renderer: WebGLRenderer): void;
-}
+    instanceData?: boolean;
+};
+export type InstancedMeshSettings = InstancedMeshOwnSettings & import("./mesh.js").MeshSettings;
 import Mesh from "./mesh.js";
 import { Matrix3d } from "../math/matrix3d.ts";
 //# sourceMappingURL=instanced_mesh.d.ts.map

package/build/renderable/instanced_mesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instanced_mesh.d.ts","sourceRoot":"","sources":["../../src/renderable/instanced_mesh.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH;IACC;;;;;;;OAOG;IACH,eAPW,MAAM,KACN,MAAM,YAEd;QAA0B,aAAa;QACZ,cAAc;QACd,YAAY;KACzC,EAiEA;IA7DA;;;;;;OAMG;IACH,gBAHU,MAAM,CAMf;IAED;;;;;;;OAOG;IACH,gBAFU,YAAY,CAEmB;IAEzC;;;;;OAKG;IACH,kBAHU,MAAM,CAGS;IAUzB,cAAc;IACd,0BAA0B;IAG1B,cAAc;IACd,0BAA0B;IAE1B,cAAc;IACd,oBAA2B;IAC3B,cAAc;IACd,mBAAmB;IAEnB,cAAc;IACd,uBAAuB;IACvB,cAAc;IACd,8BAA+B;IAE/B,cAAc;IACd,sBAAuB;IAoBxB,yBANU,MAAM,EAgDf;IAvDD;;;;;;;;OAQG;IACH,qBAFU,MAAM,CAIf;IA8DD,gCAVU,MAAM,EAiBf;IAvBD;;;;;;;;;OASG;IACH,4BAJU,MAAM,CAQf;IAWD;;;;;;;OAOG;IACH,wBANW,QAAQ,YAEhB;QAAwB,KAAK;QACF,IAAI;KAC/B,GAAU,MAAM,CAqBlB;IAED;;;;;;;;;OASG;IACH,sBAFW,MAAM,QAiBhB;IAED;;;;OAIG;IACH,mBAHW,MAAM,aACN,QAAQ,QAYlB;IAED;;;;;OAKG;IACH,mBAJW,MAAM,QACN,QAAQ,GACN,QAAQ,GAAC,SAAS,CAW9B;IAED;;;;OAIG;IACH,wBAHW,MAAM,SACN,KAAK,QAaf;IAED;;;;;;;OAOG;IACH,uBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,QAahB;IAED;;;;;;OAMG;IACH,0BAHW,MAAM,SACN,MAAM,QAyBhB;IAED;;;;;;;;OAQG;IAEH,oCAIC;IAED;;;;;OAKG;IACH,cAHa,MAAM,EAAE,CAYpB;IAED;;;;;;;OAOG;IACH,iCAJW,MAAM,GACJ,MAAM,CAclB;IAED;;;OAGG;IACH,2BAIC;IAED;;;;;;;;OAQG;IACH;;;;;;;;;;;OAWG;IACH,0BA8BC;IAVC,gCAAsC;IAkDxC;;;;;;OAMG;IACH,eAHW,cAAc,GAAC,aAAa,aAC5B,QAAQ,QA6BlB;IAED;;;;;;;;;OASG;IACH,qCAJW,cAAc,aACd,QAAQ,QA6BlB;IAED;;;OAGG;IACH;;;;;;;;;;;;;;OAcG;IACH,qCAHW,aAAa,QAqEvB;CAOD;iBAlsBgB,WAAW;yBATH,qBAAqB"}
+{"version":3,"file":"instanced_mesh.d.ts","sourceRoot":"","sources":["../../src/renderable/instanced_mesh.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH;;;;;;;;GAQG;AAEH;;GAEG;AAEH;IACC;;;;OAIG;IACH,eAJW,MAAM,KACN,MAAM,YACN,qBAAqB,EAyF/B;IApFA;;;;;;;OAOG;IACH,gBAJU,MAAM,CAOf;IAED;;;;;;;OAOG;IACH,gBAFU,YAAY,CAEmB;IAEzC;;;;;;OAMG;IACH,kBAJU,MAAM,CAIS;IAUzB;;;OAGG;IACH,0BAA0B;IAG1B;;;OAGG;IACH,0BAA0B;IAE1B;;;OAGG;IACH,oBAA2B;IAC3B;;;OAGG;IACH,mBAAmB;IAEnB;;;OAGG;IACH,uBAAuB;IACvB;;;OAGG;IACH,8BAA+B;IAE/B;;;OAGG;IACH,sBAAuB;IAoBxB,yBANU,MAAM,EAgDf;IAvDD;;;;;;;;OAQG;IACH,qBAFU,MAAM,CAIf;IA8DD,gCAVU,MAAM,EAiBf;IAvBD;;;;;;;;;OASG;IACH,4BAJU,MAAM,CAQf;IAWD;;;;;;;OAOG;IACH,wBANW,QAAQ,YAEhB;QAAwB,KAAK;QACF,IAAI;KAC/B,GAAU,MAAM,CAqBlB;IAED;;;;;;;;;OASG;IACH,sBAFW,MAAM,QAiBhB;IAED;;;;OAIG;IACH,mBAHW,MAAM,aACN,QAAQ,QAYlB;IAED;;;;;OAKG;IACH,mBAJW,MAAM,QACN,QAAQ,GACN,QAAQ,GAAC,SAAS,CAW9B;IAED;;;;OAIG;IACH,wBAHW,MAAM,SACN,KAAK,QAaf;IAED;;;;;;;OAOG;IACH,uBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,QAahB;IAED;;;;;;OAMG;IACH,0BAHW,MAAM,SACN,MAAM,QAyBhB;IAED;;;;;;;;OAQG;IAEH,oCAIC;IAED;;;;;;OAMG;IACH,cAJa,MAAM,EAAE,CAapB;IAED;;;;;;;;OAQG;IACH,iCALW,MAAM,GACJ,MAAM,CAelB;IAED;;;;OAIG;IACH,2BAIC;IAED;;;;;;;;OAQG;IACH;;;;;;;;;;;;OAYG;IACH,0BAkCC;IAdC;;;OAGG;IACH,gCAAsC;IAqDxC;;;;;;OAMG;IACH,eAHW,cAAc,GAAC,aAAa,aAC5B,QAAQ,QA6BlB;IAED;;;;;;;;;;OAUG;IACH,qCALW,cAAc,aACd,QAAQ,QA8BlB;IAED;;;;OAIG;IACH;;;;;;;;;;;;;;;OAeG;IACH,qCAJW,aAAa,QAsEvB;CAOD;;;;;;;;;;oBA1qBa,MAAM;;;;qBACN,OAAO;;;;mBACP,OAAO;;oCAIR,wBAAwB,GAAG,OAAO,WAAW,EAAE,YAAY;iBAxGvD,WAAW;yBATH,qBAAqB"}