dacha 0.18.0-alpha.8 → 0.18.0

package/build/contrib/components/rigid-body/index.js

@@ -3,8 +3,16 @@ import { Vector2 } from '../../../engine/math-lib';
 /**
  * RigidBody component for defining rigid body physics.
  *
- * Defines the physics properties for an actor. It's used by the
- * physics system to apply forces and impulses to the actor.
+ * Defines the physics properties for an actor. Dynamic bodies react to forces,
+ * impulses, gravity, collisions, and rotation. Static and kinematic bodies can
+ * participate in collisions but are not moved by solver impulses.
+ *
+ * Physics is simulated in world space.
+ *
+ * Rigid bodies may be parented only to actors with static transforms. A moving
+ * parent (for example, a dynamic or kinematic rigid body) and the physics
+ * simulation would both control the child's transform, so the result is
+ * undefined.
  *
  * @example
  * ```typescript
@@ -29,24 +37,54 @@ import { Vector2 } from '../../../engine/math-lib';
 export class RigidBody extends Component {
     _mass;
     _inverseMass;
+    _inertia;
+    _inverseInertia;
+    _restitution;
+    _friction;
     /** @internal Pending one-step kinematic movement target */
     _movementTarget;
+    /** @internal Linear velocity from the start of the current physics step */
+    _prevLinearVelocity;
+    /** @internal Angular velocity from the start of the current physics step */
+    _prevAngularVelocity;
+    /** @internal Temporary solver velocity used for contact separation */
+    _biasLinearVelocity;
+    /** @internal Temporary solver angular velocity used for contact separation */
+    _biasAngularVelocity;
+    /** @internal Time this body has stayed below automatic sleep thresholds */
+    _sleepTime;
     /** Body type that defines how the rigid body participates in simulation */
     type;
-    /** Gravity scale of the rigid body */
+    /** Gravity multiplier. `0` ignores gravity, `1` uses normal world gravity. */
     gravityScale;
-    /** Linear damping value used to slow down movement over time */
+    /** Linear damping used to slow down movement over time */
     linearDamping;
-    /** Current linear velocity of the rigid body */
+    /** Angular damping used to slow down rotation over time */
+    angularDamping;
+    /** Current linear velocity in world units per second */
     linearVelocity;
+    /** Current angular velocity of the rigid body in radians per second */
+    angularVelocity;
+    /** Whether dynamic rotation is locked. Locked bodies do not spin from torque or contacts. */
+    lockRotation;
     /** Whether rigid body simulation is disabled */
     disabled;
     /** Whether rigid body is sleeping */
     sleeping;
-    /** Force applied to the rigid body */
-    force;
-    /** Impulse applied to the rigid body */
-    impulse;
+    /** Whether this body may be put to sleep automatically when settled */
+    autoSleep;
+    /** @internal Force applied at the rigid body center */
+    _centralForce;
+    /** @internal Impulse applied at the rigid body center */
+    _centralImpulse;
+    /** @internal Forces applied at world-space positions */
+    _pointForces;
+    /** @internal Impulses applied at world-space positions */
+    _pointImpulses;
+    /** @internal Torque applied to the rigid body */
+    _torque;
+    /** @internal Angular impulse applied to the rigid body */
+    _angularImpulse;
     /** Whether contacts should only be resolved from one side */
     oneWay;
     /** Local-space normal that points toward the blocking side */
