emeraldengine 3.0.0 → 3.1.0

package/dist/types/index.d.ts

@@ -40,6 +40,7 @@ import ParticleEmitter from "./src/ParticleEmitter.js";
 import CollisionLayers from "./src/CollisionLayers.js";
 import TiledMap from "./src/importers/TiledMap.js";
 import Aseprite from "./src/importers/Aseprite.js";
+import ForgeLevel from "./src/importers/ForgeLevel.js";
 import RenderTarget from "./src/RenderTarget.js";
 import RenderStats from "./src/managers/RenderStats.js";
 import PostProcessor from "./src/PostProcessor.js";
@@ -49,6 +50,7 @@ import { BloomEffect } from "./src/PostEffects.js";
 import Material from "./src/Material.js";
 import UI from "./src/UI.js";
 import InputManager from "./src/managers/InputManager.js";
+import Gamepad from "./src/managers/Gamepad.js";
 import Particle from "./src/particlesystem/Particle.js";
 import Particles from "./src/particlesystem/Particles.js";
 import ParticleSettings from "./src/particlesystem/ParticleSettings.js";
@@ -65,8 +67,9 @@ import BoxCollider from "./src/components/BoxCollider.js";
 import BoxColliderDebug from "./src/components/BoxColliderDebug.js";
 import CircleCollider from "./src/components/CircleCollider.js";
 import CircleColliderDebug from "./src/components/CircleColliderDebug.js";
+import PolygonCollider from "./src/components/PolygonCollider.js";
 import Collider from "./src/components/Collider.js";
 import GameObject from "./src/components/GameObject.js";
 import RigidBody from "./src/components/RigidBody.js";
 import Behaviour from "./src/components/Behaviour.js";
-export { Emerald, BitmapText, Color, Drawable, FPSCounter, Instance, InstancedTexture, Physics, Vector2, Vector3, Scene, Square2D, Triangle2D, Circle2D, Storage, EmeraldDB, Texture, Time, Transform, MathUtils, Pool, Animator, Tilemap, CameraController, Camera, Easing, Tween, Timer, StateMachine, SpatialGrid, TextureAtlas, CanvasText, DebugOverlay, Serializer, Coroutine, Interpolator, ScreenEffects, SpriteBatch, ParticleEmitter, CollisionLayers, TiledMap, Aseprite, RenderTarget, RenderStats, PostProcessor, PostEffect, PostEffects, BloomEffect, Material, UI, InputManager, Particle, Particles, ParticleSettings, AudioManager, CameraManager, EventManager, SceneManager, TextureManager, AssetManager, NetworkManager, DirectionalLight, PointLight, BoxCollider, BoxColliderDebug, CircleCollider, CircleColliderDebug, Collider, GameObject, RigidBody, Behaviour };
+export { Emerald, BitmapText, Color, Drawable, FPSCounter, Instance, InstancedTexture, Physics, Vector2, Vector3, Scene, Square2D, Triangle2D, Circle2D, Storage, EmeraldDB, Texture, Time, Transform, MathUtils, Pool, Animator, Tilemap, CameraController, Camera, Easing, Tween, Timer, StateMachine, SpatialGrid, TextureAtlas, CanvasText, DebugOverlay, Serializer, Coroutine, Interpolator, ScreenEffects, SpriteBatch, ParticleEmitter, CollisionLayers, TiledMap, Aseprite, ForgeLevel, RenderTarget, RenderStats, PostProcessor, PostEffect, PostEffects, BloomEffect, Material, UI, InputManager, Gamepad, Particle, Particles, ParticleSettings, AudioManager, CameraManager, EventManager, SceneManager, TextureManager, AssetManager, NetworkManager, DirectionalLight, PointLight, BoxCollider, BoxColliderDebug, CircleCollider, CircleColliderDebug, PolygonCollider, Collider, GameObject, RigidBody, Behaviour };

package/dist/types/src/Animator.d.ts

@@ -3,7 +3,7 @@ export default Animator;
  * @class Animator
  * @description A component that manages named animation clips for a Texture (or
  * any Drawable) on the same GameObject. Register clips once, then switch between
- * them by name — handy for character states like idle/run/jump.
+ * them by name, handy for character states like idle/run/jump.
  *
  * @example
  * const anim = new Animator();

package/dist/types/src/CollisionLayers.d.ts

