dacha 0.18.0-alpha.4 → 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

@@ -11,24 +11,24 @@ export interface BaseColliderConfig {
 }
 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';
-    height: number;
-    radius: number;
+    height?: number;
+    radius?: number;
 }
 export type ColliderConfig = BoxColliderConfig | CircleColliderConfig | SegmentColliderConfig | CapsuleColliderConfig;
 export interface BoxColliderShape {

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

@@ -50,27 +50,27 @@ export class Collider extends Component {
             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,
-                    height: config.height,
-                    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/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;
+}

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

@@ -0,0 +1,262 @@
+import { ActorQuery } from '../../../engine/actor';
+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 { clipAgainstNormal } from './utils';
+const DISTANCE_EPSILON = 0.000001;
+const SNAP_EPSILON = 0.000001;
+/**
+ * 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 class CharacterController extends SceneSystem {
+    actorQuery;
+    world;
+    oneWayValidator;
+    constructor(options) {
+        super();
+        this.world = options.world;
+        this.actorQuery = new ActorQuery({
+            scene: options.scene,
+            filter: [CharacterBody, Transform, Collider, RigidBody],
+        });
+        this.oneWayValidator = new OneWayValidator();
+    }
+    onSceneDestroy() {
+        this.actorQuery.destroy();
+    }
+    isBlockingHit(actor, hit) {
+        const rigidBody = hit.actor.getComponent(RigidBody);
+        if (!rigidBody || rigidBody.disabled) {
+            return false;
+        }
+        if (!rigidBody?.oneWay || !rigidBody.oneWayNormal) {
+            return true;
+        }
+        return this.oneWayValidator.validate(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) {
+        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);
+    }
+    resetGroundState(character) {
+        if (character.onGround) {
+            character.groundActor = null;
+            character.groundNormal = character.upDirection.clone();
+            character.onGround = false;
+        }
+    }
+    resetState(character) {
+        this.resetGroundState(character);
+        character.onWall = false;
+        character.onCeiling = false;
+    }
+    castAll(actor, position, displacement) {
+        const physicsApi = this.world.systemApi.get(PhysicsAPI);
+        const character = actor.getComponent(CharacterBody);
+        const transform = actor.getComponent(Transform);
+        const distance = displacement.magnitude;
+        if (distance <= DISTANCE_EPSILON) {
+            return [];
+        }
+        return physicsApi.castActorAll({
+            actor,
+            offset: {
+                x: position.x - transform.world.position.x,
+                y: position.y - transform.world.position.y,
+            },
+            direction: displacement,
+            maxDistance: distance + character.skinWidth,
+        });
+    }
+    cast(actor, position, displacement) {
+        const hits = this.castAll(actor, position, displacement);
+        for (const hit of hits) {
+            if (hit.distance <= DISTANCE_EPSILON &&
+                VectorOps.dotProduct(displacement, hit.normal) > DISTANCE_EPSILON) {
+                continue;
+            }
+            if (this.isBlockingHit(actor, hit)) {
+                return hit;
+            }
+        }
+        return null;
+    }
+    castGround(actor, position, displacement) {
+        const hits = this.castAll(actor, position, displacement);
+        for (const hit of hits) {
+            if (this.isBlockingHit(actor, hit) &&
+                this.isWalkable(actor, hit.normal)) {
+                return hit;
+            }
+        }
+        return null;
+    }
+    recoverOverlaps(actor, position) {
+        const physicsApi = this.world.systemApi.get(PhysicsAPI);
+        const character = actor.getComponent(CharacterBody);
+        const transform = actor.getComponent(Transform);
+        for (let i = 0; i < character.maxRecoveries; i += 1) {
+            const hits = physicsApi.overlapActor({
+                actor,
+                offset: {
+                    x: position.x - transform.world.position.x,
+                    y: position.y - transform.world.position.y,
+                },
+            });
+            let recovered = false;
+            for (const hit of hits) {
+                if (!this.isRecoverableOverlap(actor, hit)) {
+                    continue;
+                }
+                const correction = hit.penetration + character.skinWidth;
+                if (correction <= DISTANCE_EPSILON) {
+                    continue;
+                }
+                position.x += hit.normal.x * correction;
+                position.y += hit.normal.y * correction;
+                recovered = true;
+            }
+            if (!recovered) {
+                break;
+            }
+        }
+    }
+    handleHit(actor, hit) {
+        const character = actor.getComponent(CharacterBody);
+        let kind;
+        if (character.motionMode === 'surface') {
+            const upDot = VectorOps.dotProduct(hit.normal, character.upDirection);
+            const threshold = Math.cos(character.maxSlopeAngle);
+            if (upDot >= threshold) {
+                kind = 'ground';
+                character.onGround = true;
+                character.groundNormal = hit.normal;
+                character.groundActor = hit.actor;
+            }
+            else if (upDot <= -threshold) {
+                kind = 'ceiling';
+                character.onCeiling = true;
+            }
+            else {
+                kind = 'wall';
+                character.onWall = true;
+            }
+        }
+        else {
+            kind = 'wall';
+            character.onWall = true;
+        }
+        actor.dispatchEvent(CharacterHit, {
+            actor: hit.actor,
+            point: hit.point,
+            normal: hit.normal,
+            distance: hit.distance,
+            kind,
+        });
+    }
+    move(actor, position, displacement) {
+        const character = actor.getComponent(CharacterBody);
+        for (let i = 0; i < character.maxSlides; i += 1) {
+            const distance = displacement.magnitude;
+            if (distance <= DISTANCE_EPSILON) {
+                break;
+            }
+            const hit = this.cast(actor, position, displacement);
+            if (!hit) {
+                position.add(displacement);
+                break;
+            }
+            const safeDistance = Math.max(hit.distance - character.skinWidth, 0);
+            const direction = displacement.clone().normalize();
+            position.x += direction.x * safeDistance;
+            position.y += direction.y * safeDistance;
+            this.handleHit(actor, hit);
+            clipAgainstNormal(character.velocity, hit.normal);
+            const remainingDistance = Math.max(distance - safeDistance, 0);
+            displacement.x = direction.x * remainingDistance;
+            displacement.y = direction.y * remainingDistance;
+            clipAgainstNormal(displacement, hit.normal);
+        }
+    }
+    updateGroundState(actor, target, skipSnapping) {
+        const character = actor.getComponent(CharacterBody);
+        if (skipSnapping) {
+            this.resetGroundState(character);
+            return;
+        }
+        const probeDistance = Math.max(character.groundSnapDistance, character.skinWidth);
+        const probeDirection = character.upDirection
+            .clone()
+            .multiplyNumber(-probeDistance);
+        const hit = this.castGround(actor, target, probeDirection);
+        if (!hit) {
+            this.resetGroundState(character);
+            return;
+        }
+        character.onGround = true;
+        character.groundNormal = hit.normal;
+        character.groundActor = hit.actor;
+        const snapDistance = Math.max(hit.distance - character.skinWidth, 0);
+        const snapDirection = character.upDirection
+            .clone()
+            .multiplyNumber(-snapDistance);
+        target.x += snapDirection.x;
+        target.y += snapDirection.y;
+    }
+    fixedUpdate(options) {
+        if (!this.world.systemApi.has(PhysicsAPI)) {
+            return;
+        }
+        const deltaTimeInSeconds = options.deltaTime / 1000;
+        this.oneWayValidator.update();
+        this.actorQuery.getActors().forEach((actor) => {
+            const transform = actor.getComponent(Transform);
+            const character = actor.getComponent(CharacterBody);
+            const rigidBody = actor.getComponent(RigidBody);
+            const collider = actor.getComponent(Collider);
+            this.resetState(character);
+            if (character.disabled ||
+                rigidBody.disabled ||
+                collider.disabled ||
+                rigidBody.type !== 'kinematic') {
+                character._displacement.multiplyNumber(0);
+                return;
+            }
+            const displacement = character.velocity
+                .clone()
+                .multiplyNumber(deltaTimeInSeconds)
+                .add(character._displacement);
+            const movingUp = VectorOps.dotProduct(displacement, character.upDirection) >
+                SNAP_EPSILON;
+            const position = new Vector2(transform.world.position.x, transform.world.position.y);
+            this.recoverOverlaps(actor, position);
+            this.move(actor, position, displacement);
+            this.updateGroundState(actor, position, movingUp || character.motionMode === 'free');
+            rigidBody.movePosition(position);
+            character._displacement.multiplyNumber(0);
+        });
+        this.oneWayValidator.lateUpdate();
+    }
+}
+CharacterController.systemName = 'CharacterController';

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

@@ -0,0 +1,2 @@
+import { type Point } from '../../../engine/math-lib';
+export declare const clipAgainstNormal: (vector: Point, normal: Point) => void;

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

@@ -0,0 +1,9 @@
+import { VectorOps } from '../../../engine/math-lib';
+export const clipAgainstNormal = (vector, normal) => {
+    const dot = VectorOps.dotProduct(vector, normal);
+    if (dot >= 0) {
+        return;
+    }
+    vector.x -= normal.x * dot;
+    vector.y -= normal.y * dot;
+};

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

@@ -3,6 +3,7 @@ export { CameraSystem, CameraAPI } from './camera-system';
 export { GameStatsMeter } from './game-stats-meter';
 export { KeyboardInputSystem } from './keyboard-input-system';
 export { KeyboardControlSystem } from './keyboard-control-system';
+export { CharacterController } from './character-controller';
 export { MouseControlSystem } from './mouse-control-system';
 export { MouseInputSystem } from './mouse-input-system';
 export { PhysicsSystem, PhysicsAPI } from './physics-system';

package/build/contrib/systems/index.js

@@ -3,6 +3,7 @@ export { CameraSystem, CameraAPI } from './camera-system';
 export { GameStatsMeter } from './game-stats-meter';
 export { KeyboardInputSystem } from './keyboard-input-system';
 export { KeyboardControlSystem } from './keyboard-control-system';
+export { CharacterController } from './character-controller';
 export { MouseControlSystem } from './mouse-control-system';
 export { MouseInputSystem } from './mouse-input-system';
 export { PhysicsSystem, PhysicsAPI } from './physics-system';