dacha 0.18.0-alpha.3 → 0.18.0-alpha.5

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

@@ -0,0 +1,66 @@
+import { Component } from '../../../engine/component';
+import { Vector2 } from '../../../engine/math-lib';
+import type { Actor } from '../../../engine/actor';
+export type CharacterMotionMode = 'surface' | 'free';
+export interface CharacterBodyConfig {
+    motionMode?: CharacterMotionMode;
+    upDirectionX?: number;
+    upDirectionY?: number;
+    skinWidth?: number;
+    maxSlopeAngle?: number;
+    maxSlides?: number;
+    maxRecoveries?: number;
+    groundSnapDistance?: number;
+    disabled?: boolean;
+}
+/**
+ * Kinematic character controller state and movement settings.
+ *
+ * The controller system consumes `velocity` during fixed updates, performs
+ * sweep/slide collision handling, and writes the resulting target through the
+ * actor's kinematic rigid body.
+ *
+ * @category Components
+ */
+export declare class CharacterBody extends Component {
+    private _up;
+    /** @internal Pending one-step displacement consumed by CharacterController */
+    _displacement: Vector2;
+    /** Controls contact classification and whether ground snapping is enabled. */
+    motionMode: CharacterMotionMode;
+    /** Desired character velocity in world units per second */
+    velocity: Vector2;
+    /** Small distance kept between the character shape and blocking colliders */
+    skinWidth: number;
+    /** Maximum walkable ground angle in radians, measured from upDirection */
+    maxSlopeAngle: number;
+    /** Maximum sweep/slide collision iterations used during one fixed update */
+    maxSlides: number;
+    /** Maximum overlap depenetration iterations used before sweep/slide movement */
+    maxRecoveries: number;
+    /** Distance used to probe opposite upDirection and keep ground contact over small gaps */
+    groundSnapDistance: number;
+    /** Whether the controller should be ignored by CharacterController */
+    disabled: boolean;
+    /** Whether the controller is standing on walkable ground after the last fixed update */
+    onGround: boolean;
+    /** Whether movement hit a side wall or non-walkable surface during the last fixed update */
+    onWall: boolean;
+    /** Whether movement hit a ceiling during the last fixed update */
+    onCeiling: boolean;
+    /** Normal of the current walkable ground surface, updated by CharacterController */
+    groundNormal: Vector2;
+    /** Actor providing the current walkable ground, or null when not grounded */
+    groundActor: Actor | null;
+    constructor(config?: CharacterBodyConfig);
+    /** Direction treated as up for ground, ceiling, slopes, ground probes, and jumps */
+    get upDirection(): Vector2;
+    set upDirection(value: Vector2);
+    /**
+     * Adds a one-step world-space displacement request.
+     *
+     * The displacement is consumed by CharacterController on the next fixed
+     * update and is already expected to be scaled by delta time.
+     */
+    move(displacement: Vector2): void;
+}

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

