dacha 0.18.0-alpha.8 → 0.18.0

package/build/contrib/components/index.d.ts

@@ -3,6 +3,7 @@ export { KeyboardControl, type KeyboardControlConfig, } from './keyboard-control
 export { Collider, type ColliderConfig, type ColliderShape, type ColliderType, type BoxColliderShape, type CircleColliderShape, type SegmentColliderShape, type CapsuleColliderShape, } from './collider';
 export { RigidBody, type RigidBodyConfig } from './rigid-body';
 export { CharacterBody, type CharacterBodyConfig } from './character-body';
+export { Interpolation, type InterpolationConfig, type InterpolationMode, } from './interpolation';
 export { Animatable, type AnimatableConfig } from './animatable';
 export { Sprite, type SpriteConfig } from './sprite';
 export { Transform, type TransformConfig } from './transform';

package/build/contrib/components/index.js

@@ -3,6 +3,7 @@ export { KeyboardControl, } from './keyboard-control';
 export { Collider, } from './collider';
 export { RigidBody } from './rigid-body';
 export { CharacterBody } from './character-body';
+export { Interpolation, } from './interpolation';
 export { Animatable } from './animatable';
 export { Sprite } from './sprite';
 export { Transform } from './transform';

package/build/contrib/components/interpolation/index.d.ts

@@ -0,0 +1,85 @@
+import { Component } from '../../../engine/component';
+export type InterpolationMode = 'interpolate' | 'extrapolate';
+export interface InterpolationConfig {
+    mode?: InterpolationMode;
+    snapThreshold?: number;
+    disabled?: boolean;
+}
+/**
+ * Component that smooths rendering of actors moved during fixed updates.
+ *
+ * Interpolator keeps local-space snapshots of the actor's Transform around
+ * each fixed step and blends them into the render-facing
+ * `renderX`/`renderY`/`renderRotation` values every render frame using
+ * `Time.alpha`. The renderer prefers these values over the Transform.
+ *
+ * The Transform component always holds the authoritative simulation state.
+ * Interpolated values are only visible to the renderer and to consumers of
+ * InterpolatorAPI, so simulation code can never accidentally read a
+ * visually smoothed but physically incorrect position.
+ *
+ * @example
+ * ```typescript
+ * actor.setComponent(new Interpolation({ mode: 'interpolate' }));
+ *
+ * // After teleporting the actor, skip smoothing for the jump:
+ * actor.getComponent(Transform).world.position.x = 500;
+ * actor.getComponent(Interpolation).snap();
+ * ```
+ *
+ * @category Components
+ */
+export declare class Interpolation extends Component {
+    /**
+     * How render values are produced. `interpolate` blends between the last
+     * two fixed steps (smooth, adds up to one fixed step of visual latency).
+     * `extrapolate` projects the latest step forward using the rigid body
+     * velocity (no added latency, may briefly overshoot on impacts).
+     *
+     * `extrapolate` uses the world-space rigid body velocity against
+     * local-space snapshots, so it is intended for root-level actors.
+     */
+    mode: InterpolationMode;
+    /**
+     * Maximum distance in world units treated as continuous movement between
+     * two fixed steps. Larger jumps snap instead of gliding. `0` disables
+     * the automatic snap detection.
+     */
+    snapThreshold: number;
+    /** Whether smoothing is turned off. The renderer falls back to Transform. */
+    disabled: boolean;
+    /** @internal Local-space position X from the previous fixed step */
+    _prevX: number;
+    /** @internal Local-space position Y from the previous fixed step */
+    _prevY: number;
+    /** @internal Local-space rotation from the previous fixed step */
+    _prevRotation: number;
+    /** @internal Local-space position X from the latest fixed step */
+    _currX: number;
+    /** @internal Local-space position Y from the latest fixed step */
+    _currY: number;
+    /** @internal Local-space rotation from the latest fixed step */
+    _currRotation: number;
+    /** @internal Whether snapshots have been initialized since (re)enabling */
+    _initialized: boolean;
+    /** @internal Whether smoothing should be skipped at the next opportunity */
+    _snapRequested: boolean;
+    /** Render-facing local-space position X, written by Interpolator */
+    renderX: number;
+    /** Render-facing local-space position Y, written by Interpolator */
+    renderY: number;
+    /** Render-facing local-space rotation, written by Interpolator */
+    renderRotation: number;
+    constructor(config?: InterpolationConfig);
+    /**
+     * Whether the render-facing values hold a valid snapshot yet. `false`
+     * until the Interpolator takes its first snapshot after the component is
+     * (re)enabled.
+     */
+    get initialized(): boolean;
+    /**
+     * Requests an immediate jump to the Transform instead of
+     * smoothing towards it. Call right after teleporting the actor.
+     */
+    snap(): void;
+}

