dacha 0.18.0-alpha.4 → 0.18.0-alpha.6

package/build/contrib/components/audio-source/index.d.ts

@@ -30,7 +30,7 @@ export interface AudioSourceConfig {
  * audioSource.volume = 0.5; // Set volume to 50%
  *
  * // Play the audio
- * actor.dispatchEvent(PlayAudio);
+ * audioSource.playing = true;
  * ```
  *
  * @category Components

package/build/contrib/components/audio-source/index.js

@@ -23,7 +23,7 @@ import { Component } from '../../../engine/component';
  * audioSource.volume = 0.5; // Set volume to 50%
  *
  * // Play the audio
- * actor.dispatchEvent(PlayAudio);
+ * audioSource.playing = true;
  * ```
  *
  * @category Components

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

@@ -0,0 +1,72 @@
+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;
+    /** @internal Whether CharacterController should run overlap recovery */
+    _needsRecovery: boolean;
+    /** 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 when recovery is requested */
+    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;
+    /**
+     * Requests overlap depenetration on the next CharacterController update.
+     */
+    recover(): void;
+}

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

@@ -0,0 +1,90 @@
+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;
+    /** @internal Whether CharacterController should run overlap recovery */
+    _needsRecovery;
+    /** 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 when recovery is requested */
+    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._needsRecovery = true;
+        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);
+    }
+    /**
+     * Requests overlap depenetration on the next CharacterController update.
+     */
+    recover() {
+        this._needsRecovery = true;
+    }
+}
+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

@@ -57,32 +57,14 @@ export declare const CollisionStay = "CollisionStay";
  */
 export declare const CollisionLeave = "CollisionLeave";
 /**
- * Dispatched to play audio on an actor
+ * Dispatched when a character body hits a blocking actor
  *
  * @event
- * @type {ActorEvent}
+ * @type {CharacterHitEvent}
  *
  * @category Events
  */
-export declare const PlayAudio = "PlayAudio";
-/**
- * Dispatched to stop audio on an actor
- *
- * @event
- * @type {ActorEvent}
- *
- * @category Events
- */
-export declare const StopAudio = "StopAudio";
-/**
- * Dispatched to set audio volume
- *
- * @event
- * @type {SetAudioSourceVolumeEvent} (for actors) or {@link SetAudioGroupVolumeEvent} (for whole groups)
- *
- * @category Events
- */
-export declare const SetAudioVolume = "SetAudioVolume";
+export declare const CharacterHit = "CharacterHit";
 /** Event signature for the {@link MouseInput} event
  *
  * @category Events
@@ -103,16 +85,6 @@ export type GameStatsUpdateEvent = WorldEvent<{
     /** Current number of actors in the scene */
     actorsCount: number;
 }>;
-/** Event signature for the {@link SetAudioVolume} event when used on world level
- *
- * @category Events
- */
-export type SetAudioGroupVolumeEvent = WorldEvent<{
-    /** Audio group name to set volume for */
-    group: string;
-    /** Volume value (0.0 to 1.0) */
-    value: number;
-}>;
 /** Event signature for mouse control events
  *
  * @category Events
@@ -155,28 +127,36 @@ export type CollisionStayEvent = CollisionStateEvent;
  * @category Events
  */
 export type CollisionLeaveEvent = CollisionStateEvent;
-/** Event signature for the {@link SetAudioVolume} event when used on actor level
+/** Event signature for the {@link CharacterHit} event
  *
  * @category Events
  */
-export type SetAudioSourceVolumeEvent = ActorEvent<{
-    /** Volume value (0.0 to 1.0) */
-    value: number;
+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';
 }>;
 declare module '../../types/events' {
     interface WorldEventMap {
         [MouseInput]: MouseInputEvent;
         [KeyboardInput]: KeyboardInputEvent;
         [GameStatsUpdate]: GameStatsUpdateEvent;
-        [SetAudioVolume]: SetAudioGroupVolumeEvent;
     }
     interface ActorEventMap {
         [CollisionEnter]: CollisionEnterEvent;
         [CollisionStay]: CollisionStayEvent;
         [CollisionLeave]: CollisionLeaveEvent;
-        [PlayAudio]: ActorEvent;
-        [StopAudio]: ActorEvent;
-        [SetAudioVolume]: SetAudioSourceVolumeEvent;
+        [CharacterHit]: CharacterHitEvent;
     }
 }
 export {};