@@ -0,0 +1,81 @@
+import { Component } from '../../../engine/component';
+import { MathOps, Vector2 } from '../../../engine/math-lib';
+/**
+ * Kinematic character controller state and movement settings.
+ *
+ * The controller system consumes `velocity` during fixed updates, performs
+ * sweep/slide collision handling, and writes the resulting target through the
+ * actor's kinematic rigid body.
+ *
+ * @category Components
+ */
+export class CharacterBody extends Component {
+    _up;
+    /** @internal Pending one-step displacement consumed by CharacterController */
+    _displacement;
+    /** Controls contact classification and whether ground snapping is enabled. */
+    motionMode;
+    /** Desired character velocity in world units per second */
+    velocity;
+    /** Small distance kept between the character shape and blocking colliders */
+    skinWidth;
+    /** Maximum walkable ground angle in radians, measured from upDirection */
+    maxSlopeAngle;
+    /** Maximum sweep/slide collision iterations used during one fixed update */
+    maxSlides;
+    /** Maximum overlap depenetration iterations used before sweep/slide movement */
+    maxRecoveries;
+    /** Distance used to probe opposite upDirection and keep ground contact over small gaps */
+    groundSnapDistance;
+    /** Whether the controller should be ignored by CharacterController */
+    disabled;
+    /** Whether the controller is standing on walkable ground after the last fixed update */
+    onGround;
+    /** Whether movement hit a side wall or non-walkable surface during the last fixed update */
+    onWall;
+    /** Whether movement hit a ceiling during the last fixed update */
+    onCeiling;
+    /** Normal of the current walkable ground surface, updated by CharacterController */
+    groundNormal;
+    /** Actor providing the current walkable ground, or null when not grounded */
+    groundActor;
+    constructor(config = {}) {
+        super();
+        this._up = new Vector2(0, -1);
+        this._displacement = new Vector2(0, 0);
+        this.upDirection = new Vector2(config.upDirectionX ?? 0, config.upDirectionY ?? -1);
+        this.motionMode = config.motionMode ?? 'surface';
+        this.disabled = config.disabled ?? false;
+        this.velocity = new Vector2(0, 0);
+        this.skinWidth = config.skinWidth ?? 0.1;
+        this.maxSlopeAngle = MathOps.degToRad(config.maxSlopeAngle ?? 45);
+        this.maxSlides = config.maxSlides ?? 4;
+        this.maxRecoveries = config.maxRecoveries ?? 3;
+        this.groundSnapDistance = config.groundSnapDistance ?? 1;
+        this.onGround = false;
+        this.onWall = false;
+        this.onCeiling = false;
+        this.groundNormal = this.upDirection.clone();
+        this.groundActor = null;
+    }
+    /** Direction treated as up for ground, ceiling, slopes, ground probes, and jumps */
+    get upDirection() {
+        return this._up;
+    }
+    set upDirection(value) {
+        this._up = value.clone().normalize();
+        if (this._up.magnitude === 0) {
+            throw new Error('Character controller upDirection must be non-zero');
+        }
+    }
+    /**
+     * Adds a one-step world-space displacement request.
+     *
+     * The displacement is consumed by CharacterController on the next fixed
+     * update and is already expected to be scaled by delta time.
+     */
+    move(displacement) {
+        this._displacement.add(displacement);
+    }
+}
+CharacterBody.componentName = 'CharacterBody';

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

@@ -7,30 +7,28 @@ export interface BaseColliderConfig {
     offsetY: number;
     layer: string;
     debugColor?: string;
+    disabled: boolean;
 }
 export interface BoxColliderConfig extends BaseColliderConfig {
     type: 'box';
-    sizeX: number;
-    sizeY: number;
+    sizeX?: number;
+    sizeY?: number;
 }
 export interface CircleColliderConfig extends BaseColliderConfig {
     type: 'circle';
-    radius: number;
+    radius?: number;
 }
 export interface SegmentColliderConfig extends BaseColliderConfig {
     type: 'segment';
-    point1X: number;
-    point1Y: number;
-    point2X: number;
-    point2Y: number;
+    point1X?: number;
+    point1Y?: number;
+    point2X?: number;
+    point2Y?: number;
 }
 export interface CapsuleColliderConfig extends BaseColliderConfig {
     type: 'capsule';
-    point1X: number;
-    point1Y: number;
-    point2X: number;
-    point2Y: number;
-    radius: number;
+    height?: number;
+    radius?: number;
 }
 export type ColliderConfig = BoxColliderConfig | CircleColliderConfig | SegmentColliderConfig | CapsuleColliderConfig;
 export interface BoxColliderShape {
@@ -48,8 +46,7 @@ export interface SegmentColliderShape {
 }
 export interface CapsuleColliderShape {
     type: 'capsule';
-    point1: Point;
-    point2: Point;
+    height: number;
     radius: number;
 }
 export type ColliderShape = BoxColliderShape | CircleColliderShape | SegmentColliderShape | CapsuleColliderShape;
@@ -69,6 +66,7 @@ export type ColliderShape = BoxColliderShape | CircleColliderShape | SegmentColl
  *   sizeX: 64,
  *   sizeY: 64,
  *   layer: 'default',
+ *   disabled: false,
  * });
  *
  * // Create a circle collider
@@ -78,6 +76,7 @@ export type ColliderShape = BoxColliderShape | CircleColliderShape | SegmentColl
  *   offsetY: 0,
  *   radius: 32,
  *   layer: 'default',
+ *   disabled: false,
  * });
  *
  * // Add to actor
@@ -90,6 +89,7 @@ export declare class Collider extends Component {
     offset: Point;
     layer: string;
     debugColor?: string;
+    disabled: boolean;
     shape: ColliderShape;
     constructor(config: ColliderConfig);
 }

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

