excalibur 0.32.0-alpha.19 → 0.32.0-alpha.20

package/CHANGELOG.md

@@ -7,7 +7,10 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Breaking Changes
 
--
+- Behavior change: Realistic physics bodies can now sleep by default `canSleepByDefault`
+- Behavior change: The `sleepBias` default is lowered to 0.5 from .9
+- Behavior change: Bodies do not sleep until all bodies in an Island are low motion for at least `sleepTimeThreshold`, default 1000ms
+- Debug: Improve body related information output in the debug draw
 
 ### Deprecated
 
@@ -16,6 +19,13 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- Added new contact `ex.Island` physics optimization, excalibur physics bodies will now wake or sleep the entire connected graph of bodies,
+this only works in the Realistic solver, but it's a huge perf win.
+- Added new `ex.angleDifference(angle1, angle2)` for calculating differences between angles in [0, 2Pi)
+- Added new debug stats to the frame to measure ECS system durations in milliseconds
+  ```typescript
+    const stats: Record<string, number> = engine.stats.currFrame.systemDuration;
+    // "update:CollisionSystem.update" -> .50
 
 - Added new parameter to `ex.Sounds` to schedule start time, this allows you to synchronize playback of multiple audio tracks
   ```typescript
@@ -102,6 +112,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Fixed
 
+- Fixed possible perf issue in `canonicalizeAngle` if a large angle was provided it could take a long time
+- Fixed issue where physics bodies did not sleep under certain situations, especially when gravity was high.
 - Fixed issue where Animation fromSpriteSheet was ignoring repeated sprite sheet indices
 - Fixed issue where setting the width/height of a ScreenElement was incorrectly scaled when supplied with a scale in the ctor
 - Fixed issue where onRemove would sometimes not be called

package/build/dist/Collision/BodyComponent.d.ts

@@ -8,9 +8,9 @@ import { CollisionGroup } from './Group/CollisionGroup';
 import type { Id } from '../Id';
 import { Transform } from '../Math/transform';
 import { EventEmitter } from '../EventEmitter';
-import type { PhysicsConfig } from './PhysicsConfig';
-import type { DeepRequired } from '../Util/Required';
+import type { BodyConfig, PhysicsConfig } from './PhysicsConfig';
 import type { Entity } from '../EntityComponentSystem';
