@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/physics/vehicle.js

@@ -0,0 +1,335 @@
+import { Vector3 } from '@zephyr3d/base';
+import { PhysicsPart } from './part.js';
+
+/**
+ * Makes its node a car, truck or other wheeled vehicle, driven by
+ * {@link Vehicle.throttle}, {@link Vehicle.brake} and {@link Vehicle.steering}.
+ *
+ * @remarks
+ * The node needs a dynamic {@link RigidBody}, and colliders for the body. The
+ * wheels are the {@link NodePhysics.wheel} of nodes below it, with no other rigid
+ * body in between; each wheel node is placed where the wheel's centre is with
+ * the suspension at rest. While simulating, the wheel nodes are moved up and
+ * down with the suspension, turned with the steering and rolled with the
+ * vehicle's motion.
+ *
+ * Up is the node's +Y; the front is {@link Vehicle.forward}. Wheels are rays
+ * cast down from the body, as in Bullet's ray cast vehicle:
+ * they find the ground, but do not collide - the body's colliders do.
+ *
+ * Inputs stay in effect until changed, and are applied every simulation step.
+ *
+ * @public
+ */ class Vehicle extends PhysicsPart {
+    _maxEngineForce;
+    _maxBrakeForce;
+    _maxHandbrakeForce;
+    _maxSteerAngle;
+    _forward;
+    _layer;
+    _throttle;
+    _brake;
+    _handbrake;
+    _steering;
+    _error;
+    constructor(){
+        super();
+        this._maxEngineForce = 4000;
+        this._maxBrakeForce = 3000;
+        this._maxHandbrakeForce = 6000;
+        this._maxSteerAngle = 30;
+        this._forward = '+z';
+        this._layer = 0;
+        this._throttle = 0;
+        this._brake = 0;
+        this._handbrake = false;
+        this._steering = 0;
+        this._error = '';
+    }
+    /** Total driving force at full throttle, in newtons, shared out by {@link Wheel.drive}. Default 4000. */ get maxEngineForce() {
+        return this._maxEngineForce;
+    }
+    set maxEngineForce(value) {
+        this._maxEngineForce = Math.max(0, value);
+    }
+    /** Braking force of a wheel at full brake, in newtons, scaled by {@link Wheel.brake}. Default 3000. */ get maxBrakeForce() {
+        return this._maxBrakeForce;
+    }
+    set maxBrakeForce(value) {
+        this._maxBrakeForce = Math.max(0, value);
+    }
+    /** Braking force of a wheel with the handbrake on, in newtons, scaled by {@link Wheel.handbrake}. Default 6000. */ get maxHandbrakeForce() {
+        return this._maxHandbrakeForce;
+    }
+    set maxHandbrakeForce(value) {
+        this._maxHandbrakeForce = Math.max(0, value);
+    }
+    /** Steering angle at full lock, in degrees, scaled by {@link Wheel.steer}. Default 30. */ get maxSteerAngle() {
+        return this._maxSteerAngle;
+    }
+    set maxSteerAngle(value) {
+        this._maxSteerAngle = value;
+    }
+    /** Which way the front faces in the node's space. Default `'+z'`. */ get forward() {
+        return this._forward;
+    }
+    set forward(value) {
+        if (value !== this._forward) {
+            this._forward = value;
+            this._rebuild();
+        }
+    }
+    /** Collision layer of the wheels: they find ground on the layers this one collides with. Default 0. */ get layer() {
+        return this._layer;
+    }
+    set layer(value) {
+        this._layer = Math.min(15, Math.max(0, Math.floor(value)));
+    }
+    /** Accelerator, -1 to 1; below 0 drives backwards. Overrides the brake on driven wheels. */ get throttle() {
+        return this._throttle;
+    }
+    set throttle(value) {
+        this._throttle = Math.min(1, Math.max(-1, value));
+    }
+    /** Brake pedal, 0 to 1. */ get brake() {
+        return this._brake;
+    }
+    set brake(value) {
+        this._brake = Math.min(1, Math.max(0, value));
+    }
+    /** Whether the handbrake is on. */ get handbrake() {
+        return this._handbrake;
+    }
+    set handbrake(value) {
+        this._handbrake = !!value;
+    }
+    /** Steering wheel, -1 to 1; above 0 turns left. */ get steering() {
+        return this._steering;
+    }
+    set steering(value) {
+        this._steering = Math.min(1, Math.max(-1, value));
+    }
+    /** Speed along the front direction in m/s; negative when going backwards. */ get speed() {
+        return this.world?._vehicleSpeed(this) ?? 0;
+    }
+    /** The wheels, in scene order, while the vehicle is in a simulation. */ get wheels() {
+        return this.world?._vehicleWheels(this) ?? [];
+    }
+    /** Why the vehicle could not be built, or an empty string. */ get error() {
+        return this._error;
+    }
+    /** The front direction in node space. */ _forwardVector(out = new Vector3()) {
+        switch(this._forward){
+            case '-z':
+                return out.setXYZ(0, 0, -1);
+            case '+x':
+                return out.setXYZ(1, 0, 0);
+            case '-x':
+                return out.setXYZ(-1, 0, 0);
+            default:
+                return out.setXYZ(0, 0, 1);
+        }
+    }
+    /** Whether any input asks the vehicle to move. */ _hasInput() {
+        return this._throttle !== 0 || this._brake !== 0 || this._handbrake || this._steering !== 0;
+    }
+    _setError(error) {
+        this._error = error;
+    }
+    _rebuild() {
+        this.world?._markVehiclesDirty();
+    }
+    _join(world) {
+        world._registerVehicle(this);
+    }
+    _leave(world) {
+        world._unregisterVehicle(this);
+    }
+}
+/**
+ * A wheel of the {@link Vehicle} above its node.
+ *
+ * @remarks
+ * Place the node where the wheel's centre is with the suspension at rest. The
+ * suspension runs along the vehicle's down direction, the axle along its
+ * sideways direction. While simulating, the node's local position and rotation
+ * are set from the suspension, steering and roll; they go back to where they
+ * were when the vehicle leaves the simulation.
+ *
+ * Suspension stiffness and damping are per kilogram of the vehicle, so they
+ * feel the same on a light car and a heavy truck: with four wheels resting, the
+ * suspension sinks by 9.81 / (4 × stiffness) metres.
+ *
+ * @public
+ */ class Wheel extends PhysicsPart {
+    _radius;
+    _suspensionRestLength;
+    _suspensionStiffness;
+    _suspensionCompression;
+    _suspensionRelaxation;
+    _maxSuspensionTravel;
+    _maxSuspensionForce;
+    _frictionSlip;
+    _sideFriction;
+    _steer;
+    _drive;
+    _brake;
+    _handbrake;
+    /** Added to what the vehicle's inputs give this wheel. */ engineForce;
+    brakeForce;
+    steerAngle;
+    /** State after the last simulation step. */ _state;
+    /** The node's local transform before the vehicle took it over. */ _rest;
+    /** The node the vehicle last wrote to, to give the rest pose back to. */ _restNode;
+    _error;
+    constructor(){
+        super();
+        this._radius = 0.4;
+        this._suspensionRestLength = 0.3;
+        this._suspensionStiffness = 30;
+        this._suspensionCompression = 2.2;
+        this._suspensionRelaxation = 3.3;
+        this._maxSuspensionTravel = 0.3;
+        this._maxSuspensionForce = 1e6;
+        this._frictionSlip = 1.5;
+        this._sideFriction = 1;
+        this._steer = 0;
+        this._drive = 0;
+        this._brake = 1;
+        this._handbrake = 0;
+        this.engineForce = 0;
+        this.brakeForce = 0;
+        this.steerAngle = 0;
+        this._state = {
+            suspensionLength: 0,
+            rotation: 0,
+            steering: 0,
+            inContact: false,
+            contactPoint: new Vector3(),
+            contactNormal: new Vector3(),
+            groundKey: -1,
+            suspensionForce: 0
+        };
+        this._rest = null;
+        this._restNode = null;
+        this._error = '';
+    }
+    /** Wheel radius in metres. Default 0.4. */ get radius() {
+        return this._radius;
+    }
+    set radius(value) {
+        this._set('_radius', Math.max(0.01, value));
+    }
+    /** Suspension length at rest, from where it is attached to the wheel's centre, in metres. Default 0.3. */ get suspensionRestLength() {
+        return this._suspensionRestLength;
+    }
+    set suspensionRestLength(value) {
+        this._set('_suspensionRestLength', Math.max(0, value));
+    }
+    /** Spring strength per kilogram of vehicle; higher is firmer and sinks less. Default 30. */ get suspensionStiffness() {
+        return this._suspensionStiffness;
+    }
+    set suspensionStiffness(value) {
+        this._set('_suspensionStiffness', Math.max(0, value));
+    }
+    /** Damping while the suspension compresses, per kilogram of vehicle. Default 2.2. */ get suspensionCompression() {
+        return this._suspensionCompression;
+    }
+    set suspensionCompression(value) {
+        this._set('_suspensionCompression', Math.max(0, value));
+    }
+    /** Damping while the suspension extends, per kilogram of vehicle. Default 3.3. */ get suspensionRelaxation() {
+        return this._suspensionRelaxation;
+    }
+    set suspensionRelaxation(value) {
+        this._set('_suspensionRelaxation', Math.max(0, value));
+    }
+    /** How far the suspension compresses or extends from rest, in metres. Default 0.3. */ get maxSuspensionTravel() {
+        return this._maxSuspensionTravel;
+    }
+    set maxSuspensionTravel(value) {
+        this._set('_maxSuspensionTravel', Math.max(0, value));
+    }
+    /** Most force the suspension pushes with, in newtons. Default 1000000. */ get maxSuspensionForce() {
+        return this._maxSuspensionForce;
+    }
+    set maxSuspensionForce(value) {
+        this._set('_maxSuspensionForce', Math.max(0, value));
+    }
+    /** Grip: the most sideways force per unit of load, like a friction coefficient. Default 1.5. */ get frictionSlip() {
+        return this._frictionSlip;
+    }
+    set frictionSlip(value) {
+        this._set('_frictionSlip', Math.max(0, value));
+    }
+    /** Scales the sideways grip; lower lets the wheel slide out. Default 1. */ get sideFriction() {
+        return this._sideFriction;
+    }
+    set sideFriction(value) {
+        this._set('_sideFriction', Math.max(0, value));
+    }
+    /** Share of the steering: 1 turns with the wheel, -1 against it (rear steer), 0 not at all. Default 0. */ get steer() {
+        return this._steer;
+    }
+    set steer(value) {
+        this._steer = value;
+    }
+    /** Share of the engine force, e.g. 0.5 for each front wheel of a front wheel drive car. Default 0. */ get drive() {
+        return this._drive;
+    }
+    set drive(value) {
+        this._drive = value;
+    }
+    /** Share of the brake. Default 1. */ get brake() {
+        return this._brake;
+    }
+    set brake(value) {
+        this._brake = Math.max(0, value);
+    }
+    /** Share of the handbrake, usually 1 on rear wheels. Default 0. */ get handbrake() {
+        return this._handbrake;
+    }
+    set handbrake(value) {
+        this._handbrake = Math.max(0, value);
+    }
+    /** Whether the wheel touched ground at the last step. */ get inContact() {
+        return this._state.inContact;
+    }
+    /** Where the wheel touches the ground, world space; valid when {@link Wheel.inContact}. */ get contactPoint() {
+        return this._state.contactPoint;
+    }
+    /** Direction of the ground under the wheel, world space; valid when {@link Wheel.inContact}. */ get contactNormal() {
+        return this._state.contactNormal;
+    }
+    /** The node of the ground under the wheel, or null. */ get groundNode() {
+        return this.world?._colliderNodeByKey(this._state.groundKey) ?? null;
+    }
+    /** Current suspension length in metres. */ get suspensionLength() {
+        return this._state.suspensionLength;
+    }
+    /** Force the suspension pushes with, in newtons. */ get suspensionForce() {
+        return this._state.suspensionForce;
+    }
+    /** Why the wheel is not part of a vehicle, or an empty string. */ get error() {
+        return this._error;
+    }
+    _setError(error) {
+        this._error = error;
+    }
+    _set(key, value) {
+        const self = this;
+        if (self[key] !== value) {
+            self[key] = value;
+            this.world?._markVehiclesDirty();
+        }
+    }
+    _join(world) {
+        world._registerWheel(this);
+    }
+    _leave(world) {
+        world._unregisterWheel(this);
+    }
+}
+
+export { Vehicle, Wheel };
+//# sourceMappingURL=vehicle.js.map