@@ -15,6 +15,7 @@ import { Component } from '../../../engine/component';
  *   sizeX: 64,
  *   sizeY: 64,
  *   layer: 'default',
+ *   disabled: false,
  * });
  *
  * // Create a circle collider
@@ -24,6 +25,7 @@ import { Component } from '../../../engine/component';
  *   offsetY: 0,
  *   radius: 32,
  *   layer: 'default',
+ *   disabled: false,
  * });
  *
  * // Add to actor
@@ -36,38 +38,39 @@ export class Collider extends Component {
     offset;
     layer;
     debugColor;
+    disabled;
     shape;
     constructor(config) {
         super();
         this.offset = { x: config.offsetX, y: config.offsetY };
         this.layer = config.layer;
         this.debugColor = config.debugColor;
+        this.disabled = config.disabled;
         switch (config.type) {
             case 'box':
                 this.shape = {
                     type: config.type,
-                    size: { x: config.sizeX, y: config.sizeY },
+                    size: { x: config.sizeX ?? 0, y: config.sizeY ?? 0 },
                 };
                 break;
             case 'circle':
                 this.shape = {
                     type: config.type,
-                    radius: config.radius,
+                    radius: config.radius ?? 0,
                 };
                 break;
             case 'segment':
                 this.shape = {
                     type: config.type,
-                    point1: { x: config.point1X, y: config.point1Y },
-                    point2: { x: config.point2X, y: config.point2Y },
+                    point1: { x: config.point1X ?? 0, y: config.point1Y ?? 0 },
+                    point2: { x: config.point2X ?? 0, y: config.point2Y ?? 0 },
                 };
                 break;
             case 'capsule':
                 this.shape = {
                     type: config.type,
-                    point1: { x: config.point1X, y: config.point1Y },
-                    point2: { x: config.point2X, y: config.point2Y },
-                    radius: config.radius,
+                    height: config.height ?? 0,
+                    radius: config.radius ?? 0,
                 };
         }
     }

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

@@ -2,6 +2,7 @@ export { Camera, type CameraConfig } from './camera';
 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 { Animatable, type AnimatableConfig } from './animatable';
 export { Sprite, type SpriteConfig } from './sprite';
 export { Transform, type TransformConfig } from './transform';

package/build/contrib/components/index.js

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

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

@@ -1,12 +1,15 @@
 import { Component } from '../../../engine/component';
 import { Vector2 } from '../../../engine/math-lib';
-export type RigidBodyType = 'dynamic' | 'static';
+export type RigidBodyType = 'dynamic' | 'static' | 'kinematic';
 export interface RigidBodyConfig {
     type: RigidBodyType;
-    mass: number;
-    gravityScale: number;
-    linearDamping: number;
+    mass?: number;
+    gravityScale?: number;
+    linearDamping?: number;
     disabled: boolean;
+    oneWay: boolean;
+    oneWayNormalX?: number;
+    oneWayNormalY?: number;
 }
 /**
  * RigidBody component for defining rigid body physics.
@@ -37,9 +40,10 @@ export interface RigidBodyConfig {
 export declare class RigidBody extends Component {
     private _mass;
     private _inverseMass;
-    /** Type of the rigid body */
-    type: RigidBodyType;
-    /** Mass of the rigid body */
+    /** @internal Pending one-step kinematic movement target */
+    _movementTarget: Vector2 | null;
+    /** Body type that defines how the rigid body participates in simulation */
+    readonly type: RigidBodyType;
     /** Gravity scale of the rigid body */
     gravityScale: number;
     /** Linear damping value used to slow down movement over time */
@@ -50,19 +54,61 @@ export declare class RigidBody extends Component {
     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 contacts should only be resolved from one side */
+    oneWay: boolean;
+    /** Local-space normal that points toward the blocking side */
+    oneWayNormal?: Vector2;
     /**
      * Creates a new RigidBody component.
      * @param config - Configuration for the rigid body
      */
     constructor(config: RigidBodyConfig);
     get mass(): number;
+    /**
+     * Sets the mass used by dynamic bodies.
+     *
+     * Non-positive values make the body immovable by forces and impulses.
+     */
     set mass(value: number);
+    /**
+     * Returns the inverse mass.
+     *
+     * Bodies with zero or negative mass return `0`.
+     */
     get inverseMass(): number;
+    /**
+     * Adds a continuous force to a dynamic body for the next physics step.
+     *
+     * Affects only active dynamic bodies.
+     */
     applyForce(force: Vector2): void;
+    /**
+     * Adds an instantaneous impulse to a dynamic body for the next physics step.
+     *
+     * Affects only active dynamic bodies.
+     */
     applyImpulse(impulse: Vector2): void;
+    /**
+     * Marks the rigid body as awake so it can be simulated.
+     */
     wakeUp(): void;
+    /**
+     * Marks the rigid body as sleeping so dynamic integration can skip it.
+     */
     sleep(): void;
+    /**
+     * Clears all accumulated force and impulse values.
+     */
     clearForces(): void;
+    /**
+     * Moves a kinematic body to a target position on the next physics step.
+     *
+     * The physics system computes a one-step velocity from the current position
+     * to this target so contacts can react to the kinematic movement.
+     */
+    movePosition(position: Vector2): void;
 }

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

@@ -29,9 +29,10 @@ import { Vector2 } from '../../../engine/math-lib';
 export class RigidBody extends Component {
     _mass;
     _inverseMass;
-    /** Type of the rigid body */
+    /** @internal Pending one-step kinematic movement target */
+    _movementTarget;
+    /** Body type that defines how the rigid body participates in simulation */
     type;
-    /** Mass of the rigid body */
     /** Gravity scale of the rigid body */
     gravityScale;
     /** Linear damping value used to slow down movement over time */
@@ -42,8 +43,14 @@ export class RigidBody extends Component {
     disabled;
     /** Whether rigid body is sleeping */
     sleeping;
+    /** Force applied to the rigid body */
     force;
+    /** Impulse applied to the rigid body */
     impulse;
+    /** Whether contacts should only be resolved from one side */
+    oneWay;
+    /** Local-space normal that points toward the blocking side */
+    oneWayNormal;
     /**
      * Creates a new RigidBody component.
      * @param config - Configuration for the rigid body
@@ -52,49 +59,98 @@ export class RigidBody extends Component {
         super();
         this._mass = 0;
         this._inverseMass = 0;
+        this._movementTarget = null;
         this.type = config.type;
-        this.mass = config.mass;
-        this.gravityScale = config.gravityScale;
-        this.linearDamping = config.linearDamping;
+        this.mass = config.mass ?? 0;
+        this.gravityScale = config.gravityScale ?? 0;
+        this.linearDamping = config.linearDamping ?? 0;
         this.linearVelocity = new Vector2(0, 0);
         this.disabled = config.disabled;
         this.sleeping = false;
         this.force = new Vector2(0, 0);
         this.impulse = new Vector2(0, 0);
+        this.oneWay = config.oneWay ?? false;
+        if (this.oneWay) {
+            this.oneWayNormal = new Vector2(config.oneWayNormalX ?? 0, config.oneWayNormalY ?? 0).normalize();
+            if (this.oneWayNormal.magnitude === 0) {
+                throw new Error('One-way rigid body normal must be non-zero');
+            }
+        }
     }
     get mass() {
         return this._mass;
     }
+    /**
+     * Sets the mass used by dynamic bodies.
+     *
+     * Non-positive values make the body immovable by forces and impulses.
+     */
     set mass(value) {
         this._mass = value;
         this._inverseMass = value > 0 ? 1 / value : 0;
     }
+    /**
+     * Returns the inverse mass.
+     *
+     * Bodies with zero or negative mass return `0`.
+     */
     get inverseMass() {
         return this._inverseMass;
     }
+    /**
+     * Adds a continuous force to a dynamic body for the next physics step.
+     *
+     * Affects only active dynamic bodies.
+     */
     applyForce(force) {
-        if (this.disabled || this.type === 'static') {
+        if (this.disabled || this.type !== 'dynamic') {
             return;
         }
         this.wakeUp();
         this.force.add(force);
     }
+    /**
+     * Adds an instantaneous impulse to a dynamic body for the next physics step.
+     *
+     * Affects only active dynamic bodies.
+     */
     applyImpulse(impulse) {
-        if (this.disabled || this.type === 'static') {
+        if (this.disabled || this.type !== 'dynamic') {
             return;
         }
         this.wakeUp();
         this.impulse.add(impulse);
     }
+    /**
+     * Marks the rigid body as awake so it can be simulated.
+     */
     wakeUp() {
         this.sleeping = false;
     }
+    /**
+     * Marks the rigid body as sleeping so dynamic integration can skip it.
+     */
     sleep() {
         this.sleeping = true;
     }
+    /**
+     * Clears all accumulated force and impulse values.
+     */
     clearForces() {
         this.force.multiplyNumber(0);
         this.impulse.multiplyNumber(0);
     }
+    /**
+     * Moves a kinematic body to a target position on the next physics step.
+     *
+     * The physics system computes a one-step velocity from the current position
+     * to this target so contacts can react to the kinematic movement.
+     */
+    movePosition(position) {
+        if (this.disabled || this.type !== 'kinematic') {
+            return;
+        }
+        this._movementTarget = position.clone();
+    }
 }
 RigidBody.componentName = 'RigidBody';

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

@@ -56,6 +56,15 @@ export declare const CollisionStay = "CollisionStay";
  * @category Events
  */
 export declare const CollisionLeave = "CollisionLeave";
+/**
+ * Dispatched when a character body hits a blocking actor
+ *
+ * @event
+ * @type {CharacterHitEvent}
+ *
+ * @category Events
+ */
+export declare const CharacterHit = "CharacterHit";
 /**
  * Dispatched to play audio on an actor
  *
@@ -155,6 +164,25 @@ export type CollisionStayEvent = CollisionStateEvent;
  * @category Events
  */
 export type CollisionLeaveEvent = CollisionStateEvent;
+/** Event signature for the {@link CharacterHit} event
+ *
+ * @category Events
+ */
+export type CharacterHitEvent = ActorEvent<{
+    /** Actor hit by the character body */
+    actor: Actor;
+    /** Hit point in world space */
+    point: {
+        x: number;
+        y: number;
+    };
+    /** Hit normal pointing from the hit actor to the character */
+    normal: Vector2;
+    /** Distance from the cast origin to the hit */
+    distance: number;
+    /** Surface classification used by the character controller */
+    kind: 'ground' | 'wall' | 'ceiling';
+}>;
 /** Event signature for the {@link SetAudioVolume} event when used on actor level
  *
  * @category Events
@@ -174,6 +202,7 @@ declare module '../../types/events' {
         [CollisionEnter]: CollisionEnterEvent;
         [CollisionStay]: CollisionStayEvent;
         [CollisionLeave]: CollisionLeaveEvent;
+        [CharacterHit]: CharacterHitEvent;
         [PlayAudio]: ActorEvent;
         [StopAudio]: ActorEvent;
         [SetAudioVolume]: SetAudioSourceVolumeEvent;

package/build/contrib/events/index.js

@@ -52,6 +52,15 @@ export const CollisionStay = 'CollisionStay';
  * @category Events
  */
 export const CollisionLeave = 'CollisionLeave';
+/**
+ * Dispatched when a character body hits a blocking actor
+ *
+ * @event
+ * @type {CharacterHitEvent}
+ *
+ * @category Events
+ */
+export const CharacterHit = 'CharacterHit';
 /**
  * Dispatched to play audio on an actor
  *

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

@@ -0,0 +1,32 @@
+import { SceneSystem } from '../../../engine/system';
+import type { SceneSystemOptions, UpdateOptions } from '../../../engine/system';
+/**
+ * Kinematic character controller system with sweep/slide collision movement.
+ *
+ * The system expects actors to have `CharacterBody`, `Transform`,
+ * `Collider`, and a kinematic `RigidBody`. Put this system before
+ * `PhysicsSystem` in system configuration so `movePosition()` targets are
+ * consumed by physics in the same fixed step.
+ *
+ * @category Systems
+ */
+export declare class CharacterController extends SceneSystem {
+    private actorQuery;
+    private world;
+    private oneWayValidator;
+    constructor(options: SceneSystemOptions);
+    onSceneDestroy(): void;
+    private isBlockingHit;
+    private isWalkable;
+    private isRecoverableOverlap;
+    private resetGroundState;
+    private resetState;
+    private castAll;
+    private cast;
+    private castGround;
+    private recoverOverlaps;
+    private handleHit;
+    private move;
+    private updateGroundState;
+    fixedUpdate(options: UpdateOptions): void;
+}