+import type { Island } from './Island';
 export interface BodyComponentOptions {
     type?: CollisionType;
     group?: CollisionGroup;
@@ -31,6 +31,7 @@ export declare class BodyComponent extends Component implements Clonable<BodyCom
     static _ID: number;
     readonly id: Id<'body'>;
     events: EventEmitter<any>;
+    island: Island | null;
     oldTransform: Transform;
     /**
      * Indicates whether the old transform has been captured at least once for interpolation
@@ -44,18 +45,21 @@ export declare class BodyComponent extends Component implements Clonable<BodyCom
     private _bodyConfig;
     private static _DEFAULT_CONFIG;
     wakeThreshold: number;
+    sleepTime: number;
     constructor(options?: BodyComponentOptions);
     get matrix(): import("..").AffineMatrix;
     /**
      * Called by excalibur to update physics config defaults if they change
      * @param config
      */
-    updatePhysicsConfig(config: DeepRequired<Pick<PhysicsConfig, 'bodies'>['bodies']>): void;
+    updatePhysicsConfig(config: BodyConfig): void;
+    get canFallAsleep(): boolean;
+    get canWakeUp(): boolean;
     /**
      * Called by excalibur to update defaults
      * @param config
      */
-    static updateDefaultPhysicsConfig(config: DeepRequired<Pick<PhysicsConfig, 'bodies'>['bodies']>): void;
+    static updateDefaultPhysicsConfig(config: BodyConfig): void;
     /**
      * Collision type for the rigidbody physics simulation, by default {@apilink CollisionType.PreventCollision}
      */
@@ -98,11 +102,13 @@ export declare class BodyComponent extends Component implements Clonable<BodyCom
      * @deprecated use isSleeping
      */
     setSleeping(sleeping: boolean): void;
+    wake(): void;
+    sleep(): void;
     set isSleeping(sleeping: boolean);
     /**
      * Update body's {@apilink BodyComponent.sleepMotion} for the purpose of sleeping
      */
-    updateMotion(): void;
+    updateMotion(duration: number): void;
     private _cachedInertia;
     /**
      * Get the moment of inertia from the {@apilink ColliderComponent}

package/build/dist/Collision/CollisionSystem.d.ts

@@ -6,11 +6,13 @@ import { ColliderComponent } from './ColliderComponent';
 import type { ExcaliburGraphicsContext } from '../Graphics/Context/ExcaliburGraphicsContext';
 import type { Scene } from '../Scene';
 import type { PhysicsWorld } from './PhysicsWorld';
+import { BodyComponent } from './Index';
 export declare class CollisionSystem extends System {
     private _physics;
     static priority: -5;
     systemType: SystemType;
     query: Query<ComponentCtor<TransformComponent> | ComponentCtor<ColliderComponent>>;
+    bodyQuery: Query<ComponentCtor<BodyComponent>>;
     private _engine;
     private _configDirty;
     private _realisticSolver;
@@ -18,6 +20,7 @@ export declare class CollisionSystem extends System {
     private _lastFrameContacts;
     private _currentFrameContacts;
     private _motionSystem;
+    private _bodies;
     private get _processor();
     private _trackCollider;
     private _untrackCollider;

package/build/dist/Collision/Detection/CollisionContact.d.ts

@@ -47,10 +47,6 @@ export declare class CollisionContact {
     bodyA: BodyComponent | null;
     bodyB: BodyComponent | null;
     constructor(colliderA: Collider, colliderB: Collider, mtv: Vector, normal: Vector, tangent: Vector, points: Vector[], localPoints: Vector[], info: SeparationInfo);
-    /**
-     * Match contact awake state, except if body's are Fixed
-     */
-    matchAwake(): void;
     isCanceled(): boolean;
     cancel(): void;
     /**

package/build/dist/Collision/Island.d.ts

@@ -0,0 +1,13 @@
+import type { BodyConfig } from './Index';
+import { type BodyComponent, type CollisionContact } from './Index';
+export declare class Island {
+    config: BodyConfig;
+    bodies: BodyComponent[];
+    contacts: CollisionContact[];
+    isSleeping: boolean;
+    constructor(config: BodyConfig);
+    wake(): void;
+    sleep(): void;
+    updateSleepState(elapsed: number): void;
+}
+export declare function buildContactIslands(config: BodyConfig, bodies: BodyComponent[], contacts: CollisionContact[]): Island[];

package/build/dist/Collision/MotionSystem.d.ts

@@ -10,6 +10,7 @@ export declare class MotionSystem extends System {
     systemType: SystemType;
     private _physicsConfigDirty;
     query: Query<typeof TransformComponent | typeof MotionComponent>;
+    private _createPhysicsQuery;
     constructor(world: World, physics: PhysicsWorld);
     update(elapsed: number): void;
     captureOldTransformWithChildren(entity: Entity): void;

package/build/dist/Collision/PhysicsConfig.d.ts

@@ -119,23 +119,34 @@ export interface PhysicsConfig {
          */
         defaultMass?: number;
         /**
-         * Sleep epsilon
+         * Sleep epsilon - (small number) this is the amount of massless kinetic energy a body needs to be below to fall asleep
          *
          * Default 0.07
          */
         sleepEpsilon?: number;
         /**
-         * Wake Threshold, the amount of "motion" need to wake a body from sleep
+         * Wake Threshold - the amount of "motion" or massless kinetic energy need to wake a body from sleep
          *
          * Default 0.07 * 3;
          */
         wakeThreshold?: number;
         /**
-         * Sleep bias
+         * Sleep bias - The weighted average to apply to the current frame body motion over one second
          *
-         * Default 0.9
+         * ```typescript
+         * let bias = Math.pos(sleepBias, durationSeconds);
+         * let motion = bias * previousAverageMotion + (1 - bias) * currentFrameMotion;
+         * ```
+         *
+         * Default 0.5
          */
         sleepBias?: number;
+        /**
+         * Amount of time that bodies (in contact islands) need to be below the sleepEpsilon
+         *
+         * Default 1000ms
+         */
+        sleepTimeThreshold?: number;
         /**
          * By default bodies do not sleep, this can be turned on to improve perf if you have a lot of bodies.
          *
@@ -204,4 +215,5 @@ export interface PhysicsConfig {
         warmStart?: boolean;
     };
 }
+export type BodyConfig = DeepRequired<Pick<PhysicsConfig, 'bodies'>['bodies']>;
 export declare const getDefaultPhysicsConfig: () => DeepRequired<PhysicsConfig>;

package/build/dist/Collision/PhysicsWorld.d.ts

@@ -27,6 +27,7 @@ export declare class PhysicsWorld {
             sleepEpsilon?: number;
             wakeThreshold?: number;
             sleepBias?: number;
+            sleepTimeThreshold?: number;
             canSleepByDefault?: boolean;
         }>;
         spatialPartition?: SpatialPartitionStrategy;

package/build/dist/Collision/Solver/Solver.d.ts

@@ -21,5 +21,5 @@ export interface CollisionSolver {
      * 4. postSolve
      * @param contacts
      */
-    solve(contacts: CollisionContact[]): CollisionContact[];
+    solve(contacts: CollisionContact[], duration?: number): CollisionContact[];
 }

package/build/dist/Debug/DebugConfig.d.ts

@@ -32,6 +32,10 @@ export interface FrameStatistics {
      * Duration statistics (in ms)
      */
     duration: FrameDurationStats;
+    /**
+     * Duration statistics (in ms) for ECS systems
+     */
+    systemDuration: Record<string, number>;
     /**
      * Actor statistics
      */
@@ -296,6 +300,7 @@ export declare class FrameStats implements FrameStatistics {
     private _durationStats;
     private _physicsStats;
     private _graphicsStats;
+    systemDuration: Record<string, number>;
     /**
      * Zero out values or clone other IFrameStat stats. Allows instance reuse.
      * @param [otherStats] Optional stats to clone

package/build/dist/Math/util.d.ts

@@ -24,6 +24,10 @@ export declare function approximatelyEqual(val1: number, val2: number, tolerance
  * Convert an angle to be the equivalent in the range [0, 2PI)
  */
 export declare function canonicalizeAngle(angle: number): number;
+/**
+ * Return the different in angles in the range [0, 2PI)
+ */
+export declare function angleDifference(angle1: number, angle2: number): number;
 /**
  * Convert radians to degrees
  */