package/dist/physics/vehicle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vehicle.js","sources":["../../src/physics/vehicle.ts"],"sourcesContent":["import type { Quaternion } from '@zephyr3d/base';\r\nimport { Vector3 } from '@zephyr3d/base';\r\nimport type { SceneNode } from '../scene/scene_node';\r\nimport { PhysicsPart } from './part';\r\nimport type { PhysicsWorld } from './world';\r\n\r\n/**\r\n * Which way the front of a {@link Vehicle} faces, in its node's space.\r\n *\r\n * @public\r\n */\r\nexport type VehicleForward = '+z' | '-z' | '+x' | '-x';\r\n\r\n/**\r\n * Makes its node a car, truck or other wheeled vehicle, driven by\r\n * {@link Vehicle.throttle}, {@link Vehicle.brake} and {@link Vehicle.steering}.\r\n *\r\n * @remarks\r\n * The node needs a dynamic {@link RigidBody}, and colliders for the body. The\r\n * wheels are the {@link NodePhysics.wheel} of nodes below it, with no other rigid\r\n * body in between; each wheel node is placed where the wheel's centre is with\r\n * the suspension at rest. While simulating, the wheel nodes are moved up and\r\n * down with the suspension, turned with the steering and rolled with the\r\n * vehicle's motion.\r\n *\r\n * Up is the node's +Y; the front is {@link Vehicle.forward}. Wheels are rays\r\n * cast down from the body, as in Bullet's ray cast vehicle:\r\n * they find the ground, but do not collide - the body's colliders do.\r\n *\r\n * Inputs stay in effect until changed, and are applied every simulation step.\r\n *\r\n * @public\r\n */\r\nexport class Vehicle extends PhysicsPart {\r\n  private _maxEngineForce: number;\r\n  private _maxBrakeForce: number;\r\n  private _maxHandbrakeForce: number;\r\n  private _maxSteerAngle: number;\r\n  private _forward: VehicleForward;\r\n  private _layer: number;\r\n  private _throttle: number;\r\n  private _brake: number;\r\n  private _handbrake: boolean;\r\n  private _steering: number;\r\n  private _error: string;\r\n\r\n  constructor() {\r\n    super();\r\n    this._maxEngineForce = 4000;\r\n    this._maxBrakeForce = 3000;\r\n    this._maxHandbrakeForce = 6000;\r\n    this._maxSteerAngle = 30;\r\n    this._forward = '+z';\r\n    this._layer = 0;\r\n    this._throttle = 0;\r\n    this._brake = 0;\r\n    this._handbrake = false;\r\n    this._steering = 0;\r\n    this._error = '';\r\n  }\r\n\r\n  /** Total driving force at full throttle, in newtons, shared out by {@link Wheel.drive}. Default 4000. */\r\n  get maxEngineForce() {\r\n    return this._maxEngineForce;\r\n  }\r\n  set maxEngineForce(value: number) {\r\n    this._maxEngineForce = Math.max(0, value);\r\n  }\r\n  /** Braking force of a wheel at full brake, in newtons, scaled by {@link Wheel.brake}. Default 3000. */\r\n  get maxBrakeForce() {\r\n    return this._maxBrakeForce;\r\n  }\r\n  set maxBrakeForce(value: number) {\r\n    this._maxBrakeForce = Math.max(0, value);\r\n  }\r\n  /** Braking force of a wheel with the handbrake on, in newtons, scaled by {@link Wheel.handbrake}. Default 6000. */\r\n  get maxHandbrakeForce() {\r\n    return this._maxHandbrakeForce;\r\n  }\r\n  set maxHandbrakeForce(value: number) {\r\n    this._maxHandbrakeForce = Math.max(0, value);\r\n  }\r\n  /** Steering angle at full lock, in degrees, scaled by {@link Wheel.steer}. Default 30. */\r\n  get maxSteerAngle() {\r\n    return this._maxSteerAngle;\r\n  }\r\n  set maxSteerAngle(value: number) {\r\n    this._maxSteerAngle = value;\r\n  }\r\n  /** Which way the front faces in the node's space. Default `'+z'`. */\r\n  get forward() {\r\n    return this._forward;\r\n  }\r\n  set forward(value: VehicleForward) {\r\n    if (value !== this._forward) {\r\n      this._forward = value;\r\n      this._rebuild();\r\n    }\r\n  }\r\n  /** Collision layer of the wheels: they find ground on the layers this one collides with. Default 0. */\r\n  get layer() {\r\n    return this._layer;\r\n  }\r\n  set layer(value: number) {\r\n    this._layer = Math.min(15, Math.max(0, Math.floor(value)));\r\n  }\r\n\r\n  /** Accelerator, -1 to 1; below 0 drives backwards. Overrides the brake on driven wheels. */\r\n  get throttle() {\r\n    return this._throttle;\r\n  }\r\n  set throttle(value: number) {\r\n    this._throttle = Math.min(1, Math.max(-1, value));\r\n  }\r\n  /** Brake pedal, 0 to 1. */\r\n  get brake() {\r\n    return this._brake;\r\n  }\r\n  set brake(value: number) {\r\n    this._brake = Math.min(1, Math.max(0, value));\r\n  }\r\n  /** Whether the handbrake is on. */\r\n  get handbrake() {\r\n    return this._handbrake;\r\n  }\r\n  set handbrake(value: boolean) {\r\n    this._handbrake = !!value;\r\n  }\r\n  /** Steering wheel, -1 to 1; above 0 turns left. */\r\n  get steering() {\r\n    return this._steering;\r\n  }\r\n  set steering(value: number) {\r\n    this._steering = Math.min(1, Math.max(-1, value));\r\n  }\r\n\r\n  /** Speed along the front direction in m/s; negative when going backwards. */\r\n  get speed() {\r\n    return this.world?._vehicleSpeed(this) ?? 0;\r\n  }\r\n  /** The wheels, in scene order, while the vehicle is in a simulation. */\r\n  get wheels(): readonly Wheel[] {\r\n    return this.world?._vehicleWheels(this) ?? [];\r\n  }\r\n  /** Why the vehicle could not be built, or an empty string. */\r\n  get error() {\r\n    return this._error;\r\n  }\r\n\r\n  /** The front direction in node space. */\r\n  _forwardVector(out = new Vector3()) {\r\n    switch (this._forward) {\r\n      case '-z':\r\n        return out.setXYZ(0, 0, -1);\r\n      case '+x':\r\n        return out.setXYZ(1, 0, 0);\r\n      case '-x':\r\n        return out.setXYZ(-1, 0, 0);\r\n      default:\r\n        return out.setXYZ(0, 0, 1);\r\n    }\r\n  }\r\n  /** Whether any input asks the vehicle to move. */\r\n  _hasInput() {\r\n    return this._throttle !== 0 || this._brake !== 0 || this._handbrake || this._steering !== 0;\r\n  }\r\n  _setError(error: string) {\r\n    this._error = error;\r\n  }\r\n  private _rebuild() {\r\n    this.world?._markVehiclesDirty();\r\n  }\r\n  protected _join(world: PhysicsWorld) {\r\n    world._registerVehicle(this);\r\n  }\r\n  protected _leave(world: PhysicsWorld) {\r\n    world._unregisterVehicle(this);\r\n  }\r\n}\r\n\r\n/**\r\n * A wheel of the {@link Vehicle} above its node.\r\n *\r\n * @remarks\r\n * Place the node where the wheel's centre is with the suspension at rest. The\r\n * suspension runs along the vehicle's down direction, the axle along its\r\n * sideways direction. While simulating, the node's local position and rotation\r\n * are set from the suspension, steering and roll; they go back to where they\r\n * were when the vehicle leaves the simulation.\r\n *\r\n * Suspension stiffness and damping are per kilogram of the vehicle, so they\r\n * feel the same on a light car and a heavy truck: with four wheels resting, the\r\n * suspension sinks by 9.81 / (4 × stiffness) metres.\r\n *\r\n * @public\r\n */\r\nexport class Wheel extends PhysicsPart {\r\n  private _radius: number;\r\n  private _suspensionRestLength: number;\r\n  private _suspensionStiffness: number;\r\n  private _suspensionCompression: number;\r\n  private _suspensionRelaxation: number;\r\n  private _maxSuspensionTravel: number;\r\n  private _maxSuspensionForce: number;\r\n  private _frictionSlip: number;\r\n  private _sideFriction: number;\r\n  private _steer: number;\r\n  private _drive: number;\r\n  private _brake: number;\r\n  private _handbrake: number;\r\n  /** Added to what the vehicle's inputs give this wheel. */\r\n  engineForce: number;\r\n  brakeForce: number;\r\n  steerAngle: number;\r\n  /** State after the last simulation step. */\r\n  readonly _state: {\r\n    suspensionLength: number;\r\n    rotation: number;\r\n    steering: number;\r\n    inContact: boolean;\r\n    contactPoint: Vector3;\r\n    contactNormal: Vector3;\r\n    groundKey: number;\r\n    suspensionForce: number;\r\n  };\r\n  /** The node's local transform before the vehicle took it over. */\r\n  _rest: { position: Vector3; rotation: Quaternion } | null;\r\n  /** The node the vehicle last wrote to, to give the rest pose back to. */\r\n  _restNode: SceneNode | null;\r\n  private _error: string;\r\n\r\n  constructor() {\r\n    super();\r\n    this._radius = 0.4;\r\n    this._suspensionRestLength = 0.3;\r\n    this._suspensionStiffness = 30;\r\n    this._suspensionCompression = 2.2;\r\n    this._suspensionRelaxation = 3.3;\r\n    this._maxSuspensionTravel = 0.3;\r\n    this._maxSuspensionForce = 1e6;\r\n    this._frictionSlip = 1.5;\r\n    this._sideFriction = 1;\r\n    this._steer = 0;\r\n    this._drive = 0;\r\n    this._brake = 1;\r\n    this._handbrake = 0;\r\n    this.engineForce = 0;\r\n    this.brakeForce = 0;\r\n    this.steerAngle = 0;\r\n    this._state = {\r\n      suspensionLength: 0,\r\n      rotation: 0,\r\n      steering: 0,\r\n      inContact: false,\r\n      contactPoint: new Vector3(),\r\n      contactNormal: new Vector3(),\r\n      groundKey: -1,\r\n      suspensionForce: 0\r\n    };\r\n    this._rest = null;\r\n    this._restNode = null;\r\n    this._error = '';\r\n  }\r\n\r\n  /** Wheel radius in metres. Default 0.4. */\r\n  get radius() {\r\n    return this._radius;\r\n  }\r\n  set radius(value: number) {\r\n    this._set('_radius', Math.max(0.01, value));\r\n  }\r\n  /** Suspension length at rest, from where it is attached to the wheel's centre, in metres. Default 0.3. */\r\n  get suspensionRestLength() {\r\n    return this._suspensionRestLength;\r\n  }\r\n  set suspensionRestLength(value: number) {\r\n    this._set('_suspensionRestLength', Math.max(0, value));\r\n  }\r\n  /** Spring strength per kilogram of vehicle; higher is firmer and sinks less. Default 30. */\r\n  get suspensionStiffness() {\r\n    return this._suspensionStiffness;\r\n  }\r\n  set suspensionStiffness(value: number) {\r\n    this._set('_suspensionStiffness', Math.max(0, value));\r\n  }\r\n  /** Damping while the suspension compresses, per kilogram of vehicle. Default 2.2. */\r\n  get suspensionCompression() {\r\n    return this._suspensionCompression;\r\n  }\r\n  set suspensionCompression(value: number) {\r\n    this._set('_suspensionCompression', Math.max(0, value));\r\n  }\r\n  /** Damping while the suspension extends, per kilogram of vehicle. Default 3.3. */\r\n  get suspensionRelaxation() {\r\n    return this._suspensionRelaxation;\r\n  }\r\n  set suspensionRelaxation(value: number) {\r\n    this._set('_suspensionRelaxation', Math.max(0, value));\r\n  }\r\n  /** How far the suspension compresses or extends from rest, in metres. Default 0.3. */\r\n  get maxSuspensionTravel() {\r\n    return this._maxSuspensionTravel;\r\n  }\r\n  set maxSuspensionTravel(value: number) {\r\n    this._set('_maxSuspensionTravel', Math.max(0, value));\r\n  }\r\n  /** Most force the suspension pushes with, in newtons. Default 1000000. */\r\n  get maxSuspensionForce() {\r\n    return this._maxSuspensionForce;\r\n  }\r\n  set maxSuspensionForce(value: number) {\r\n    this._set('_maxSuspensionForce', Math.max(0, value));\r\n  }\r\n  /** Grip: the most sideways force per unit of load, like a friction coefficient. Default 1.5. */\r\n  get frictionSlip() {\r\n    return this._frictionSlip;\r\n  }\r\n  set frictionSlip(value: number) {\r\n    this._set('_frictionSlip', Math.max(0, value));\r\n  }\r\n  /** Scales the sideways grip; lower lets the wheel slide out. Default 1. */\r\n  get sideFriction() {\r\n    return this._sideFriction;\r\n  }\r\n  set sideFriction(value: number) {\r\n    this._set('_sideFriction', Math.max(0, value));\r\n  }\r\n  /** Share of the steering: 1 turns with the wheel, -1 against it (rear steer), 0 not at all. Default 0. */\r\n  get steer() {\r\n    return this._steer;\r\n  }\r\n  set steer(value: number) {\r\n    this._steer = value;\r\n  }\r\n  /** Share of the engine force, e.g. 0.5 for each front wheel of a front wheel drive car. Default 0. */\r\n  get drive() {\r\n    return this._drive;\r\n  }\r\n  set drive(value: number) {\r\n    this._drive = value;\r\n  }\r\n  /** Share of the brake. Default 1. */\r\n  get brake() {\r\n    return this._brake;\r\n  }\r\n  set brake(value: number) {\r\n    this._brake = Math.max(0, value);\r\n  }\r\n  /** Share of the handbrake, usually 1 on rear wheels. Default 0. */\r\n  get handbrake() {\r\n    return this._handbrake;\r\n  }\r\n  set handbrake(value: number) {\r\n    this._handbrake = Math.max(0, value);\r\n  }\r\n\r\n  /** Whether the wheel touched ground at the last step. */\r\n  get inContact() {\r\n    return this._state.inContact;\r\n  }\r\n  /** Where the wheel touches the ground, world space; valid when {@link Wheel.inContact}. */\r\n  get contactPoint(): Vector3 {\r\n    return this._state.contactPoint;\r\n  }\r\n  /** Direction of the ground under the wheel, world space; valid when {@link Wheel.inContact}. */\r\n  get contactNormal(): Vector3 {\r\n    return this._state.contactNormal;\r\n  }\r\n  /** The node of the ground under the wheel, or null. */\r\n  get groundNode(): SceneNode | null {\r\n    return this.world?._colliderNodeByKey(this._state.groundKey) ?? null;\r\n  }\r\n  /** Current suspension length in metres. */\r\n  get suspensionLength() {\r\n    return this._state.suspensionLength;\r\n  }\r\n  /** Force the suspension pushes with, in newtons. */\r\n  get suspensionForce() {\r\n    return this._state.suspensionForce;\r\n  }\r\n  /** Why the wheel is not part of a vehicle, or an empty string. */\r\n  get error() {\r\n    return this._error;\r\n  }\r\n\r\n  _setError(error: string) {\r\n    this._error = error;\r\n  }\r\n  private _set(key: string, value: number) {\r\n    const self = this as unknown as Record<string, number>;\r\n    if (self[key] !== value) {\r\n      self[key] = value;\r\n      this.world?._markVehiclesDirty();\r\n    }\r\n  }\r\n  protected _join(world: PhysicsWorld) {\r\n    world._registerWheel(this);\r\n  }\r\n  protected _leave(world: PhysicsWorld) {\r\n    world._unregisterWheel(this);\r\n  }\r\n}\r\n"],"names":["Vehicle","PhysicsPart","_maxEngineForce","_maxBrakeForce","_maxHandbrakeForce","_maxSteerAngle","_forward","_layer","_throttle","_brake","_handbrake","_steering","_error","maxEngineForce","value","Math","max","maxBrakeForce","maxHandbrakeForce","maxSteerAngle","forward","_rebuild","layer","min","floor","throttle","brake","handbrake","steering","speed","world","_vehicleSpeed","wheels","_vehicleWheels","error","_forwardVector","out","Vector3","setXYZ","_hasInput","_setError","_markVehiclesDirty","_join","_registerVehicle","_leave","_unregisterVehicle","Wheel","_radius","_suspensionRestLength","_suspensionStiffness","_suspensionCompression","_suspensionRelaxation","_maxSuspensionTravel","_maxSuspensionForce","_frictionSlip","_sideFriction","_steer","_drive","engineForce","brakeForce","steerAngle","_rest","_restNode","_state","suspensionLength","rotation","inContact","contactPoint","contactNormal","groundKey","suspensionForce","radius","_set","suspensionRestLength","suspensionStiffness","suspensionCompression","suspensionRelaxation","maxSuspensionTravel","maxSuspensionForce","frictionSlip","sideFriction","steer","drive","groundNode","_colliderNodeByKey","key","self","_registerWheel","_unregisterWheel"],"mappings":"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"}