package/build/contrib/events/index.js

@@ -53,29 +53,11 @@ export const CollisionStay = 'CollisionStay';
  */
 export const CollisionLeave = 'CollisionLeave';
 /**
- * Dispatched to play audio on an actor
+ * Dispatched when a character body hits a blocking actor
  *
  * @event
- * @type {ActorEvent}
+ * @type {CharacterHitEvent}
  *
  * @category Events
  */
-export const PlayAudio = 'PlayAudio';
-/**
- * Dispatched to stop audio on an actor
- *
- * @event
- * @type {ActorEvent}
- *
- * @category Events
- */
-export const StopAudio = 'StopAudio';
-/**
- * Dispatched to set audio volume
- *
- * @event
- * @type {SetAudioSourceVolumeEvent} (for actors) or {@link SetAudioGroupVolumeEvent} (for whole groups)
- *
- * @category Events
- */
-export const SetAudioVolume = 'SetAudioVolume';
+export const CharacterHit = 'CharacterHit';

package/build/contrib/systems/audio-system/api.d.ts

@@ -0,0 +1,38 @@
+export interface AudioAPIHandlers {
+    getGroupVolume(group: string): number;
+    setGroupVolume(group: string, volume: number): void;
+}
+/**
+ * API that provides synchronous audio mixer controls.
+ *
+ * Actor playback is controlled through AudioSource component state.
+ * This API is intended for global audio state such as group and master volume.
+ *
+ * @category Systems
+ */
+export declare class AudioAPI {
+    private handlers;
+    constructor(handlers: AudioAPIHandlers);
+    /**
+     * Current master volume.
+     */
+    get masterVolume(): number;
+    /**
+     * Sets the master volume.
+     */
+    set masterVolume(volume: number);
+    /**
+     * Returns the volume for an audio group.
+     *
+     * @param group - Audio group name
+     * @returns Audio group volume
+     */
+    getGroupVolume(group: string): number;
+    /**
+     * Sets the volume for an audio group.
+     *
+     * @param group - Audio group name
+     * @param volume - New group volume
+     */
+    setGroupVolume(group: string, volume: number): void;
+}

package/build/contrib/systems/audio-system/api.js

@@ -0,0 +1,44 @@
+/**
+ * API that provides synchronous audio mixer controls.
+ *
+ * Actor playback is controlled through AudioSource component state.
+ * This API is intended for global audio state such as group and master volume.
+ *
+ * @category Systems
+ */
+export class AudioAPI {
+    handlers;
+    constructor(handlers) {
+        this.handlers = handlers;
+    }
+    /**
+     * Current master volume.
+     */
+    get masterVolume() {
+        return this.getGroupVolume('master');
+    }
+    /**
+     * Sets the master volume.
+     */
+    set masterVolume(volume) {
+        this.setGroupVolume('master', volume);
+    }
+    /**
+     * Returns the volume for an audio group.
+     *
+     * @param group - Audio group name
+     * @returns Audio group volume
+     */
+    getGroupVolume(group) {
+        return this.handlers.getGroupVolume(group);
+    }
+    /**
+     * Sets the volume for an audio group.
+     *
+     * @param group - Audio group name
+     * @param volume - New group volume
+     */
+    setGroupVolume(group, volume) {
+        this.handlers.setGroupVolume(group, volume);
+    }
+}

package/build/contrib/systems/audio-system/index.d.ts

@@ -25,13 +25,14 @@ export declare class AudioSystem extends WorldSystem {
     private loadAudio;
     private handleActorAdd;
     private handleActorRemove;
-    private handlePlayAudio;
-    private handleStopAudio;
-    private handleSetAudioVolume;
     private resumeIfSuspended;
+    private getGroup;
+    private getGroupVolume;
+    private setGroupVolume;
     private initAudio;
     private playAudio;
     private stopAudio;
     private updateAudio;
     update(): void;
 }
+export { AudioAPI } from './api';

package/build/contrib/systems/audio-system/index.js

@@ -1,9 +1,9 @@
 import { WorldSystem } from '../../../engine/system';
-import { Actor, ActorQuery } from '../../../engine/actor';
+import { ActorQuery } from '../../../engine/actor';
 import { AddActor, RemoveActor } from '../../../engine/events';
 import { CacheStore } from '../../../engine/data-lib';
 import { AudioSource } from '../../components';