@@ -40,13 +40,13 @@ declare namespace CollisionLayers {
 /**
  * @class CollisionLayers
  * @description A small registry that maps human-readable layer names to the
- * category bits planck uses for collision filtering, so games can say
+ * category bits the physics engine uses for collision filtering, so games can
  * "players collide with ground and enemies, but not with each other" without
  * juggling raw bitmasks.
  *
  * Two fixtures collide only if each one's category is in the other's mask, so
  * filtering is symmetric by construction. Up to 16 distinct layers are
- * supported (planck filter bits are 16-bit).
+ * supported (filter bits are 16-bit).
  *
  * @example
  * CollisionLayers.define("ground", "player", "enemy", "pickup");

package/dist/types/src/Color.d.ts

@@ -8,6 +8,7 @@ export default Color;
  * @param {number} a - The alpha value
  */
 declare class Color {
+    static fromHex(hex: any): Color;
     constructor(r: any, g: any, b: any, a?: number);
     r: any;
     g: any;

package/dist/types/src/Drawable.d.ts

@@ -206,7 +206,7 @@ declare class Drawable {
      * @description Frees this drawable's GPU resources: its vertex/texcoord
      * buffers and its reference on the shared texture (the GL texture itself is
      * deleted when the last drawable using it is disposed). Call it when the
-     * owning object is permanently removed — GameObject.destroy() and
+     * owning object is permanently removed. GameObject.destroy() and
      * Scene.remove(obj, { dispose: true }) do it for you. Safe to call twice.
      */
     dispose(): void;

package/dist/types/src/EmeraldDB.d.ts

@@ -1,7 +1,7 @@
 export default EmeraldDB;
 /**
  * @class EmeraldDB
- * @description Async game-save storage on IndexedDB — the big-world companion
+ * @description Async game-save storage on IndexedDB, the big-world companion
  * to `Storage` (localStorage). Same versioned-envelope semantics (`{v,t,data}`
  * with a `.bak` backup and forward migration), but with no ~5MB quota and no
  * JSON round-trip: values are structured-cloned, so large nested world state
@@ -56,7 +56,7 @@ declare class EmeraldDB {
     private static _tx;
     /**
      * @method set
-     * @description Stores a value under a key (structured clone — objects, Maps,
+     * @description Stores a value under a key (structured clone: objects, Maps,
      * Sets, typed arrays all survive).
      * @param {string} key
      * @param {*} value

package/dist/types/src/InstancedTexture.d.ts

@@ -28,6 +28,8 @@ declare class InstancedTexture extends Drawable {
     static: boolean;
     /** @private */
     private _matricesDirty;
+    /** The animation every instance starts with; set by playAnimation/playAnimationOnce. @private */
+    private _defaultAnimation;
     /**
      * @method setStatic
      * @description Toggles static mode (see constructor notes).
@@ -257,11 +259,24 @@ declare class InstancedTexture extends Drawable {
     handleInstanceHover(event: Event, x: number, y: number, lastHoveredInstance: Instance): Instance;
     /**
      * @method playAnimationOnce
-     * @description Plays an animation once
+     * @description Plays the same animation once, in lockstep, on every
+     * instance, then holds each on its last frame: the current instances
+     * immediately, and any added later via {@link InstancedTexture#addInstance}.
      * @param {Array} frames - The frames to play
-     * @param {number} speed - The speed of the animation
+     * @param {number} [speed=1000] - Milliseconds per frame
      */
     playAnimationOnce(frames: any[], speed?: number): void;
+    /**
+     * @method stopAnimation
+     * @description Stops the shared animation started by playAnimation/
+     * playAnimationOnce on every current instance, and clears it so instances
+     * added afterwards no longer start playing it either. Instances animated
+     * individually via {@link InstancedTexture#animateInstance} are unaffected
+     * unless you stop them the same way, through {@link InstancedTexture#stopInstanceAnimation}.
+     * @param {boolean} [revertToOriginal=false] - Whether to reset each
+     *   instance back to the frame it had before playAnimation was called
+     */
+    stopAnimation(revertToOriginal?: boolean): void;
 }
 import Drawable from "./Drawable.js";
 import Instance from "./Instance.js";

package/dist/types/src/Material.d.ts

@@ -4,7 +4,7 @@ export default Material;
  * @description A custom shader for a Drawable. By default it reuses the engine's
  * standard vertex shader (so transforms, the camera, and instancing keep
  * working) and only overrides the fragment program. Pass `options.vertex` to
- * also supply a custom VERTEX program — the escape hatch for effects the fixed
+ * also supply a custom VERTEX program: the escape hatch for effects the fixed
  * pipeline can't express (perspective tilt, vertex waves, billboarding, ...).
  *
  * The fragment shader always has: `vTexCoord`, `vFragPos`, `vInstanceColor`,
@@ -13,7 +13,7 @@ export default Material;
  * `uTime`, and must write `vTexCoord` + `gl_Position`.
  *
  * Declare extra uniforms and set them via `set(name, value)`. A uniform value
- * may be a number, an array (vec2/3/4), or a FUNCTION — the function is called
+ * may be a number, an array (vec2/3/4), or a FUNCTION: the function is called
  * each draw and receives the Drawable currently rendering, so a single shared
  * Material can read PER-OBJECT state (e.g. each card's own tilt angle).
  *

package/dist/types/src/MathUtils.d.ts

@@ -3,7 +3,8 @@ export default MathUtils;
  * @class MathUtils
  * @description Common math helpers for games: interpolation, clamping, angle
  * conversion, random ranges, and lightweight 2D vector operations that work on
- * any `{ x, y }` object (including planck Vec2 and Emerald Vector2).
+ * any `{ x, y }` object (including the physics engine's Vec2 and Emerald
+ * Vector2).
  */
 declare class MathUtils {
     /**

package/dist/types/src/ParticleEmitter.d.ts

@@ -3,7 +3,7 @@ export default ParticleEmitter;
  * @class ParticleEmitter
  * @description A reliable, allocation-free particle system built from a fixed
  * pool of ordinary textured GameObjects. Each live particle's transform, tint
- * and opacity are driven by hand every frame — there is no instanced-draw /
+ * and opacity are driven by hand every frame; there is no instanced-draw /
  * dynamic-buffer lifecycle to desync, so it keeps drawing for the whole session
  * (unlike the InstancedTexture-based `Particles`, which can stop emitting after
  * heavy reuse on some GPUs).

package/dist/types/src/Physics.d.ts

@@ -1,9 +1,14 @@
 /**
  * @class Physics
- * @description Represents the physics engine
+ * @description The game-facing front end of Emerald's own rigid-body engine
+ * (see `src/physics`). It owns the {@link World}, converts between world
+ * (pixel) units and physics units via `scale`, steps the simulation on a fixed
+ * timestep, and routes contacts to `onCollisionEnter`/`onCollisionExit` on your
+ * objects and {@link Behaviour} components.
  * @param {number} gravity - The gravity of the physics engine
- * @param {number} scale - The scale of the physics engine
- * @param {number} velocityThreshold - The velocity threshold of the physics engine
+ * @param {number} scale - Pixels per physics unit (meter)
+ * @param {number} velocityThreshold - Relative speed below which impacts stop
+ *   bouncing, which is what lets resting bodies settle instead of jittering
  */
 export class Physics {
     /**
@@ -13,18 +18,30 @@ export class Physics {
      */
     static scheduleAction(callback: Function): void;
     constructor(gravity: any, scale: any, velocityThreshold?: number);
-    world: planck.World;
+    world: World;
     gravity: any;
     scale: any;
     fixedTimeStep: number;
     maxSubSteps: number;
+    /** Largest slice the variable mode will simulate in one step. */
+    maxTimeStep: number;
+    /** "fixed" or "variable", see {@link Physics#setVariableTimeStep}. */
+    timeStepMode: string;
+    /** Steps taken by the last process() call. */
+    lastStepCount: number;
     /** @private */
     private _accumulator;
+    /** World-level listeners added via onCollisionEnter. @private */
+    private _enterCallbacks;
+    /** World-level listeners added via onCollisionExit. @private */
+    private _exitCallbacks;
     /**
      * @method _dispatchContacts
-     * @description Routes planck contacts to the owning objects so Behaviour
-     * components receive onCollisionEnter/onCollisionExit. Bodies created through
-     * RigidBody carry the owner via userData.
+     * @description Binds contact routing to the current world: owning objects (so
+     * Behaviour components receive onCollisionEnter/onCollisionExit) first, then
+     * any world-level listeners. Bodies created through RigidBody carry the owner
+     * via userData. Re-run whenever the world is replaced, so subscriptions
+     * survive a clear().
      * @private
      */
     private _dispatchContacts;
@@ -52,11 +69,54 @@ export class Physics {
     queryPoint(point: any): any[];
     /**
      * @method setFixedTimeStep
-     * @description Sets the fixed physics step (seconds) and optional substep cap.
+     * @description Runs the simulation in constant-size slices, independent of
+     * the frame rate: `process()` banks the elapsed time and steps as many whole
+     * slices as fit. This is the default and the safe choice: the same inputs
+     * produce the same result on every machine, and a slow frame can't destabilise
+     * the solver.
+     *
+     * The cost is that motion updates at the step rate, not the display rate. On
+     * a 120Hz screen with a 1/60 step, every simulated position is shown for two
+     * frames, so anything that moves in the render frame (a smoothly lerped
+     * camera, for instance) will slide against sprites that only move every other
+     * frame. Either drive those from the same fixed step, or use
+     * {@link Physics#setVariableTimeStep}.
+     *
      * @param {number} step - Fixed step in seconds (e.g. 1/60)
      * @param {number} [maxSubSteps] - Max steps per process() call (spiral guard)
+     * @returns {Physics} - this
      */
-    setFixedTimeStep(step: number, maxSubSteps?: number): void;
+    setFixedTimeStep(step: number, maxSubSteps?: number): Physics;
+    /**
+     * @method setVariableTimeStep
+     * @description Advances the simulation once per `process()` call using the
+     * frame's own delta, so physics runs at exactly the rendering rate. Every
+     * rendered frame then shows a freshly simulated position, which is what
+     * removes the stepping you otherwise see when the display refreshes faster
+     * than the simulation.
+     *
+     * The trade-offs are real and worth knowing:
+     * - **Not deterministic.** Results depend on the frame timings the machine
+     *   happened to produce, so replays and lockstep networking need fixed steps.
+     * - **Solver accuracy tracks the frame rate.** Contacts are resolved
+     *   iteratively, so a long frame is a coarser solve; deep stacks and fast
+     *   bodies are more forgiving under a fixed step.
+     *
+     * A frame longer than `maxStep` is split into several equal steps rather than
+     * simulated in one lump, up to `maxSubSteps`; beyond that the excess time is
+     * dropped instead of letting the world explode or spiral.
+     *
+     * @param {number} [maxStep=1/30] - Longest slice to simulate in one step
+     * @param {number} [maxSubSteps] - Max steps per process() call
+     * @returns {Physics} - this
+     */
+    setVariableTimeStep(maxStep?: number, maxSubSteps?: number): Physics;
+    /**
+     * @method getTimeStepMode
+     * @description Returns "fixed" or "variable".
+     * @returns {string}
+     */
+    getTimeStepMode(): string;
     /**
      * @method createBody
      * @description Creates a body in the physics engine
@@ -71,27 +131,97 @@ export class Physics {
      * @returns {Body} - The body
      */
     createBody(type: string, position?: Vector2, fixedRotation?: boolean, attachFixture?: boolean, fixtureSize?: Vector2, density?: number, friction?: number, restitution?: number): Body;
+    /**
+     * @method createDistanceJoint
+     * @description Connects two rigid bodies with a fixed-length rod between two
+     * world-space anchor points, or a damped spring toward that length when
+     * `frequencyHz` is set.
+     * @param {RigidBody} rigidBodyA
+     * @param {RigidBody} rigidBodyB
+     * @param {Object} [options] - `{ anchorA, anchorB, length, frequencyHz,
+     *   dampingRatio, collideConnected }`. `anchorA`/`anchorB` are world-space
+     *   pixel points; each defaults to its body's own center. `length` is in
+     *   pixels; it defaults to the current distance between the anchors.
+     * @returns {DistanceJoint}
+     */
+    createDistanceJoint(rigidBodyA: RigidBody, rigidBodyB: RigidBody, options?: any): DistanceJoint;
+    /**
+     * @method createRevoluteJoint
+     * @description Pins two rigid bodies together at a shared world-space point,
+     * like a hinge: a door, a pendulum arm, a see-saw. Set `enableMotor` to
+     * drive it toward a target angular speed instead of swinging freely.
+     * @param {RigidBody} rigidBodyA
+     * @param {RigidBody} rigidBodyB
+     * @param {Object} anchor - World-space pixel point both bodies pin to
+     * @param {Object} [options] - `{ enableMotor, motorSpeed, maxMotorTorque,
+     *   collideConnected }`
+     * @returns {RevoluteJoint}
+     */
+    createRevoluteJoint(rigidBodyA: RigidBody, rigidBodyB: RigidBody, anchor: any, options?: any): RevoluteJoint;
+    /**
+     * @method destroyJoint
+     * @description Removes a joint created by {@link Physics#createDistanceJoint}
+     * or {@link Physics#createRevoluteJoint}.
+     * @param {Joint} joint
+     */
+    destroyJoint(joint: Joint): void;
     /**
      * @method onCollisionEnter
-     * @description Handles the collision enter event
-     * @param {Function} callback - The callback function to handle the collision enter event
+     * @description Registers a world-level listener called whenever any two
+     * fixtures start touching. Survives {@link Physics#clear}.
+     * @param {Function} callback - Called with (bodyA, bodyB, contact)
      */
     onCollisionEnter(callback: Function): void;
     /**
      * @method onCollisionExit
-     * @description Handles the collision exit event
-     * @param {Function} callback - The callback function to handle the collision exit event
+     * @description Registers a world-level listener called whenever any two
+     * fixtures stop touching. Survives {@link Physics#clear}.
+     * @param {Function} callback - Called with (bodyA, bodyB, contact)
      */
     onCollisionExit(callback: Function): void;
     /**
      * @method process
-     * @description Processes the physics engine
-     * @param {number} dt - The delta time
+     * @description Advances the simulation by `dt` seconds, in whichever way the
+     * current time-step mode calls for. Call it once per frame.
+     * @param {number} dt - Seconds elapsed since the previous call
+     * @returns {number} - How many steps were simulated
+     */
+    process(dt: number): number;
+    /**
+     * @method _stepVariable
+     * @description Simulates the frame's own delta. Normally that is a single
+     * step of exactly `dt`, so physics advances in lock-step with rendering. Only
+     * an unusually long frame is divided, and only far enough to keep each slice
+     * within `maxTimeStep`.
+     * @param {number} dt
+     * @returns {number} - Steps taken
+     * @private
+     */
+    private _stepVariable;
+    /**
+     * @method _stepFixed
+     * @description Banks elapsed time and simulates as many constant-size slices
+     * as have accumulated, leaving the remainder for next frame.
+     * @param {number} dt
+     * @returns {number} - Steps taken
+     * @private
+     */
+    private _stepFixed;
+    /**
+     * @method getInterpolationAlpha
+     * @description How far the fixed-step simulation currently sits between its
+     * last completed step and the next one (0..1). Useful if you interpolate
+     * renderables between physics states. Always 0 in variable mode, where every
+     * frame already renders a freshly simulated position.
+     * @returns {number}
      */
-    process(dt: number): void;
+    getInterpolationAlpha(): number;
     /**
      * @method clear
-     * @description Clears the physics engine objects and resets the gravity
+     * @description Drops every body and starts a fresh world with the original
+     * gravity; use it when tearing a level down. Collision routing and any
+     * listeners added through onCollisionEnter/onCollisionExit are re-bound to
+     * the new world, so they keep working afterwards.
      */
     clear(): void;
     /**
@@ -204,4 +334,4 @@ export class Vector3 {
      */
     getZ(): number;
 }
-import * as planck from "planck";
+import { World } from "./physics/index.js";

package/dist/types/src/Scene.d.ts

@@ -27,7 +27,7 @@ declare class Scene {
      * @method dispose
      * @description Destroys every object in the scene (freeing their GPU
      * resources and physics bodies) and empties it. Call when a level/screen is
-     * torn down for good — removing objects without disposing leaks GL buffers
+     * torn down for good; removing objects without disposing leaks GL buffers
      * over repeated scene swaps.
      */
     dispose(): void;

package/dist/types/src/Shaders.d.ts

@@ -1,2 +1,2 @@
-export const STANDARD_VERTEX_SHADER: "\n  attribute vec4 aVertexPosition;\n  attribute vec2 aTextureCoord;\n  \n  attribute vec4 aInstanceMatrix0;\n  attribute vec4 aInstanceMatrix1;\n  attribute vec4 aInstanceMatrix2;\n  attribute vec4 aInstanceMatrix3;\n  \n  attribute vec2 aInstanceTexCoord0;\n  attribute vec2 aInstanceTexCoord1;\n  attribute vec2 aInstanceTexCoord2;\n  attribute vec2 aInstanceTexCoord3;\n\n  attribute vec4 aInstanceColor;\n\n  uniform mat4 uModelViewMatrix;\n  uniform mat4 uInstancedModelViewMatrix;\n  uniform mat4 uProjectionMatrix;\n  uniform bool useInstances;\n\n  varying highp vec2 vTexCoord;\n  varying vec2 vFragPos;\n  varying vec4 vInstanceColor;\n\n  void main() {\n    mat4 instanceMatrix = mat4(\n      aInstanceMatrix0,\n      aInstanceMatrix1,\n      aInstanceMatrix2,\n      aInstanceMatrix3\n    );\n    \n    if(useInstances) {\n        gl_Position = uProjectionMatrix * uInstancedModelViewMatrix * instanceMatrix * aVertexPosition;\n        vFragPos = (uInstancedModelViewMatrix * instanceMatrix * aVertexPosition).xy;\n        vInstanceColor = aInstanceColor;\n\n        int vertexIndex = int(aVertexPosition.x > 0.0 ? (aVertexPosition.y > 0.0 ? 0 : 2) : (aVertexPosition.y > 0.0 ? 1 : 3));\n        \n        if(vertexIndex == 0) {\n            vTexCoord = aInstanceTexCoord0;\n        } else if(vertexIndex == 1) {\n            vTexCoord = aInstanceTexCoord1;\n        } else if(vertexIndex == 2) {\n            vTexCoord = aInstanceTexCoord2;\n        } else {\n            vTexCoord = aInstanceTexCoord3;\n        }\n    } else {\n        gl_Position = uProjectionMatrix * uModelViewMatrix * aVertexPosition;\n        vFragPos = (uModelViewMatrix * aVertexPosition).xy;\n        vTexCoord = aTextureCoord;\n        vInstanceColor = vec4(1.0);\n    }\n  }\n";
-export const STANDARD_FRAGMENT_SHADER: "\n    #ifdef GL_ES\n    precision highp float;\n    #endif\n    uniform bool useTexture;\n    uniform vec4 uColor;\n    uniform sampler2D uSampler;\n    uniform float uOpacity;\n\n    uniform vec2 uLightPosition[4];\n    uniform vec3 uLightColor[4];\n    uniform float uLightIntensity[4];\n    uniform float uLightRadius[4];\n    uniform int uActiveLights;\n    \n    uniform vec2 uDirLightPosition[4];\n    uniform vec2 uDirLightDirection[4];\n    uniform vec3 uDirLightColor[4];\n    uniform float uDirLightIntensity[4];\n    uniform float uDirLightWidth[4];\n    uniform int uActiveDirLights;\n    \n    uniform vec3 uAmbientLightValues;\n    uniform bool uUseLighting;\n\n    varying vec2 vTexCoord;\n    varying vec2 vFragPos;\n    varying vec4 vInstanceColor;\n\n    void main() {\n        vec4 ambientLight = vec4(uAmbientLightValues.xyz, 1.0);\n\n        vec4 texColor;\n        if (useTexture) {\n            texColor = texture2D(uSampler, vTexCoord);\n            if (texColor.a < 0.01) discard;\n            texColor *= uColor;\n        } else {\n            texColor = uColor;\n        }\n\n        texColor *= vInstanceColor;\n        \n        vec3 lighting = ambientLight.rgb;\n        \n        for(int i = 0; i < 4; i++) {\n            if(i >= uActiveLights) break;\n            \n            float distance = length(uLightPosition[i] - vFragPos);\n            \n            if(distance < uLightRadius[i]) {\n                float attenuation = 1.0 - distance / uLightRadius[i];\n                \n                lighting += uLightColor[i] * attenuation * uLightIntensity[i];\n            }\n        }\n        \n        for(int i = 0; i < 4; i++) {\n            if(i >= uActiveDirLights) break;\n            \n            vec2 lightPos = uDirLightPosition[i];\n            vec2 lightDir = normalize(uDirLightDirection[i]);\n            vec2 toFrag = vFragPos - lightPos;\n            \n            float projection = dot(toFrag, lightDir);\n            if(projection < 0.0) continue;\n            \n            float perpDistance = abs(dot(toFrag, vec2(-lightDir.y, lightDir.x)));\n            \n            if(perpDistance > uDirLightWidth[i] * 0.5) continue;\n            \n            float widthFactor = 1.0 - (perpDistance / (uDirLightWidth[i] * 0.5));\n            \n            float distance = length(toFrag);\n            float maxDistance = 1000.0;\n            float distanceFactor = max(0.0, 1.0 - (distance / maxDistance));\n            \n            lighting += uDirLightColor[i] * uDirLightIntensity[i] * widthFactor * distanceFactor;\n        }\n        \n        vec4 outColor;\n        if (uUseLighting) {\n            outColor = vec4(texColor.rgb * lighting, texColor.a);\n        } else {\n            outColor = texColor;\n        }\n        outColor.a *= clamp(uOpacity, 0.0, 1.0);\n        gl_FragColor = outColor;\n    }\n";
+export const STANDARD_VERTEX_SHADER: "\n  attribute vec4 aVertexPosition;\n  attribute vec2 aTextureCoord;\n\n  attribute vec4 aInstanceMatrix0;\n  attribute vec4 aInstanceMatrix1;\n  attribute vec4 aInstanceMatrix2;\n  attribute vec4 aInstanceMatrix3;\n\n  attribute vec2 aInstanceTexCoord0;\n  attribute vec2 aInstanceTexCoord1;\n  attribute vec2 aInstanceTexCoord2;\n  attribute vec2 aInstanceTexCoord3;\n\n  attribute vec4 aInstanceColor;\n\n  uniform mat4 uModelViewMatrix;\n  uniform mat4 uInstancedModelViewMatrix;\n  uniform mat4 uProjectionMatrix;\n  uniform bool useInstances;\n\n  varying highp vec2 vTexCoord;\n  varying vec2 vFragPos;\n  varying vec4 vInstanceColor;\n\n  void main() {\n    mat4 instanceMatrix = mat4(\n      aInstanceMatrix0,\n      aInstanceMatrix1,\n      aInstanceMatrix2,\n      aInstanceMatrix3\n    );\n\n    if(useInstances) {\n        gl_Position = uProjectionMatrix * uInstancedModelViewMatrix * instanceMatrix * aVertexPosition;\n        vFragPos = (uInstancedModelViewMatrix * instanceMatrix * aVertexPosition).xy;\n        vInstanceColor = aInstanceColor;\n\n        int vertexIndex = int(aVertexPosition.x > 0.0 ? (aVertexPosition.y > 0.0 ? 0 : 2) : (aVertexPosition.y > 0.0 ? 1 : 3));\n\n        if(vertexIndex == 0) {\n            vTexCoord = aInstanceTexCoord0;\n        } else if(vertexIndex == 1) {\n            vTexCoord = aInstanceTexCoord1;\n        } else if(vertexIndex == 2) {\n            vTexCoord = aInstanceTexCoord2;\n        } else {\n            vTexCoord = aInstanceTexCoord3;\n        }\n    } else {\n        gl_Position = uProjectionMatrix * uModelViewMatrix * aVertexPosition;\n        vFragPos = (uModelViewMatrix * aVertexPosition).xy;\n        vTexCoord = aTextureCoord;\n        vInstanceColor = vec4(1.0);\n    }\n  }\n";
+export const STANDARD_FRAGMENT_SHADER: "\n    #ifdef GL_ES\n    precision highp float;\n    #endif\n    uniform bool useTexture;\n    uniform vec4 uColor;\n    uniform sampler2D uSampler;\n    uniform float uOpacity;\n\n    uniform vec2 uLightPosition[4];\n    uniform vec3 uLightColor[4];\n    uniform float uLightIntensity[4];\n    uniform float uLightRadius[4];\n    uniform int uActiveLights;\n\n    uniform vec2 uDirLightPosition[4];\n    uniform vec2 uDirLightDirection[4];\n    uniform vec3 uDirLightColor[4];\n    uniform float uDirLightIntensity[4];\n    uniform float uDirLightWidth[4];\n    uniform int uActiveDirLights;\n\n    uniform vec3 uAmbientLightValues;\n    uniform bool uUseLighting;\n\n    varying vec2 vTexCoord;\n    varying vec2 vFragPos;\n    varying vec4 vInstanceColor;\n\n    void main() {\n        vec4 ambientLight = vec4(uAmbientLightValues.xyz, 1.0);\n\n        vec4 texColor;\n        if (useTexture) {\n            texColor = texture2D(uSampler, vTexCoord);\n            if (texColor.a < 0.01) discard;\n            texColor *= uColor;\n        } else {\n            texColor = uColor;\n        }\n\n        texColor *= vInstanceColor;\n\n        vec3 lighting = ambientLight.rgb;\n\n        for(int i = 0; i < 4; i++) {\n            if(i >= uActiveLights) break;\n\n            float distance = length(uLightPosition[i] - vFragPos);\n\n            if(distance < uLightRadius[i]) {\n                float attenuation = 1.0 - distance / uLightRadius[i];\n\n                lighting += uLightColor[i] * attenuation * uLightIntensity[i];\n            }\n        }\n\n        for(int i = 0; i < 4; i++) {\n            if(i >= uActiveDirLights) break;\n\n            vec2 lightPos = uDirLightPosition[i];\n            vec2 lightDir = normalize(uDirLightDirection[i]);\n            vec2 toFrag = vFragPos - lightPos;\n\n            float projection = dot(toFrag, lightDir);\n            if(projection < 0.0) continue;\n\n            float perpDistance = abs(dot(toFrag, vec2(-lightDir.y, lightDir.x)));\n\n            if(perpDistance > uDirLightWidth[i] * 0.5) continue;\n\n            float widthFactor = 1.0 - (perpDistance / (uDirLightWidth[i] * 0.5));\n\n            float distance = length(toFrag);\n            float maxDistance = 1000.0;\n            float distanceFactor = max(0.0, 1.0 - (distance / maxDistance));\n\n            lighting += uDirLightColor[i] * uDirLightIntensity[i] * widthFactor * distanceFactor;\n        }\n\n        vec4 outColor;\n        if (uUseLighting) {\n            outColor = vec4(texColor.rgb * lighting, texColor.a);\n        } else {\n            outColor = texColor;\n        }\n        outColor.a *= clamp(uOpacity, 0.0, 1.0);\n        gl_FragColor = outColor;\n    }\n";

package/dist/types/src/Tilemap.d.ts

@@ -61,7 +61,7 @@ declare class Tilemap {
      * @method buildColliders
      * @description Generates static physics colliders from the current map. Solid
      * cells are merged greedily into horizontal runs, so a row of N tiles becomes
-     * one box collider instead of N — far fewer bodies for the physics engine.
+     * one box collider instead of N, far fewer bodies for the physics engine.
      * The bodies are tagged so collision callbacks resolve back to `ownerObject`
      * (defaults to the tilemap's GameObject). Call again after setMap to rebuild.
      *

package/dist/types/src/UI.d.ts

@@ -99,7 +99,7 @@ declare class UI {
     private _hitTest;
     /**
      * @method isOver
-     * @description Whether an interactive element is under the given page point —
+     * @description Whether an interactive element is under the given page point,
      * useful to suppress game clicks behind the UI.
      */
     isOver(clientX: any, clientY: any): boolean;

package/dist/types/src/components/Behaviour.d.ts

@@ -58,14 +58,14 @@ declare class Behaviour {
      * @description Called when the owner's body starts touching another. Requires
      * the Physics world to be ticked. Override in subclasses.
      * @param {Object} other - The other GameObject/Instance (or null)
-     * @param {Object} contact - The planck contact
+     * @param {Object} contact - The physics contact
      */
     onCollisionEnter(other: any, contact: any): void;
     /**
      * @method onCollisionExit
      * @description Called when the owner's body stops touching another.
      * @param {Object} other - The other GameObject/Instance (or null)
-     * @param {Object} contact - The planck contact
+     * @param {Object} contact - The physics contact
      */
     onCollisionExit(other: any, contact: any): void;
 }

package/dist/types/src/components/Collider.d.ts

@@ -18,12 +18,18 @@ declare class Collider {
      * @method syncDebugShape
      * @description Mirrors a transform onto the debug shape, but only if one has
      * already been created. Never forces lazy creation.
+     *
+     * The rigidbody's spawn offset is added back, because the collider sits at
+     * `transform + offset` while the transform tracks the renderable. Without it
+     * the debug shape would drift away from the collider it is supposed to be
+     * showing on any body built with an offset.
+     *
      * @param {Transform} transform - The source transform
      */
     syncDebugShape(transform: Transform): void;
     /**
      * @method setFilter
-     * @description Sets the raw planck collision filter on this collider's
+     * @description Sets the raw collision filter on this collider's
      * fixture. Two fixtures collide only when each one's category bit is present
      * in the other's mask. Subclasses must have created `this.collider`
      * (the fixture) first.

package/dist/types/src/components/GameObject.d.ts

@@ -26,7 +26,7 @@ declare class GameObject {
     setLayer(layer: number): GameObject;
     /**
      * @method setScreenSpace
-     * @description When true, the object ignores the camera (fixed on screen) —
+     * @description When true, the object ignores the camera (fixed on screen),
      * useful for HUD/UI. Position is then in pixels from the viewport center.
      * Note: not supported for InstancedTexture-based objects.
      * @param {boolean} value
@@ -114,7 +114,7 @@ declare class GameObject {
      * @description Permanently tears the object down: disposes every Drawable's
      * GPU resources, destroys physics bodies, and runs Behaviour.onDestroy().
      * Use it (or Scene.remove(obj, { dispose: true })) when an object will not
-     * be re-added — plain Scene.remove() keeps GPU resources alive for re-use.
+     * be re-added: plain Scene.remove() keeps GPU resources alive for re-use.
      * Safe to call twice.
      */
     destroy(): void;

package/dist/types/src/components/PolygonCollider.d.ts

@@ -0,0 +1,33 @@
+export default PolygonCollider;
+/**
+ * @class PolygonCollider
+ * @extends Collider
+ * @description A convex-polygon fixture, for collision shapes a box or
+ * circle can't approximate, like ramps, wedges, or arbitrary tile outlines (see
+ * {@link ForgeLevel}). Points outside the convex hull of what you pass are
+ * dropped automatically; a concave shape needs more than one collider.
+ * @param {Rigidbody} rigidbody - The rigidbody to attach the collider to
+ * @param {Array<{x:number,y:number}>} points - Local-space points, in
+ *   physics units, in any order
+ * @param {number} density - The density of the collider
+ * @param {number} friction - The friction of the collider
+ * @param {number} restitution - The restitution of the collider
+ * @param {boolean} [isSensor=false] - Whether the collider is a sensor
+ * @param {GameObject} [parentObject=null] - The parent object of the collider
+ * @param {Object} [filter=null] - Collision filter spec, see {@link Collider#setFilter}
+ */
+declare class PolygonCollider extends Collider {
+    constructor(rigidbody: any, points: any, density: any, friction: any, restitution: any, isSensor?: boolean, parentObject?: any, filter?: any);
+    collider: any;
+    points: any;
+    /**
+     * @method getPoints
+     * @description Returns the local-space points this collider was built from
+     * @returns {Array<{x:number,y:number}>}
+     */
+    getPoints(): Array<{
+        x: number;
+        y: number;
+    }>;
+}
+import Collider from "./Collider.js";