package/dist/physics/world.js

@@ -0,0 +1,25 @@
+let worldFactory = null;
+/**
+ * Sets how scenes get their physics world.
+ *
+ * @remarks
+ * Called by a physics implementation when it is loaded (`initPhysics` of
+ * `@zephyr3d/physics`), not usually by applications. Scenes create their world
+ * from it the first time they need one; scenes that already have a world keep
+ * it. Without a factory, scenes have no world: physics data on nodes is kept,
+ * saved and loaded, but not simulated.
+ *
+ * @public
+ */ function setPhysicsWorldFactory(factory) {
+    worldFactory = factory;
+}
+/**
+ * The factory set with {@link setPhysicsWorldFactory}, or null.
+ *
+ * @public
+ */ function getPhysicsWorldFactory() {
+    return worldFactory;
+}
+
+export { getPhysicsWorldFactory, setPhysicsWorldFactory };
+//# sourceMappingURL=world.js.map

package/dist/physics/world.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.js","sources":["../../src/physics/world.ts"],"sourcesContent":["import type { IEventTarget, Nullable, Quaternion, Vector3 } from '@zephyr3d/base';\r\nimport type { Scene } from '../scene/scene';\r\nimport type { SceneNode } from '../scene/scene_node';\r\nimport type {\r\n  CharacterMoveResult,\r\n  ColliderOutline,\r\n  PhysicsQueryHit,\r\n  PhysicsQueryOptions,\r\n  PhysicsShape,\r\n  PhysicsWorldEventMap\r\n} from './types';\r\nimport type { RigidBody } from './rigid_body';\r\nimport type { Collider } from './collider';\r\nimport type { Joint } from './joint';\r\nimport type { CharacterController } from './character';\r\nimport type { Vehicle, Wheel } from './vehicle';\r\n\r\n/**\r\n * A simulated rigid body, as a physics implementation exposes it to\r\n * {@link RigidBody}. Application code uses {@link RigidBody} instead.\r\n *\r\n * @public\r\n */\r\nexport interface PhysicsBodyHandle {\r\n  setMass(mass: number): void;\r\n  setDamping(linear: number, angular: number): void;\r\n  setGravityScale(scale: number): void;\r\n  setCcd(enabled: boolean): void;\r\n  setEnabledAxes(translation: [boolean, boolean, boolean], rotation: [boolean, boolean, boolean]): void;\r\n  getPosition(out: Vector3): Vector3;\r\n  getRotation(out: Quaternion): Quaternion;\r\n  getLinearVelocity(out: Vector3): Vector3;\r\n  setLinearVelocity(v: Vector3): void;\r\n  getAngularVelocity(out: Vector3): Vector3;\r\n  setAngularVelocity(v: Vector3): void;\r\n  /** Sets the force and torque applied during the following steps, replacing earlier ones. */\r\n  setForce(force: Vector3, torque: Vector3): void;\r\n  applyImpulse(impulse: Vector3, torqueImpulse: Vector3): void;\r\n  isSleeping(): boolean;\r\n  wakeUp(): void;\r\n}\r\n\r\n/**\r\n * A simulated joint, as a physics implementation exposes it to {@link Joint}.\r\n *\r\n * @public\r\n */\r\nexport interface PhysicsJointHandle {\r\n  setContactsEnabled(enabled: boolean): void;\r\n}\r\n\r\n/**\r\n * The physics simulation of one scene: steps the physics data on its nodes\r\n * ({@link SceneNode.physics}) and answers queries.\r\n *\r\n * @remarks\r\n * Scenes get one from the physics implementation an application loads, as\r\n * `scene.physicsWorld`; see {@link setPhysicsWorldFactory}. The members whose\r\n * names start with an underscore are how physics data talks to the\r\n * implementation; application code does not call them.\r\n *\r\n * @public\r\n */\r\nexport interface PhysicsWorld extends IEventTarget<PhysicsWorldEventMap> {\r\n  /** The scene this world simulates. */\r\n  readonly scene: Scene;\r\n  /** Whether the world has been disposed. */\r\n  readonly disposed: boolean;\r\n  /** Gravity in m/s². Default (0, -9.81, 0). */\r\n  gravity: Vector3;\r\n  /** Length of one simulation step, in seconds. Default 1/60. */\r\n  fixedTimeStep: number;\r\n  /** Most simulation steps taken in one frame. Default 8: real time down to 7.5 frames per second at the default step. */\r\n  maxSubSteps: number;\r\n  /** Whether moving bodies are drawn between their last two simulated poses. Default true. */\r\n  interpolation: boolean;\r\n  /** Whether this world steps on its own each frame. Default true. */\r\n  enabled: boolean;\r\n  /** Whether the simulation waits to start until mesh and terrain colliders have their geometry. Default true. */\r\n  waitForCollidersOnStart: boolean;\r\n  /** Display names of the 16 collider layers. */\r\n  readonly layerNames: readonly string[];\r\n  /** Whether colliders on layers `a` and `b` collide. */\r\n  getLayerCollision(a: number, b: number): boolean;\r\n  /** Sets whether colliders on layers `a` and `b` collide; applies to both orders. */\r\n  setLayerCollision(a: number, b: number, enabled: boolean): void;\r\n  /** Advances the simulation by `dt` seconds of frame time; called each frame while enabled. */\r\n  update(dt: number): void;\r\n  /** Resolves once every collider waiting for its geometry has it, or failed to. */\r\n  whenReady(): Promise<void>;\r\n  /**\r\n   * Brings the world up to date with the scene without stepping it: physics data added,\r\n   * removed or changed, and nodes moved, since the last step. For tools querying a world that\r\n   * is not simulated, such as the editor's; queries otherwise see the world as of the last step.\r\n   *\r\n   * @remarks\r\n   * Moves no body. Colliders that come to touch through it start touching without a contact\r\n   * event, so do not call it on a world being simulated if contact events matter.\r\n   */\r\n  syncWithScene(): void;\r\n  /** The nearest collider along a ray. */\r\n  raycast(\r\n    origin: Vector3,\r\n    direction: Vector3,\r\n    maxDistance?: number,\r\n    options?: PhysicsQueryOptions\r\n  ): Nullable<PhysicsQueryHit>;\r\n  /** Every collider along a ray, nearest first. */\r\n  raycastAll(\r\n    origin: Vector3,\r\n    direction: Vector3,\r\n    maxDistance?: number,\r\n    options?: PhysicsQueryOptions\r\n  ): PhysicsQueryHit[];\r\n  /** The first collider a shape moved along a direction would touch. */\r\n  shapeCast(\r\n    shape: PhysicsShape,\r\n    position: Vector3,\r\n    rotation: Quaternion,\r\n    direction: Vector3,\r\n    maxDistance?: number,\r\n    options?: PhysicsQueryOptions\r\n  ): Nullable<PhysicsQueryHit>;\r\n  /** Colliders overlapping a shape. */\r\n  overlap(\r\n    shape: PhysicsShape,\r\n    position: Vector3,\r\n    rotation: Quaternion,\r\n    options?: PhysicsQueryOptions\r\n  ): Collider[];\r\n  /** Colliders containing a point. */\r\n  overlapPoint(point: Vector3, options?: PhysicsQueryOptions): Collider[];\r\n  /**\r\n   * Traces a collider's shape (or a character controller's capsule) as lines,\r\n   * exactly as the simulation builds it; for tools.\r\n   */\r\n  getColliderOutline(target: Collider | CharacterController): Promise<Nullable<ColliderOutline>>;\r\n  /** A key that changes whenever {@link PhysicsWorld.getColliderOutline} would give a different outline. */\r\n  getColliderOutlineKey(target: Collider | CharacterController): string;\r\n  /** Releases the world. */\r\n  dispose(): void;\r\n\r\n  /** Whether a fixed update is running, so forces act on one step only. */\r\n  readonly _inFixedUpdate: boolean;\r\n  _registerBody(body: RigidBody): void;\r\n  _unregisterBody(body: RigidBody): void;\r\n  _markBodyDirty(body: RigidBody): void;\r\n  _getBodyHandle(body: RigidBody): Nullable<PhysicsBodyHandle>;\r\n  _registerCollider(collider: Collider): void;\r\n  _unregisterCollider(collider: Collider): void;\r\n  _markColliderDirty(collider: Collider): void;\r\n  _updateColliderGroups(collider: Collider): void;\r\n  _registerJoint(joint: Joint): void;\r\n  _unregisterJoint(joint: Joint): void;\r\n  _markJointDirty(joint: Joint): void;\r\n  _getJointHandle(joint: Joint): Nullable<PhysicsJointHandle>;\r\n  _applyJointLimits(joint: Joint): void;\r\n  _applyJointMotor(joint: Joint): void;\r\n  _jointValue(joint: Joint): number;\r\n  _registerCharacter(character: CharacterController): void;\r\n  _unregisterCharacter(character: CharacterController): void;\r\n  _configureCharacter(character: CharacterController): void;\r\n  _moveCharacter(character: CharacterController, displacement: Vector3): Nullable<CharacterMoveResult>;\r\n  _registerVehicle(vehicle: Vehicle): void;\r\n  _unregisterVehicle(vehicle: Vehicle): void;\r\n  _registerWheel(wheel: Wheel): void;\r\n  _unregisterWheel(wheel: Wheel): void;\r\n  _markVehiclesDirty(): void;\r\n  _vehicleSpeed(vehicle: Vehicle): number;\r\n  _vehicleWheels(vehicle: Vehicle): readonly Wheel[];\r\n  _colliderNodeByKey(key: number): Nullable<SceneNode>;\r\n}\r\n\r\n/**\r\n * Creates the physics world of a scene.\r\n *\r\n * @public\r\n */\r\nexport type PhysicsWorldFactory = (scene: Scene) => PhysicsWorld;\r\n\r\nlet worldFactory: Nullable<PhysicsWorldFactory> = null;\r\n\r\n/**\r\n * Sets how scenes get their physics world.\r\n *\r\n * @remarks\r\n * Called by a physics implementation when it is loaded (`initPhysics` of\r\n * `@zephyr3d/physics`), not usually by applications. Scenes create their world\r\n * from it the first time they need one; scenes that already have a world keep\r\n * it. Without a factory, scenes have no world: physics data on nodes is kept,\r\n * saved and loaded, but not simulated.\r\n *\r\n * @public\r\n */\r\nexport function setPhysicsWorldFactory(factory: Nullable<PhysicsWorldFactory>) {\r\n  worldFactory = factory;\r\n}\r\n\r\n/**\r\n * The factory set with {@link setPhysicsWorldFactory}, or null.\r\n *\r\n * @public\r\n */\r\nexport function getPhysicsWorldFactory() {\r\n  return worldFactory;\r\n}\r\n"],"names":["worldFactory","setPhysicsWorldFactory","factory","getPhysicsWorldFactory"],"mappings":"AAoLA,IAAIA,YAA8C,GAAA,IAAA;AAElD;;;;;;;;;;;IAYO,SAASC,sBAAAA,CAAuBC,OAAsC,EAAA;IAC3EF,YAAeE,GAAAA,OAAAA;AACjB;AAEA;;;;AAIC,IACM,SAASC,sBAAAA,GAAAA;IACd,OAAOH,YAAAA;AACT;;;;"}