@@ -59,16 +97,36 @@ export class RigidBody extends Component {
         super();
         this._mass = 0;
         this._inverseMass = 0;
+        this._inertia = 0;
+        this._inverseInertia = 0;
+        this._restitution = 0;
+        this._friction = 0;
         this._movementTarget = null;
+        this._prevLinearVelocity = new Vector2(0, 0);
+        this._prevAngularVelocity = 0;
+        this._biasLinearVelocity = new Vector2(0, 0);
+        this._biasAngularVelocity = 0;
+        this._sleepTime = 0;
         this.type = config.type;
-        this.mass = config.mass ?? 0;
-        this.gravityScale = config.gravityScale ?? 0;
+        this.mass = config.mass ?? (this.type === 'dynamic' ? 1 : 0);
+        this.gravityScale =
+            config.gravityScale ?? (this.type === 'dynamic' ? 1 : 0);
         this.linearDamping = config.linearDamping ?? 0;
-        this.linearVelocity = new Vector2(0, 0);
+        this.angularDamping = config.angularDamping ?? 0;
+        this.restitution = config.restitution ?? 0;
+        this.friction = config.friction ?? 0.6;
+        this.lockRotation = config.lockRotation ?? false;
+        this.autoSleep = config.autoSleep ?? true;
         this.disabled = config.disabled;
+        this.linearVelocity = new Vector2(0, 0);
+        this.angularVelocity = 0;
         this.sleeping = false;
-        this.force = new Vector2(0, 0);
-        this.impulse = new Vector2(0, 0);
+        this._centralForce = new Vector2(0, 0);
+        this._centralImpulse = new Vector2(0, 0);
+        this._pointForces = [];
+        this._pointImpulses = [];
+        this._torque = 0;
+        this._angularImpulse = 0;
         this.oneWay = config.oneWay ?? false;
         if (this.oneWay) {
             this.oneWayNormal = new Vector2(config.oneWayNormalX ?? 0, config.oneWayNormalY ?? 0).normalize();
@@ -83,6 +141,7 @@ export class RigidBody extends Component {
     /**
      * Sets the mass used by dynamic bodies.
      *
+     * Mass is an authored, kilogram-like scalar.
      * Non-positive values make the body immovable by forces and impulses.
      */
     set mass(value) {
@@ -95,50 +154,160 @@ export class RigidBody extends Component {
      * Bodies with zero or negative mass return `0`.
      */
     get inverseMass() {
+        if (this.type === 'static' || this.type === 'kinematic' || this.sleeping) {
+            return 0;
+        }
         return this._inverseMass;
     }
+    get inertia() {
+        return this._inertia;
+    }
+    /**
+     * Moment of inertia used by dynamic bodies.
+     *
+     * Inertia is the rotational equivalent of mass: higher values make the body
+     * harder to spin. It is automatically computed from the collider shape, mass,
+     * and collider offset every physics step, so user code usually should only
+     * read this value.
+     */
+    set inertia(value) {
+        this._inertia = value;
+        this._inverseInertia = value > 0 ? 1 / value : 0;
+    }
+    /**
+     * Returns the inverse moment of inertia.
+     *
+     * This is the solver-friendly form of inertia. Static bodies, kinematic
+     * bodies, locked rotation, or non-positive inertia return `0`.
+     */
+    get inverseInertia() {
+        if (this.type === 'static' ||
+            this.type === 'kinematic' ||
+            this.sleeping ||
+            this.lockRotation) {
+            return 0;
+        }
+        return this._inverseInertia;
+    }
+    /** Bounciness used by contact resolution. `0` does not bounce, `1` keeps full bounce speed. */
+    get restitution() {
+        return this._restitution;
+    }
+    set restitution(value) {
+        this._restitution = Math.max(0, Math.min(value, 1));
+    }
+    /** Surface friction used by contact resolution. Higher values reduce sliding more strongly. */
+    get friction() {
+        return this._friction;
+    }
+    set friction(value) {
+        this._friction = Math.max(0, value);
+    }
     /**
      * Adds a continuous force to a dynamic body for the next physics step.
      *
-     * Affects only active dynamic bodies.
+     * Affects only active dynamic bodies. When `position` is provided, it is a
+     * world-space point where the force is applied; off-center forces can also
+     * rotate the body.
      */
-    applyForce(force) {
+    applyForce(force, position) {
         if (this.disabled || this.type !== 'dynamic') {
             return;
         }
         this.wakeUp();
-        this.force.add(force);
+        if (!position) {
+            this._centralForce.add(force);
+            return;
+        }
+        this._pointForces.push({
+            force: force.clone(),
+            position: { x: position.x, y: position.y },
+        });
     }
     /**
      * Adds an instantaneous impulse to a dynamic body for the next physics step.
      *
-     * Affects only active dynamic bodies.
+     * Affects only active dynamic bodies. An impulse is a one-step velocity kick.
+     * When `position` is provided, it is a world-space point where the impulse is
+     * applied; off-center impulses can also rotate the body.
      */
-    applyImpulse(impulse) {
+    applyImpulse(impulse, position) {
         if (this.disabled || this.type !== 'dynamic') {
             return;
         }
         this.wakeUp();
-        this.impulse.add(impulse);
+        if (!position) {
+            this._centralImpulse.add(impulse);
+            return;
+        }
+        this._pointImpulses.push({
+            impulse: impulse.clone(),
+            position: { x: position.x, y: position.y },
+        });
+    }
+    /**
+     * Adds a continuous torque to a dynamic body for the next physics step.
+     *
+     * Torque is rotational force: it changes angular velocity over time. Affects
+     * only active dynamic bodies with unlocked rotation.
+     */
+    applyTorque(torque) {
+        if (this.disabled || this.type !== 'dynamic' || this.lockRotation) {
+            return;
+        }
+        this.wakeUp();
+        this._torque += torque;
+    }
+    /**
+     * Adds an instantaneous angular impulse to a dynamic body for the next physics step.
+     *
+     * Angular impulse is an immediate rotational kick. Affects only active dynamic
+     * bodies with unlocked rotation.
+     */
+    applyAngularImpulse(impulse) {
+        if (this.disabled || this.type !== 'dynamic' || this.lockRotation) {
+            return;
+        }
+        this.wakeUp();
+        this._angularImpulse += impulse;
     }
     /**
      * Marks the rigid body as awake so it can be simulated.
      */
     wakeUp() {
+        if (this.disabled || this.type !== 'dynamic') {
+            return;
+        }
         this.sleeping = false;
+        this._sleepTime = 0;
     }
     /**
      * Marks the rigid body as sleeping so dynamic integration can skip it.
      */
     sleep() {
+        if (this.disabled || this.type !== 'dynamic') {
+            return;
+        }
         this.sleeping = true;
+        this._sleepTime = 0;
+        this._prevLinearVelocity.multiplyNumber(0);
+        this._prevAngularVelocity = 0;
+        this.linearVelocity.multiplyNumber(0);
+        this.angularVelocity = 0;
+        this._biasLinearVelocity.multiplyNumber(0);
+        this._biasAngularVelocity = 0;
+        this.clearForces();
     }
     /**
      * Clears all accumulated force and impulse values.
      */
     clearForces() {
-        this.force.multiplyNumber(0);
-        this.impulse.multiplyNumber(0);
+        this._centralForce.multiplyNumber(0);
+        this._centralImpulse.multiplyNumber(0);
+        this._pointForces.length = 0;
+        this._pointImpulses.length = 0;
+        this._torque = 0;
+        this._angularImpulse = 0;
     }
     /**
      * Moves a kinematic body to a target position on the next physics step.

package/build/contrib/systems/animator/index.d.ts

@@ -1,5 +1,5 @@
 import { SceneSystem } from '../../../engine/system';
-import type { UpdateOptions, SceneSystemOptions } from '../../../engine/system';
+import type { SceneSystemOptions } from '../../../engine/system';
 /**
  * Animator system that manages the animation of actors with {@link Animatable} components
  * using the state machine approach
@@ -10,6 +10,7 @@ import type { UpdateOptions, SceneSystemOptions } from '../../../engine/system';
  */
 export declare class Animator extends SceneSystem {
     private actorQuery;
+    private time;
     private substatePickers;
     private actorConditions;
     constructor(options: SceneSystemOptions);
@@ -18,5 +19,5 @@ export declare class Animator extends SceneSystem {
     private setUpConditionControllers;
     private updateFrame;
     private pickSubstate;
-    update(options: UpdateOptions): void;
+    update(): void;
 }

package/build/contrib/systems/animator/index.js

@@ -5,7 +5,8 @@ import { RemoveActor } from '../../../engine/events';
 import { conditionControllers } from './condition-controllers';
 import { substatePickers } from './substate-pickers';
 import { setValue } from './utils';
-const FRAME_RATE = 100;
+// Seconds per animation frame at speed 1.
+const FRAME_RATE = 0.1;
 /**
  * Animator system that manages the animation of actors with {@link Animatable} components
  * using the state machine approach
@@ -16,10 +17,12 @@ const FRAME_RATE = 100;
  */
 export class Animator extends SceneSystem {
     actorQuery;
+    time;
     substatePickers;
     actorConditions;
     constructor(options) {
         super();
+        this.time = options.time;
         this.actorQuery = new ActorQuery({
             scene: options.scene,
             filter: [Animatable],
@@ -64,8 +67,8 @@ export class Animator extends SceneSystem {
         const substatePicker = this.substatePickers[state.pickMode];
         return substatePicker.getSubstate(actor, state.substates, state.pickProps);
     }
-    update(options) {
-        const { deltaTime } = options;
+    update() {
+        const { deltaTime } = this.time;
         this.actorQuery.getActors().forEach((actor) => {
             const animatable = actor.getComponent(Animatable);
             if (animatable.currentState === void 0) {

package/build/contrib/systems/behavior-system/system.d.ts

@@ -1,5 +1,5 @@
 import { SceneSystem } from '../../../engine/system';
-import type { SceneSystemOptions, UpdateOptions } from '../../../engine/system';
+import type { SceneSystemOptions } from '../../../engine/system';
 /**
  * Behavior system that manages custom behavior execution for actors
  * with {@link Behaviors} components
@@ -15,6 +15,7 @@ export declare class BehaviorSystem extends SceneSystem {
     private behaviors;
     private world;
     private scene;
+    private time;
     private activeBehaviors;
     constructor(options: SceneSystemOptions);
     onSceneEnter(): void;
@@ -22,5 +23,6 @@ export declare class BehaviorSystem extends SceneSystem {
     private handleActorAdd;
     private handleActorRemove;
     private setUpBehavior;
-    update(options: UpdateOptions): void;
+    update(): void;
+    fixedUpdate(): void;
 }

package/build/contrib/systems/behavior-system/system.js

@@ -17,12 +17,14 @@ export class BehaviorSystem extends SceneSystem {
     behaviors;
     world;
     scene;
+    time;
     activeBehaviors;
     constructor(options) {
         super();
-        const { actorSpawner, world, scene, globalOptions, resources = [], } = options;
+        const { actorSpawner, world, scene, globalOptions, time, resources = [], } = options;
         this.world = world;
         this.scene = scene;
+        this.time = time;
         this.behaviorQuery = new ActorQuery({
             scene,
             filter: [Behaviors],
@@ -79,14 +81,20 @@ export class BehaviorSystem extends SceneSystem {
                 world: this.world,
                 scene: this.scene,
                 globalOptions: this.globalOptions,
+                time: this.time,
             };
             const BehaviorClass = this.behaviors[config.name];
             return new BehaviorClass(options);
         });
     }
-    update(options) {
+    update() {
         this.behaviorQuery.getActors().forEach((actor) => {
-            this.activeBehaviors[actor.id].forEach((behavior) => behavior.update?.(options));
+            this.activeBehaviors[actor.id].forEach((behavior) => behavior.update?.());
+        });
+    }
+    fixedUpdate() {
+        this.behaviorQuery.getActors().forEach((actor) => {
+            this.activeBehaviors[actor.id].forEach((behavior) => behavior.fixedUpdate?.());
         });
     }
 }

package/build/contrib/systems/behavior-system/types.d.ts

@@ -1,6 +1,7 @@
 import type { Actor, ActorSpawner } from '../../../engine/actor';
 import type { World } from '../../../engine/world';
 import type { Scene } from '../../../engine/scene';
+import type { Time } from '../../../engine/time';
 import type { Constructor } from '../../../types/utils';
 /**
  * Options for the behavior
@@ -16,13 +17,8 @@ export interface BehaviorOptions {
     actorSpawner: ActorSpawner;
     /** Global game options */
     globalOptions: Record<string, unknown>;
-}
-/**
- * Options for the update method
- */
-interface UpdateOptions {
-    /** Time elapsed since the last update in milliseconds */
-    deltaTime: number;
+    /** Shared timing state */
+    time: Time;
 }
 /**
  * Base class for all behaviors
@@ -35,8 +31,10 @@ export declare abstract class Behavior {
     static behaviorName: string;
     /** Destroy the behavior */
     destroy?(): void;
-    /** Update the behavior */
-    update?(options: UpdateOptions): void;
+    /** Update the behavior every frame with a variable timestep */
+    update?(): void;
+    /** Update the behavior with a fixed timestep, aligned with physics */
+    fixedUpdate?(): void;
 }
 /**
  * Constructor for all behaviors
@@ -44,4 +42,3 @@ export declare abstract class Behavior {
 export type BehaviorConstructor = Constructor<Behavior> & {
     behaviorName: string;
 };
-export {};

package/build/contrib/systems/character-controller/index.d.ts

@@ -1,5 +1,5 @@
 import { SceneSystem } from '../../../engine/system';
-import type { SceneSystemOptions, UpdateOptions } from '../../../engine/system';
+import type { SceneSystemOptions } from '../../../engine/system';
 /**
  * Kinematic character controller system with sweep/slide collision movement.
  *
@@ -13,9 +13,11 @@ import type { SceneSystemOptions, UpdateOptions } from '../../../engine/system';
 export declare class CharacterController extends SceneSystem {
     private actorQuery;
     private world;
+    private time;
     private oneWayValidator;
     constructor(options: SceneSystemOptions);
     onSceneDestroy(): void;
+    private handleRemoveActor;
     private isBlockingHit;
     private isWalkable;
     private isRecoverableOverlap;
@@ -28,5 +30,5 @@ export declare class CharacterController extends SceneSystem {
     private handleHit;
     private move;
     private updateGroundState;
-    fixedUpdate(options: UpdateOptions): void;
+    fixedUpdate(): void;
 }

package/build/contrib/systems/character-controller/index.js

@@ -3,8 +3,9 @@ import { SceneSystem } from '../../../engine/system';
 import { Vector2, VectorOps } from '../../../engine/math-lib';
 import { Collider, CharacterBody, RigidBody, Transform, } from '../../components';
 import { PhysicsAPI } from '../physics-system';
-import { OneWayValidator } from '../../utils/one-way-validator';
 import { CharacterHit } from '../../events';
+import { RemoveActor } from '../../../engine/events';
+import { OneWayValidator } from './one-way-validator';
 import { clipAgainstNormal } from './utils';
 const DISTANCE_EPSILON = 0.000001;
 const SNAP_EPSILON = 0.000001;
@@ -21,19 +22,26 @@ const SNAP_EPSILON = 0.000001;
 export class CharacterController extends SceneSystem {
     actorQuery;
     world;
+    time;
     oneWayValidator;
     constructor(options) {
         super();
         this.world = options.world;
+        this.time = options.time;
         this.actorQuery = new ActorQuery({
             scene: options.scene,
             filter: [CharacterBody, Transform, Collider, RigidBody],
         });
+        this.actorQuery.addEventListener(RemoveActor, this.handleRemoveActor);
         this.oneWayValidator = new OneWayValidator();
     }
     onSceneDestroy() {
+        this.actorQuery.removeEventListener(RemoveActor, this.handleRemoveActor);
         this.actorQuery.destroy();
     }
+    handleRemoveActor = (event) => {
+        this.oneWayValidator.delete(event.actor);
+    };
     isBlockingHit(actor, hit) {
         const rigidBody = hit.actor.getComponent(RigidBody);
         if (!rigidBody || rigidBody.disabled) {
@@ -42,22 +50,18 @@ export class CharacterController extends SceneSystem {
         if (!rigidBody?.oneWay || !rigidBody.oneWayNormal) {
             return true;
         }
-        return this.oneWayValidator.validate(hit.actor, actor, hit.normal);
+        return this.oneWayValidator.shouldBlock(hit.actor, actor, hit.normal);
     }
     isWalkable(actor, normal) {
         const character = actor.getComponent(CharacterBody);
         return (VectorOps.dotProduct(normal, character.upDirection) >=
             Math.cos(character.maxSlopeAngle));
     }
-    isRecoverableOverlap(actor, hit) {
+    isRecoverableOverlap(hit) {
         const rigidBody = hit.actor.getComponent(RigidBody);
-        if (!rigidBody || rigidBody.disabled || rigidBody.type === 'dynamic') {
-            return false;
-        }
-        if (!rigidBody.oneWay || !rigidBody.oneWayNormal) {
-            return true;
-        }
-        return this.oneWayValidator.validate(hit.actor, actor, hit.normal);
+        return (rigidBody !== undefined &&
+            !rigidBody.disabled &&
+            rigidBody.type !== 'dynamic');
     }
     resetGroundState(character) {
         if (character.onGround) {
@@ -79,6 +83,7 @@ export class CharacterController extends SceneSystem {
         const character = actor.getComponent(CharacterBody);
         const transform = actor.getComponent(Transform);
         const distance = displacement.magnitude;
+        this.oneWayValidator.touch(actor);
         return physicsApi.castActor({
             actor,
             offset: {
@@ -87,7 +92,7 @@ export class CharacterController extends SceneSystem {
             },
             direction: displacement,
             maxDistance: distance + character.skinWidth,
-            hitFilter,
+            hitFilter: (hit) => this.isBlockingHit(actor, hit) && hitFilter(hit),
         });
     }
     castMotion(actor, position, displacement) {
@@ -96,11 +101,11 @@ export class CharacterController extends SceneSystem {
                 VectorOps.dotProduct(displacement, hit.normal) > DISTANCE_EPSILON) {
                 return false;
             }
-            return this.isBlockingHit(actor, hit);
+            return true;
         });
     }
     castGround(actor, position, displacement) {
-        return this.cast(actor, position, displacement, (hit) => this.isBlockingHit(actor, hit) && this.isWalkable(actor, hit.normal));
+        return this.cast(actor, position, displacement, (hit) => this.isWalkable(actor, hit.normal));
     }
     recoverOverlaps(actor, position) {
         const character = actor.getComponent(CharacterBody);
@@ -119,7 +124,7 @@ export class CharacterController extends SceneSystem {
             });
             let recovered = false;
             for (const hit of hits) {
-                if (!this.isRecoverableOverlap(actor, hit)) {
+                if (!this.isRecoverableOverlap(hit)) {
                     continue;
                 }
                 const correction = hit.penetration + character.skinWidth;
@@ -220,11 +225,11 @@ export class CharacterController extends SceneSystem {
         target.x += snapDirection.x;
         target.y += snapDirection.y;
     }
-    fixedUpdate(options) {
+    fixedUpdate() {
         if (!this.world.systemApi.has(PhysicsAPI)) {
             return;
         }
-        const deltaTimeInSeconds = options.deltaTime / 1000;
+        const { fixedDeltaTime } = this.time;
         this.oneWayValidator.update();
         this.actorQuery.getActors().forEach((actor) => {
             const transform = actor.getComponent(Transform);
@@ -243,7 +248,7 @@ export class CharacterController extends SceneSystem {
             this.recoverOverlaps(actor, position);
             const displacement = character.velocity
                 .clone()
-                .multiplyNumber(deltaTimeInSeconds)
+                .multiplyNumber(fixedDeltaTime)
                 .add(character._displacement);
             const movingUp = VectorOps.dotProduct(displacement, character.upDirection) >
                 SNAP_EPSILON;

package/build/contrib/systems/character-controller/one-way-validator.d.ts

@@ -0,0 +1,15 @@
+import type { Actor } from '../../../engine/actor';
+import { type Point } from '../../../engine/math-lib';
+export declare class OneWayValidator {
+    private ignoredOneWayContacts;
+    private touchedActors;
+    private oneWayContactUpdateIndex;
+    constructor();
+    private clearOneWayContacts;
+    private trackOneWayContact;
+    touch(actor: Actor): void;
+    shouldBlock(oneWayActor: Actor, otherActor: Actor, normal: Point): boolean;
+    delete(actor: Actor): void;
+    update(): void;
+    lateUpdate(): void;
+}