package/build/contrib/components/interpolation/index.js

@@ -0,0 +1,101 @@
+import { Component } from '../../../engine/component';
+/**
+ * Component that smooths rendering of actors moved during fixed updates.
+ *
+ * Interpolator keeps local-space snapshots of the actor's Transform around
+ * each fixed step and blends them into the render-facing
+ * `renderX`/`renderY`/`renderRotation` values every render frame using
+ * `Time.alpha`. The renderer prefers these values over the Transform.
+ *
+ * The Transform component always holds the authoritative simulation state.
+ * Interpolated values are only visible to the renderer and to consumers of
+ * InterpolatorAPI, so simulation code can never accidentally read a
+ * visually smoothed but physically incorrect position.
+ *
+ * @example
+ * ```typescript
+ * actor.setComponent(new Interpolation({ mode: 'interpolate' }));
+ *
+ * // After teleporting the actor, skip smoothing for the jump:
+ * actor.getComponent(Transform).world.position.x = 500;
+ * actor.getComponent(Interpolation).snap();
+ * ```
+ *
+ * @category Components
+ */
+export class Interpolation extends Component {
+    /**
+     * How render values are produced. `interpolate` blends between the last
+     * two fixed steps (smooth, adds up to one fixed step of visual latency).
+     * `extrapolate` projects the latest step forward using the rigid body
+     * velocity (no added latency, may briefly overshoot on impacts).
+     *
+     * `extrapolate` uses the world-space rigid body velocity against
+     * local-space snapshots, so it is intended for root-level actors.
+     */
+    mode;
+    /**
+     * Maximum distance in world units treated as continuous movement between
+     * two fixed steps. Larger jumps snap instead of gliding. `0` disables
+     * the automatic snap detection.
+     */
+    snapThreshold;
+    /** Whether smoothing is turned off. The renderer falls back to Transform. */
+    disabled;
+    /** @internal Local-space position X from the previous fixed step */
+    _prevX;
+    /** @internal Local-space position Y from the previous fixed step */
+    _prevY;
+    /** @internal Local-space rotation from the previous fixed step */
+    _prevRotation;
+    /** @internal Local-space position X from the latest fixed step */
+    _currX;
+    /** @internal Local-space position Y from the latest fixed step */
+    _currY;
+    /** @internal Local-space rotation from the latest fixed step */
+    _currRotation;
+    /** @internal Whether snapshots have been initialized since (re)enabling */
+    _initialized;
+    /** @internal Whether smoothing should be skipped at the next opportunity */
+    _snapRequested;
+    /** Render-facing local-space position X, written by Interpolator */
+    renderX;
+    /** Render-facing local-space position Y, written by Interpolator */
+    renderY;
+    /** Render-facing local-space rotation, written by Interpolator */
+    renderRotation;
+    constructor(config = {}) {
+        super();
+        const { mode = 'interpolate', snapThreshold = 0, disabled = false, } = config;
+        this.mode = mode;
+        this.snapThreshold = snapThreshold;
+        this.disabled = disabled;
+        this._prevX = 0;
+        this._prevY = 0;
+        this._prevRotation = 0;
+        this._currX = 0;
+        this._currY = 0;
+        this._currRotation = 0;
+        this._initialized = false;
+        this._snapRequested = false;
+        this.renderX = 0;
+        this.renderY = 0;
+        this.renderRotation = 0;
+    }
+    /**
+     * Whether the render-facing values hold a valid snapshot yet. `false`
+     * until the Interpolator takes its first snapshot after the component is
+     * (re)enabled.
+     */
+    get initialized() {
+        return this._initialized;
+    }
+    /**
+     * Requests an immediate jump to the Transform instead of
+     * smoothing towards it. Call right after teleporting the actor.
+     */
+    snap() {
+        this._snapRequested = true;
+    }
+}
+Interpolation.componentName = 'Interpolation';

package/build/contrib/components/rigid-body/index.d.ts

@@ -1,21 +1,42 @@
 import { Component } from '../../../engine/component';