package/dist/posteffect/bloom.js

@@ -8,6 +8,13 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
  */ class Bloom extends AbstractPostEffect {
     static className = 'Bloom';
     /** Largest finite IEEE-754 half-float value used by the HDR post-effect chain. */ static HALF_FLOAT_MAX = 65504;
+    static PHYSICAL_LEVEL_WEIGHTS = [
+        0.3465 + 0.138,
+        0.1176,
+        0.066,
+        0.066,
+        0.061
+    ].map((w)=>w * 0.675);
     static _programDownsampleH = null;
     static _programDownsampleV = null;
     static _programUpsample = null;
@@ -117,12 +124,36 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
    * NdotL ~ 1 changes frame to frame. The trade is a slightly dimmer, slightly tighter halo,
    * because the weighting deliberately holds the brightest samples back. Turn it off for a static
    * scene that wants maximum reach and has no high-frequency speculars to stabilize.
+   *
+   * Only applies under legacy lighting. With physical lighting, bloom downsample is a
+   * plain linear average and leaves fireflies to TAA (bloom reads the TAA-resolved frame).
    */ get karisAverage() {
         return this._karisAverage;
     }
     set karisAverage(val) {
         this._karisAverage = !!val;
     }
+    static _levelWeights(ctx, count) {
+        const physical = ctx.scene?.lightingMode === 'physical';
+        const weights = [];
+        for(let i = 0; i < count; i++){
+            weights.push(physical ? Bloom.PHYSICAL_LEVEL_WEIGHTS[i] ?? 0 : 1);
+        }
+        return weights;
+    }
+    /** Whether the prefilter uses the Karis average, see {@link Bloom.karisAverage}. */ _useKarisAverage(ctx) {
+        return this._karisAverage && ctx.scene?.lightingMode !== 'physical';
+    }
+    /**
+   * Upsample source scale for level `i + 1` into level `i`.
+   *
+   * @remarks
+   * The chain accumulates acc[i] = L[i] + (w[i+1] / w[i]) * up(acc[i+1]), which equals
+   * sum(w[k] * L[k]) / w[i]; the final compose multiplies by w[0]. This weights every level with a
+   * single scalar per pass.
+   */ static _upsampleScale(weights, i) {
+        return weights[i] > 0 ? weights[i + 1] / weights[i] : 0;
+    }
     /** {@inheritDoc AbstractPostEffect.requireLinearDepthTexture} */ requireLinearDepthTexture() {
         return false;
     }
@@ -161,6 +192,7 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
             // Degenerate viewport: no pyramid possible, bloom contributes nothing.
             return s.input;
         }