-import { PlayAudio, StopAudio, SetAudioVolume } from '../../../events';
+import { AudioAPI } from './api';
 import { getAllSources, getAllTemplateSources, loadAudio } from './utils';
 const MASTER_GROUP = 'master';
 const VOLUME_TOLERANCE = 0.001;
@@ -44,9 +44,13 @@ export class AudioSystem extends WorldSystem {
         }, { [MASTER_GROUP]: masterAudioGroup });
         this.audioStore = new CacheStore();
         this.audioState = new Map();
-        this.world.addEventListener(PlayAudio, this.handlePlayAudio);
-        this.world.addEventListener(StopAudio, this.handleStopAudio);
-        this.world.addEventListener(SetAudioVolume, this.handleSetAudioVolume);
+        const audioApi = new AudioAPI({
+            getGroupVolume: (group) => this.getGroupVolume(group),
+            setGroupVolume: (group, volume) => {
+                this.setGroupVolume(group, volume);
+            },
+        });
+        this.world.systemApi.register(audioApi);
         window.addEventListener('click', this.resumeIfSuspended, { once: true });
         window.addEventListener('keydown', this.resumeIfSuspended, { once: true });
         window.addEventListener('touchstart', this.resumeIfSuspended, {
@@ -96,9 +100,6 @@ export class AudioSystem extends WorldSystem {
     }
     onWorldDestroy() {
         void this.audioContext.close();
-        this.world.removeEventListener(PlayAudio, this.handlePlayAudio);
-        this.world.removeEventListener(StopAudio, this.handleStopAudio);
-        this.world.removeEventListener(SetAudioVolume, this.handleSetAudioVolume);
         window.removeEventListener('click', this.resumeIfSuspended);
         window.removeEventListener('keydown', this.resumeIfSuspended);
         window.removeEventListener('touchstart', this.resumeIfSuspended);
@@ -129,28 +130,6 @@ export class AudioSystem extends WorldSystem {
         this.audioStore.release(src);
         this.stopAudio(actor);
     };
-    handlePlayAudio = (event) => {
-        this.playAudio(event.target);
-    };
-    handleStopAudio = (event) => {
-        this.stopAudio(event.target);
-    };
-    handleSetAudioVolume = (event) => {
-        if (event.target instanceof Actor) {
-            const audioSource = event.target.getComponent(AudioSource);
-            if (!audioSource) {
-                return;
-            }
-            audioSource.volume = event.value;
-        }
-        else {
-            const audioGroup = this.audioGroups[event.group];
-            if (!audioGroup) {
-                return;
-            }
-            audioGroup.gain.value = event.value;
-        }
-    };
     resumeIfSuspended = () => {
         if (this.audioContext.state === 'suspended') {
             void this.audioContext.resume().catch((err) => {
@@ -158,6 +137,19 @@ export class AudioSystem extends WorldSystem {
             });
         }
     };
+    getGroup(group) {
+        const audioGroup = this.audioGroups[group];
+        if (!audioGroup) {
+            throw new Error(`Can't find audio group with the following name: ${group}`);
+        }
+        return audioGroup;
+    }
+    getGroupVolume(group) {
+        return this.getGroup(group).gain.value;
+    }
+    setGroupVolume(group, volume) {
+        this.getGroup(group).gain.value = volume;
+    }
     initAudio(actor) {
         const audioSource = actor.getComponent(AudioSource);
         if (audioSource.autoplay) {
@@ -217,6 +209,7 @@ export class AudioSystem extends WorldSystem {
         if (Math.abs(audioSource.volume - audioState.properties.volume) >
             VOLUME_TOLERANCE) {
             audioState.gainNode.gain.value = audioSource.volume;
+            audioState.properties.volume = audioSource.volume;
         }
     }
     update() {
@@ -236,3 +229,4 @@ export class AudioSystem extends WorldSystem {
     }
 }
 AudioSystem.systemName = 'AudioSystem';
+export { AudioAPI } from './api';

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 cast;
+    private castMotion;
+    private castGround;
+    private recoverOverlaps;
+    private handleHit;
+    private move;
+    private updateGroundState;
+    fixedUpdate(options: UpdateOptions): void;
+}