-import { Vector2 } from '../../../engine/math-lib';
+import { Vector2, type Point } from '../../../engine/math-lib';
 export type RigidBodyType = 'dynamic' | 'static' | 'kinematic';
 export interface RigidBodyConfig {
     type: RigidBodyType;
     mass?: number;
     gravityScale?: number;
     linearDamping?: number;
+    angularDamping?: number;
+    lockRotation?: boolean;
+    autoSleep?: boolean;
+    restitution?: number;
+    friction?: number;
     disabled: boolean;
     oneWay: boolean;
     oneWayNormalX?: number;
     oneWayNormalY?: number;
 }
+interface PointForce {
+    force: Vector2;
+    position: Point;
+}
+interface PointImpulse {
+    impulse: Vector2;
+    position: Point;
+}
 /**
  * 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
@@ -40,24 +61,54 @@ export interface RigidBodyConfig {
 export declare class RigidBody extends Component {
     private _mass;
     private _inverseMass;
+    private _inertia;
+    private _inverseInertia;
+    private _restitution;
+    private _friction;
     /** @internal Pending one-step kinematic movement target */
     _movementTarget: Vector2 | null;
+    /** @internal Linear velocity from the start of the current physics step */
+    _prevLinearVelocity: Vector2;
+    /** @internal Angular velocity from the start of the current physics step */
+    _prevAngularVelocity: number;
+    /** @internal Temporary solver velocity used for contact separation */
+    _biasLinearVelocity: Vector2;
+    /** @internal Temporary solver angular velocity used for contact separation */
+    _biasAngularVelocity: number;
+    /** @internal Time this body has stayed below automatic sleep thresholds */
+    _sleepTime: number;
     /** Body type that defines how the rigid body participates in simulation */
     readonly type: RigidBodyType;
-    /** Gravity scale of the rigid body */
+    /** Gravity multiplier. `0` ignores gravity, `1` uses normal world gravity. */
     gravityScale: number;
-    /** Linear damping value used to slow down movement over time */
+    /** Linear damping used to slow down movement over time */
     linearDamping: number;
-    /** Current linear velocity of the rigid body */
+    /** Angular damping used to slow down rotation over time */
+    angularDamping: number;
+    /** Current linear velocity in world units per second */
     linearVelocity: Vector2;
+    /** Current angular velocity of the rigid body in radians per second */
+    angularVelocity: number;
+    /** Whether dynamic rotation is locked. Locked bodies do not spin from torque or contacts. */
+    lockRotation: boolean;
     /** Whether rigid body simulation is disabled */
     disabled: boolean;
     /** Whether rigid body is sleeping */
     sleeping: boolean;
-    /** Force applied to the rigid body */
-    force: Vector2;
-    /** Impulse applied to the rigid body */
-    impulse: Vector2;
+    /** Whether this body may be put to sleep automatically when settled */
+    autoSleep: boolean;
+    /** @internal Force applied at the rigid body center */
+    _centralForce: Vector2;
+    /** @internal Impulse applied at the rigid body center */
+    _centralImpulse: Vector2;
+    /** @internal Forces applied at world-space positions */
+    _pointForces: PointForce[];
+    /** @internal Impulses applied at world-space positions */
+    _pointImpulses: PointImpulse[];
+    /** @internal Torque applied to the rigid body */
+    _torque: number;
+    /** @internal Angular impulse applied to the rigid body */
+    _angularImpulse: number;
     /** Whether contacts should only be resolved from one side */
     oneWay: boolean;
     /** Local-space normal that points toward the blocking side */
@@ -71,6 +122,7 @@ export declare 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: number);
@@ -80,18 +132,59 @@ export declare class RigidBody extends Component {
      * Bodies with zero or negative mass return `0`.
      */
     get inverseMass(): number;
+    get inertia(): number;
+    /**
+     * 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: number);
+    /**
+     * 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(): number;
+    /** Bounciness used by contact resolution. `0` does not bounce, `1` keeps full bounce speed. */
+    get restitution(): number;
+    set restitution(value: number);
+    /** Surface friction used by contact resolution. Higher values reduce sliding more strongly. */
+    get friction(): number;
+    set friction(value: number);
     /**
      * 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: Vector2): void;
+    applyForce(force: Vector2, position?: Point): void;
     /**
      * 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: Vector2, position?: Point): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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.
      */
-    applyImpulse(impulse: Vector2): void;
+    applyAngularImpulse(impulse: number): void;
     /**
      * Marks the rigid body as awake so it can be simulated.
      */
@@ -112,3 +205,4 @@ export declare class RigidBody extends Component {
      */
     movePosition(position: Vector2): void;
 }
+export {};