+        const weights = Bloom._levelWeights(ctx, levels.length);
         // 1. Prefilter (threshold/knee) at half resolution.
         const prefilterHandle = graph.addPass('Bloom:Prefilter', (builder)=>{
             builder.read(s.input);
@@ -180,7 +212,7 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
                 this._prepare(device, inputTexture);
                 device.pushDeviceStates();
                 try {
-                    this.prefilter(device, inputTexture, rg.getTexture(out));
+                    this.prefilter(device, inputTexture, rg.getTexture(out), this._useKarisAverage(ctx));
                 } finally{
                     device.popDeviceStates();
                 }
@@ -240,7 +272,7 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
                     device.pushDeviceStates();
                     try {
                         this._prepare(device, rg.getTexture(src));
-                        this.upsampleInto(device, rg.getTexture(src), rg.getTexture(out));
+                        this.upsampleInto(device, rg.getTexture(src), rg.getTexture(out), Bloom._upsampleScale(weights, i));
                     } finally{
                         device.popDeviceStates();
                     }
@@ -264,7 +296,7 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
                     device.setFramebuffer(output.framebuffer ? rg.getFramebuffer(output.framebuffer) : null);
                     device.setViewport(null);
                     device.setScissor(null);
-                    this.finalCompose(device, rg.getTexture(s.input), rg.getTexture(bloomHandle), output.srgbOutput);
+                    this.finalCompose(device, rg.getTexture(s.input), rg.getTexture(bloomHandle), output.srgbOutput, weights[0]);
                 } finally{
                     device.popDeviceStates();
                 }
@@ -280,17 +312,18 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
         const w = Math.max(inputColorTexture.width >> 1, 1);
         const h = Math.max(inputColorTexture.height >> 1, 1);
         const colorTex = device.pool.fetchTemporalTexture2D(false, inputColorTexture.format, w, h, false);
-        this.prefilter(device, inputColorTexture, colorTex);
+        this.prefilter(device, inputColorTexture, colorTex, this._useKarisAverage(ctx));
         this.downsample(device, colorTex, downsampleTextures);
-        this.upsample(device, downsampleTextures);
+        const weights = Bloom._levelWeights(ctx, downsampleTextures.length);
+        this.upsample(device, downsampleTextures, weights);
         device.popDeviceStates();
-        this.finalCompose(device, inputColorTexture, downsampleTextures[0], srgbOutput);
+        this.finalCompose(device, inputColorTexture, downsampleTextures[0], srgbOutput, weights[0]);
         for (const tex of downsampleTextures){
             device.pool.releaseTexture(tex);
         }
         device.pool.releaseTexture(colorTex);
     }
