dacha 0.18.0-alpha.9 → 0.18.1

package/build/contrib/components/bitmap-text/index.d.ts

@@ -8,17 +8,17 @@ interface RenderData {
 }
 type TextAlign = 'left' | 'center' | 'right';
 export interface BitmapTextConfig {
-    text: string;
-    font: string;
-    fontSize: number;
-    align: TextAlign;
-    color: string;
-    opacity: number;
-    blending: BlendingMode;
-    disabled: boolean;
-    sortingLayer: string;
-    sortOffsetX: number;
-    sortOffsetY: number;
+    text?: string;
+    font?: string;
+    fontSize?: number;
+    align?: TextAlign;
+    color?: string;
+    opacity?: number;
+    blending?: BlendingMode;
+    disabled?: boolean;
+    sortingLayer?: string;
+    sortOffsetX?: number;
+    sortOffsetY?: number;
 }
 /**
  * BitmapText component for rendering text using a bitmap font.

package/build/contrib/components/bitmap-text/index.js

@@ -60,16 +60,19 @@ export class BitmapText extends Component {
     renderData;
     constructor(config) {
         super();
-        this.text = config.text;
-        this.font = config.font;
-        this.fontSize = config.fontSize;
-        this.align = config.align;
-        this.color = config.color;
-        this.opacity = config.opacity;
-        this.blending = config.blending;
-        this.disabled = config.disabled;
-        this.sortingLayer = config.sortingLayer;
-        this.sortOffset = { x: config.sortOffsetX, y: config.sortOffsetY };
+        this.text = config.text ?? 'Text';
+        this.font = config.font ?? '';
+        this.fontSize = config.fontSize ?? 10;
+        this.align = config.align ?? 'center';
+        this.color = config.color ?? '#000000';
+        this.opacity = config.opacity ?? 1;
+        this.blending = config.blending ?? 'normal';
+        this.disabled = config.disabled ?? false;
+        this.sortingLayer = config.sortingLayer ?? 'default';
+        this.sortOffset = {
+            x: config.sortOffsetX ?? 0,
+            y: config.sortOffsetY ?? 0,
+        };
     }
 }
 BitmapText.componentName = 'BitmapText';

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/mesh/index.d.ts

@@ -13,20 +13,20 @@ export interface MaterialConfig {
     options: Record<string, unknown>;
 }
 export interface MeshConfig {
-    src: string;
-    width: number;
-    height: number;
-    slice: number;
-    flipX: boolean;
-    flipY: boolean;
-    sortingLayer: string;
-    sortOffsetX: number;
-    sortOffsetY: number;
-    color: string;
-    blending: BlendingMode;
-    opacity: number;
+    src?: string;
+    width?: number;
+    height?: number;
+    slice?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    sortingLayer?: string;
+    sortOffsetX?: number;
+    sortOffsetY?: number;
+    color?: string;
+    blending?: BlendingMode;
+    opacity?: number;
     material?: MaterialConfig;
-    disabled: boolean;
+    disabled?: boolean;
 }
 /**
  * Mesh component for rendering 2D textures with a custom shader.

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

@@ -78,16 +78,19 @@ export class Mesh extends Component {
      */
     constructor(config) {
         super();
-        this.src = config.src;
-        this.width = config.width;
-        this.height = config.height;
-        this.slice = config.slice;
+        this.src = config.src ?? '';
+        this.width = config.width ?? 10;
+        this.height = config.height ?? 10;
+        this.slice = config.slice ?? 1;
         this.currentFrame = 0;
-        this.flipX = config.flipX;
-        this.flipY = config.flipY;
-        this.disabled = config.disabled;
-        this.sortingLayer = config.sortingLayer;
-        this.sortOffset = { x: config.sortOffsetX, y: config.sortOffsetY };
+        this.flipX = config.flipX ?? false;
+        this.flipY = config.flipY ?? false;
+        this.disabled = config.disabled ?? false;
+        this.sortingLayer = config.sortingLayer ?? 'default';
+        this.sortOffset = {
+            x: config.sortOffsetX ?? 0,
+            y: config.sortOffsetY ?? 0,
+        };
         this.color = config.color ?? '#ffffff';
         this.blending = config.blending ?? 'normal';
         this.opacity = config.opacity ?? 1;

package/build/contrib/components/pixi-view/index.d.ts

@@ -5,10 +5,10 @@ interface RenderData {
     view: ViewContainer;
 }
 export interface PixiViewConfig {
-    createView: () => ViewContainer;
-    sortingLayer: string;
-    sortOffsetX: number;
-    sortOffsetY: number;
+    createView?: () => ViewContainer;
+    sortingLayer?: string;
+    sortOffsetX?: number;
+    sortOffsetY?: number;
 }
 /**
  * PixiView component for rendering a view.
@@ -41,7 +41,7 @@ export interface PixiViewConfig {
  */
 export declare class PixiView extends Component {
     /** Function to create a custom pixi.js view */
-    createView: () => ViewContainer;
+    createView?: () => ViewContainer;
     /** Sorting layer of the pixi view */
     sortingLayer: string;
     /** Center point of the pixi view */

package/build/contrib/components/pixi-view/index.js

@@ -45,8 +45,11 @@ export class PixiView extends Component {
     constructor(config) {
         super();
         this.createView = config.createView;
-        this.sortingLayer = config.sortingLayer;
-        this.sortOffset = { x: config.sortOffsetX, y: config.sortOffsetY };
+        this.sortingLayer = config.sortingLayer ?? 'default';
+        this.sortOffset = {
+            x: config.sortOffsetX ?? 0,
+            y: config.sortOffsetY ?? 0,
+        };
     }
     /** Get the pixi.js view. It's only available after the actor with this component is added to a scene */
     get view() {

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

@@ -31,6 +31,13 @@ interface PointImpulse {
  * 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
  * // Create a dynamic rigid body
@@ -115,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);

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

@@ -7,6 +7,13 @@ import { Vector2 } from '../../../engine/math-lib';
  * 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
  * // Create a dynamic rigid body
@@ -134,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) {

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

@@ -9,45 +9,29 @@ interface RenderData {
 export type ShapeType = 'rectangle' | 'roundRectangle' | 'circle' | 'ellipse' | 'line';
 export interface BaseShapeConfig {
     strokeColor?: string;
-    strokeWidth: number;
-    strokeAlignment: number;
-    pixelLine: boolean;
+    strokeWidth?: number;
+    strokeAlignment?: number;
+    pixelLine?: boolean;
     fill?: string;
-    opacity: number;
-    blending: BlendingMode;
-    disabled: boolean;
-    sortingLayer: string;
-    sortOffsetX: number;
-    sortOffsetY: number;
-}
-export interface RectangleShapeConfig extends BaseShapeConfig {
-    type: 'rectangle';
-    sizeX: number;
-    sizeY: number;
+    opacity?: number;
+    blending?: BlendingMode;
+    disabled?: boolean;
+    sortingLayer?: string;
+    sortOffsetX?: number;
+    sortOffsetY?: number;
 }
-export interface RoundRectangleShapeConfig extends BaseShapeConfig {
-    type: 'roundRectangle';
-    sizeX: number;
-    sizeY: number;
-    radius: number;
-}
-export interface CircleShapeConfig extends BaseShapeConfig {
-    type: 'circle';
-    radius: number;
-}
-export interface EllipseShapeConfig extends BaseShapeConfig {
-    type: 'ellipse';
-    radiusX: number;
-    radiusY: number;
-}
-export interface LineShapeConfig extends BaseShapeConfig {
-    type: 'line';
-    point1X: number;
-    point1Y: number;
-    point2X: number;
-    point2Y: number;
+export interface ShapeConfig extends BaseShapeConfig {
+    type?: ShapeType;
+    sizeX?: number;
+    sizeY?: number;
+    radius?: number;
+    radiusX?: number;
+    radiusY?: number;
+    point1X?: number;
+    point1Y?: number;
+    point2X?: number;
+    point2Y?: number;
 }
-export type ShapeConfig = RectangleShapeConfig | RoundRectangleShapeConfig | CircleShapeConfig | EllipseShapeConfig | LineShapeConfig;
 export interface RectangleShapeGeometry {
     type: 'rectangle';
     size: Point;

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

@@ -71,47 +71,51 @@ export class Shape extends Component {
      */
     constructor(config) {
         super();
-        this.strokeColor = config.strokeColor;
-        this.strokeWidth = config.strokeWidth;
-        this.strokeAlignment = config.strokeAlignment;
-        this.pixelLine = config.pixelLine;
-        this.fill = config.fill;
-        this.opacity = config.opacity;
-        this.blending = config.blending;
-        this.disabled = config.disabled;
-        this.sortingLayer = config.sortingLayer;
-        this.sortOffset = { x: config.sortOffsetX, y: config.sortOffsetY };
-        switch (config.type) {
+        this.strokeColor = config.strokeColor ?? '#ffffff';
+        this.strokeWidth = config.strokeWidth ?? 0;
+        this.strokeAlignment = config.strokeAlignment ?? 0.5;
+        this.pixelLine = config.pixelLine ?? false;
+        this.fill = config.fill ?? '#ffffff';
+        this.opacity = config.opacity ?? 1;
+        this.blending = config.blending ?? 'normal';
+        this.disabled = config.disabled ?? false;
+        this.sortingLayer = config.sortingLayer ?? 'default';
+        this.sortOffset = {
+            x: config.sortOffsetX ?? 0,
+            y: config.sortOffsetY ?? 0,
+        };
+        const type = config.type ?? 'rectangle';
+        switch (type) {
             case 'rectangle':
                 this.geometry = {
-                    type: config.type,
-                    size: { x: config.sizeX, y: config.sizeY },
+                    type,
+                    size: { x: config.sizeX ?? 10, y: config.sizeY ?? 10 },
                 };
                 break;
             case 'roundRectangle':
                 this.geometry = {
-                    type: config.type,
-                    size: { x: config.sizeX, y: config.sizeY },
-                    radius: config.radius,
+                    type,
+                    size: { x: config.sizeX ?? 10, y: config.sizeY ?? 10 },
+                    radius: config.radius ?? 2,
                 };
                 break;
             case 'circle':
                 this.geometry = {
-                    type: config.type,
-                    radius: config.radius,
+                    type,
+                    radius: config.radius ?? 5,
                 };
                 break;
             case 'ellipse':
                 this.geometry = {
-                    type: config.type,
-                    radius: { x: config.radiusX, y: config.radiusY },
+                    type,
+                    radius: { x: config.radiusX ?? 5, y: config.radiusY ?? 5 },
                 };
                 break;
             case 'line':
                 this.geometry = {
-                    type: config.type,
-                    point1: { x: config.point1X, y: config.point1Y },
-                    point2: { x: config.point2X, y: config.point2Y },
+                    type,
+                    point1: { x: config.point1X ?? -5, y: config.point1Y ?? 0 },
+                    point2: { x: config.point2X ?? 5, y: config.point2Y ?? 0 },
                 };
         }
     }

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

@@ -10,20 +10,22 @@ interface RenderData {
 type FitType = 'stretch' | 'repeat';
 export { type BlendingMode } from '../../types/view';
 export interface SpriteConfig {
-    src: string;
-    width: number;
-    height: number;
-    slice: number;
-    flipX: boolean;
-    flipY: boolean;
-    sortingLayer: string;
-    sortOffsetX: number;
-    sortOffsetY: number;
-    fit: FitType;
-    color: string;
-    blending: BlendingMode;
-    opacity: number;
-    disabled: boolean;
+    src?: string;
+    width?: number;
+    height?: number;
+    slice?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    sortingLayer?: string;
+    sortOffsetX?: number;
+    sortOffsetY?: number;
+    textureOffsetX?: number;
+    textureOffsetY?: number;
+    fit?: FitType;
+    color?: string;
+    blending?: BlendingMode;
+    opacity?: number;
+    disabled?: boolean;
 }
 /**
  * Sprite component for rendering 2D textures.
@@ -80,6 +82,12 @@ export declare class Sprite extends Component {
     sortingLayer: string;
     /** Center point for sorting calculations */
     sortOffset: Point;
+    /**
+     * Texture sampling offset in pixels. Only applies to `fit: 'repeat'`
+     * With flipX/flipY the tile is mirrored, so a positive offset scrolls in
+     * the mirrored direction.
+     */
+    textureOffset: Point;
     /** Current frame to render */
     currentFrame?: number;
     /** How the texture should fit within the sprite bounds */

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

@@ -54,6 +54,12 @@ export class Sprite extends Component {
     sortingLayer;
     /** Center point for sorting calculations */
     sortOffset;
+    /**
+     * Texture sampling offset in pixels. Only applies to `fit: 'repeat'`
+     * With flipX/flipY the tile is mirrored, so a positive offset scrolls in
+     * the mirrored direction.
+     */
+    textureOffset;
     /** Current frame to render */
     currentFrame;
     /** How the texture should fit within the sprite bounds */
@@ -73,17 +79,24 @@ export class Sprite extends Component {
      */
     constructor(config) {
         super();
-        this.src = config.src;
-        this.width = config.width;
-        this.height = config.height;
-        this.slice = config.slice;
+        this.src = config.src ?? '';
+        this.width = config.width ?? 10;
+        this.height = config.height ?? 10;
+        this.slice = config.slice ?? 1;
         this.currentFrame = 0;
-        this.flipX = config.flipX;
-        this.flipY = config.flipY;
-        this.disabled = config.disabled;
-        this.sortingLayer = config.sortingLayer;
-        this.sortOffset = { x: config.sortOffsetX, y: config.sortOffsetY };
-        this.fit = config.fit;
+        this.flipX = config.flipX ?? false;
+        this.flipY = config.flipY ?? false;
+        this.disabled = config.disabled ?? false;
+        this.sortingLayer = config.sortingLayer ?? 'default';
+        this.sortOffset = {
+            x: config.sortOffsetX ?? 0,
+            y: config.sortOffsetY ?? 0,
+        };
+        this.textureOffset = {
+            x: config.textureOffsetX ?? 0,
+            y: config.textureOffsetY ?? 0,
+        };
+        this.fit = config.fit ?? 'stretch';
         this.color = config.color ?? '#ffffff';
         this.blending = config.blending ?? 'normal';
         this.opacity = config.opacity ?? 1;

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

@@ -4,6 +4,8 @@ export { GameStatsMeter } from './game-stats-meter';
 export { KeyboardInputSystem } from './keyboard-input-system';
 export { KeyboardControlSystem } from './keyboard-control-system';
 export { CharacterController } from './character-controller';
+export { Interpolator, InterpolatorAPI } from './interpolator';
+export type { RenderTransform } from './interpolator';
 export { MouseControlSystem } from './mouse-control-system';
 export { MouseInputSystem } from './mouse-input-system';
 export { PhysicsSystem, PhysicsAPI } from './physics-system';