-    /** @internal */ prefilter(device, srcTexture, rt) {
+    /** @internal */ prefilter(device, srcTexture, rt, karis = this._karisAverage) {
         this._thresholdValue.x = this._threshold * this._threshold;
         this._thresholdValue.y = this._thresholdValue.x * this._thresholdKnee;
         this._thresholdValue.z = 2 * this._thresholdValue.y;
@@ -309,15 +342,15 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
         // Half-texel diagonals of the *source*, so each fetch lands on a 2x2 group boundary.
         this._invTexSize.setXY(1 / srcTexture.width, 1 / srcTexture.height);
         Bloom._bindgroupPrefilter.setValue('invTexSize', this._invTexSize);
-        Bloom._bindgroupPrefilter.setValue('karis', this._karisAverage ? 1 : 0);
+        Bloom._bindgroupPrefilter.setValue('karis', karis ? 1 : 0);
         this.drawFullscreenQuad();
     }
-    /** @internal */ finalCompose(device, srcTexture, bloomTexture, srgbOutput) {
+    /** @internal */ finalCompose(device, srcTexture, bloomTexture, srgbOutput, levelWeight = 1) {
         device.setProgram(Bloom._programFinalCompose);
         device.setBindGroup(0, Bloom._bindgroupFinalCompose);
         Bloom._bindgroupFinalCompose.setTexture('srcTex', srcTexture);
         Bloom._bindgroupFinalCompose.setTexture('bloomTex', bloomTexture);
-        Bloom._bindgroupFinalCompose.setValue('intensity', this._intensity);
+        Bloom._bindgroupFinalCompose.setValue('intensity', this._intensity * levelWeight);
         // Legacy lighting puts Bloom last in the chain (see Camera.syncPostProcessingMode), so this
         // pass may be the one writing the sRGB screen. Without this the whole frame is handed to the
         // display scene-linear and everything darkens the moment bloom is switched on.
@@ -325,14 +358,15 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
         Bloom._bindgroupFinalCompose.setValue('flip', device.type === 'webgpu' && device.getFramebuffer() ? 1 : 0);
         this.drawFullscreenQuad();
     }
-    /** @internal */ upsample(device, textures) {
+    /** @internal */ upsample(device, textures, weights) {
         for(let i = textures.length - 2; i >= 0; i--){
-            this.upsampleInto(device, textures[i + 1], textures[i]);
+            this.upsampleInto(device, textures[i + 1], textures[i], weights ? Bloom._upsampleScale(weights, i) : 1);
         }
     }
-    /** @internal */ upsampleInto(device, srcTexture, dstTexture) {
+    /** @internal */ upsampleInto(device, srcTexture, dstTexture, scale = 1) {
         device.setProgram(Bloom._programUpsample);
         device.setBindGroup(0, Bloom._bindgroupUpsample);
+        Bloom._bindgroupUpsample.setValue('scale', scale);
         Bloom._bindgroupUpsample.setValue('flip', device.type === 'webgpu' ? 1 : 0);
         Bloom._bindgroupUpsample.setTexture('tex', srcTexture);
         // Tent offsets are in source-texel units, so the filter widens with the level it reads
@@ -545,6 +579,7 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
                     this.tex = pb.tex2D().uniform(0);
                     this.invTexSize = pb.vec2().uniform(0);
                     this.radius = pb.float().uniform(0);
+                    this.scale = pb.float().uniform(0);
                     this.$outputs.outColor = pb.vec4();
                     pb.main(function() {
                         // 3x3 tent filter, the upsample kernel from "Next Generation Post Processing in
@@ -604,7 +639,7 @@ import { Vector4, Vector2 } from '@zephyr3d/base';
                         for (const [dx, dy, w] of taps){
                             this.sum = pb.add(this.sum, pb.mul(pb.textureSampleLevel(this.tex, pb.add(this.$inputs.uv, pb.mul(this.o, pb.vec2(dx, dy))), 0).rgb, w / 16));
                         }
-                        this.$outputs.outColor = pb.vec4(this.sum, 1);
+                        this.$outputs.outColor = pb.vec4(pb.mul(this.sum, this.scale), 1);
                     });
                 }
             });