nexus-2d 0.0.1 → 0.0.3

package/dist/types/engine/charactercontroller.d.ts

@@ -0,0 +1,235 @@
+/**
+ * CharacterController2D - Kinematic character with tight controls
+ *
+ * Why kinematic not dynamic:
+ * - Physics forces feel floaty (acceleration, momentum)
+ * - We want instant response (press right → move right)
+ * - Still get collision detection from physics
+ *
+ * Game feel features:
+ * - Coyote time (jump grace period)
+ * - Jump buffering (early jump input)
+ * - Variable jump height
+ * - Acceleration curves
+ * - Air control
+ *
+ * Common use case: 2D platformer character
+ */
+export class CharacterController2D extends RigidBody2D {
+    constructor(name: any, options?: {});
+    activeCollisions: Set<any>;
+    collisionData: Map<any, any>;
+    onCollisionEnter: (other: any, pair: any) => void;
+    onCollisionStay: (other: any, pair: any) => void;
+    onCollisionExit: (other: any, pair: any) => void;
+    speed: any;
+    acceleration: any;
+    friction: any;
+    airAcceleration: any;
+    airFriction: any;
+    jumpForce: any;
+    gravity: any;
+    maxFallSpeed: any;
+    jumpCutMultiplier: any;
+    coyoteTime: any;
+    jumpBufferTime: any;
+    coyoteTimer: number;
+    jumpBufferTimer: number;
+    velocity: {
+        x: number;
+        y: number;
+    };
+    grounded: boolean;
+    wasGrounded: boolean;
+    jumping: boolean;
+    state: string;
+    moveInput: number;
+    jumpPressed: boolean;
+    jumpHeld: boolean;
+    jumpReleased: boolean;
+    groundCheckDistance: number;
+    wallCheckDistance: number;
+    onJump: any;
+    onLand: any;
+    onWallHit: any;
+    spriteNode: Sprite | AnimatedSprite;
+    animatedSprite: any;
+    collisionWidth: any;
+    collisionHeight: any;
+    collisionPaddingX: any;
+    collisionPaddingY: any;
+    debugDraw: any;
+    debugColor: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    /**
+   * Setup sprite and auto-configure collision from sprite dimensions
+   *
+   * @param {Sprite|AnimatedSprite} sprite - Sprite to attach
+   */
+    setupSprite(sprite: Sprite | AnimatedSprite): void;
+    /**
+ * Create collision box
+ *
+ * Uses collisionWidth/Height which are either:
+ * - Auto-calculated from sprite
+ * - Manually specified in options
+ */
+    setupCollision(): void;
+    /**
+ * Setup animation state machine hooks
+ *
+ * Automatically plays animations based on controller state
+ */
+    setupAnimations(animatedSprite: any): void;
+    prevState: any;
+    /**
+   * Update animations based on state
+   *
+   * Called automatically in _process if sprite is AnimatedSprite
+   */
+    updateAnimations(): void;
+    /**
+   * Map controller state to animation name
+   *
+   * Override this in subclasses for custom animation mappings
+   */
+    getAnimationForState(state: any): any;
+    /**
+ * Manually check collisions using Matter.Query
+ *
+ * Since kinematic (static) bodies don't fire collision events with other static bodies,
+ * we need to manually query the physics world
+ */
+    checkCollisionsManually(): any;
+    /**
+     * Resolve collisions using manual query results
+     */
+    resolveCollisions(): void;
+    /**
+     * Slide velocity along collision surface
+     */
+    slideVelocity(normal: any, pushDir: any): void;
+    /**
+     * Check grounded using manual collision detection
+     */
+    checkGrounded(): void;
+    /**
+     * Update game feel timers
+     */
+    updateTimers(delta: any): void;
+    handleCollisionEnter(other: any, pair: any): void;
+    handleCollisionStay(other: any, pair: any): void;
+    handleCollisionExit(other: any, pair: any): void;
+    /**
+     * Handle horizontal movement
+     *
+     * Features:
+     * - Instant direction change (no momentum)
+     * - Smooth acceleration to max speed
+     * - Different air/ground acceleration
+     */
+    handleMovement(delta: any): void;
+    /**
+     * Handle jump input with game feel tricks
+     *
+     * Coyote time: Can jump slightly after leaving platform
+     * Jump buffer: Jump input remembered for short time
+     * Variable height: Release jump early = shorter jump
+     */
+    handleJump(delta: any): void;
+    /**
+     * Apply gravity
+     */
+    applyGravity(delta: any): void;
+    /**
+     * Update state machine
+     *
+     * States: idle, walk, jump, fall
+     * Used for animation selection
+     */
+    updateState(): void;
+    /**
+     * Set move input from external system
+     *
+     * @param {number} direction - -1 (left), 0 (none), 1 (right)
+     */
+    setMoveInput(direction: number): void;
+    /**
+     * Set jump input from external system
+     *
+     * @param {boolean} pressed - Jump pressed this frame
+     * @param {boolean} held - Jump held
+     * @param {boolean} released - Jump released this frame
+     */
+    setJumpInput(pressed: boolean, held: boolean, released: boolean): void;
+}
+/**
+ * InputController - bridges tessera.js InputMap to CharacterController2D
+ *
+ * Why separate:
+ * - CharacterController doesn't know about input systems
+ * - Can swap input sources (keyboard, gamepad, AI, replay)
+ * - Easier to test (mock input)
+ */
+export class CharacterInputController {
+    constructor(character: any, inputMap: any);
+    character: any;
+    inputMap: any;
+    prevJumpHeld: boolean;
+    /**
+     * Update character from input - call every frame
+     */
+    update(): void;
+}
+/**
+ * TopDownController - 8-directional movement (no jumping)
+ *
+ * For: top-down action games, twin-stick shooters
+ */
+export class TopDownController extends RigidBody2D {
+    constructor(name: any, options?: {});
+    speed: any;
+    acceleration: any;
+    friction: any;
+    velocity: {
+        x: number;
+        y: number;
+    };
+    moveInput: {
+        x: number;
+        y: number;
+    };
+    canDash: any;
+    dashSpeed: any;
+    dashDuration: any;
+    dashCooldown: any;
+    isDashing: boolean;
+    dashTimer: number;
+    dashCooldownTimer: number;
+    dashDirection: {
+        x: number;
+        y: number;
+    };
+    handleMovement(delta: any): void;
+    /**
+     * Execute dash
+     */
+    dash(): boolean;
+    setMoveInput(x: any, y: any): void;
+}
+/**
+ * TopDownInputController - for TopDownController
+ */
+export class TopDownInputController {
+    constructor(character: any, inputMap: any);
+    character: any;
+    inputMap: any;
+    prevDashHeld: boolean;
+    update(): void;
+}
+import { RigidBody2D } from './physics.js';
+import { Sprite } from './sprite.js';
+import { AnimatedSprite } from './sprite.js';

package/dist/types/engine/controllers.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Base Controller - all camera behaviors inherit from this
+ * Why a base class: provides common lifecycle methods and state management
+ */
+export class CameraController {
+    constructor(name?: string);
+    name: string;
+    enabled: boolean;
+    priority: number;
+    camera: any;
+    weight: number;
+    attach(camera: any): void;
+    detach(): void;
+    onAttach(): void;
+    onDetach(): void;
+    onUpdate(delta: any): boolean;
+    preUpdate(delta: any): void;
+    postUpdate(delta: any): void;
+}
+/**
+ * FollowController - smoothly follows a target
+ * Key features:
+ * - Lag/smoothing with lerp
+ * - Deadzone (camera only moves when target leaves center area)
+ * - Look-ahead (predictive movement)
+ * - Boundaries (clamp to level limits)
+ */
+/**
+ * Optimized FollowController with smooth lerping
+ *
+ * Key improvements:
+ * - Smooth lerp towards target center (no harsh deadzone snapping)
+ * - Optional soft deadzone for reduced movement near center
+ * - Simplified calculations, fewer conversions
+ * - Better performance with early exits
+ */
+export class FollowController extends CameraController {
+    constructor(target: any, options?: {});
+    target: any;
+    smoothing: any;
+    softDeadzoneRadius: any;
+    softDeadzoneFalloff: any;
+    offset: any;
+    bounds: any;
+    smoothingX: any;
+    smoothingY: any;
+    minMovement: any;
+}
+/**
+ * ShakeController - screen shake for impacts, explosions, etc.
+ * Key features:
+ * - Perlin-like noise for natural shaking
+ * - Decay over time
+ * - Configurable intensity and frequency
+ * - Can shake position, rotation, or both
+ */
+export class ShakeController extends CameraController {
+    constructor(options?: {});
+    intensity: any;
+    decay: any;
+    frequency: any;
+    shakePosition: boolean;
+    shakeRotation: any;
+    maxRotation: any;
+    time: number;
+    seed: number;
+    currentIntensity: number;
+    offset: {
+        x: number;
+        y: number;
+    };
+    rotationOffset: number;
+    octaves: any;
+    persistence: any;
+    shake(intensity?: any): void;
+    _perlinNoise(seed: any, t: any): number;
+}
+/**
+ * ZoomController - smooth zoom interpolation
+ * Key features:
+ * - Animated zoom to target level
+ * - Zoom to fit specific bounds
+ * - Zoom with pivot point (mouse position)
+ */
+export class ZoomController extends CameraController {
+    constructor(options?: {});
+    targetZoom: any;
+    smoothing: any;
+    minZoom: any;
+    maxZoom: any;
+    zoomToFitPadding: any;
+    isZooming: boolean;
+    zoomStart: number;
+    zoomTime: number;
+    zoomDuration: number;
+    easingFunc: (t: any) => any;
+    pivot: any;
+    zoomTo(zoomLevel: any, duration?: number, easing?: string, pivot?: any): void;
+    zoomToFit(bounds: any, duration?: number, easing?: string): void;
+    zoomBy(factor: any, duration?: number, easing?: string, pivot?: any): void;
+    _getEasingFunction(name: any): (t: any) => any;
+}
+/**
+ * PathController - follow a Bézier path for cinematic sequences
+ * Key features:
+ * - Follow sequence of control points
+ * - Configurable speed and easing
+ * - Loop or one-shot playback
+ * - Callbacks at waypoints
+ */
+export class PathController extends CameraController {
+    constructor(path?: any[], options?: {});
+    path: any[];
+    speed: any;
+    easing: any;
+    loop: any;
+    autoStart: any;
+    isPlaying: boolean;
+    currentTime: number;
+    totalDistance: number;
+    segmentDistances: any[];
+    currentSegment: number;
+    t: number;
+    onComplete: any;
+    onWaypoint: any;
+    play(): void;
+    pause(): void;
+    stop(): void;
+    _calculatePathDistances(): void;
+    onUpdate(delta: any): any;
+    _applyEasing(t: any, easing: any): any;
+}
+/**
+ * ControllerManager - manages multiple controllers on a camera
+ * Why needed: handles controller priority, blending, and update order
+ */
+export class ControllerManager {
+    constructor(camera: any);
+    camera: any;
+    controllers: Map<any, any>;
+    updateOrder: any[];
+    _originalUpdate: any;
+    add(controller: any): any;
+    remove(name: any): void;
+    get(name: any): any;
+    _update(delta: any): void;
+}
+/**
+ * Integrated Camera2D with controller support
+ * Extends the base Camera2D to include controller management
+ */
+export class ControlledCamera extends Camera2D {
+    controllerManager: ControllerManager;
+    _controllers: ControllerManager;
+    addController(controller: any): any;
+    removeController(name: any): void;
+    getController(name: any): any;
+    follow(target: any, options: any): FollowController;
+    shake(options: any): ShakeController;
+    zoom(options: any): ZoomController;
+    path(path: any, options: any): PathController;
+}
+/**
+ * CameraRig - parent node for camera with additional control points
+ * Useful for: camera shake that doesn't affect child objects, complex camera setups
+ */
+export class CameraRig extends Node {
+    camera: ControlledCamera;
+    pivot: Node;
+    cameraOffset: {
+        x: number;
+        y: number;
+    };
+    shakeCamera(intensity?: number): ShakeController;
+    moveRig(x: any, y: any): void;
+    setCameraOffset(x: any, y: any): void;
+}
+import { Camera2D } from "./cam.js";
+import { Node } from "./core.js";

package/dist/types/engine/core.d.ts

@@ -50,10 +50,13 @@ export class Node {
         x: number;
         y: number;
     };
+    worldCos: number;
+    worldSin: number;
     transformDirty: boolean;
     visible: boolean;
     active: boolean;
     ready: boolean;
+    physicsWorld: any;
     /**
      *
      * @param {Node} node
@@ -78,6 +81,18 @@ export class Node {
   * This gives proper transform inheritance (child orbits parent)
   */
     updateWorldTransform(): void;
+    getWorldPosition(): {
+        x: number;
+        y: number;
+    };
+    worldToLocal(wx: any, wy: any): {
+        x: any;
+        y: any;
+    };
+    localToWorld(lx: any, ly: any): {
+        x: number;
+        y: number;
+    };
     _ready(): void;
     _process(delta: any): void;
     _draw(canvas: any, camera: any): void;
@@ -116,7 +131,9 @@ export class Scene {
     paused: boolean;
     timeScale: number;
     camera: any;
+    set physicsWorld(world: any);
     addChild(node: any): Node;
+    start(): void;
     process(delta: any): void;
     draw(): void;
     /**

package/dist/types/engine/lerp.d.ts

@@ -0,0 +1,104 @@
+/**
+ * - `t = 0` → returns `a`
+- `t = 0.5` → returns midpoint
+- `t = 1` → returns `b`
+- Single multiplication, single addition
+- No branching (fast)
+- Works for ANY numeric type (positions, colors, angles, scales)
+
+ * @param {*} a
+ * @param {*} b
+ * @param {*} t
+ * @returns
+ */
+export function lerp(a: any, b: any, t: any): any;
+export function lerp2D(p0: any, p1: any, t: any): {
+    x: any;
+    y: any;
+};
+export function inverseLerp(a: any, b: any, value: any): number;
+export function remap(inMin: any, inMax: any, outMin: any, outMax: any, value: any): any;
+/**
+ * in quadratic interpolation (or "quadratic lerp" in programming contexts), the resulting line is a parabolic curve that is determined by the three points. It is not a direct, piecewise linear connection of the points.
+Quadratic interpolation fits a second-degree polynomial (a parabola) through the three given points (e.g., A, B, and C).
+When used as a Bézier curve, the three points define the start point, an end point, and a control point that shapes the curve.
+The curve is generated by a continuous process of linear interpolations (lerps) between intermediate points, resulting in a smooth arc.
+ * @param {*} p0
+ * @param {*} p1
+ * @param {*} p2
+ * @param {*} t
+ * @returns
+ */
+export function quadraticBezier(p0: any, p1: any, p2: any, t: any): {
+    x: any;
+    y: any;
+};
+/**
+ * the tangent vector of a quadratic Bézier curve is directly related to a linear interpolation (LERP). Specifically, the first derivative of a quadratic Bézier curve equation is a LERP function that defines the curve's velocity and direction (tangent) at any given parameter \(t\). A quadratic Bézier curve is defined as \(B(t)=(1-t)^{2}P_{0}+2(1-t)tP_{1}+t^{2}P_{2}\).The first derivative (rate of change with respect to \(t\)) is \(B^{\prime }(t)=2(1-t)(P_{1}-P_{0})+2t(P_{2}-P_{1})\).This derivative can be expressed as a LERP between the vectors \((P_{1}-P_{0})\) and \((P_{2}-P_{1})\), scaled by 2.
+ * @param {*} p0
+ * @param {*} p1
+ * @param {*} p2
+ * @param {*} t
+ * @returns
+ */
+export function quadraticBezierTangent(p0: any, p1: any, p2: any, t: any): {
+    x: number;
+    y: number;
+};
+export function cubicBezier(p0: any, p1: any, p2: any, p3: any, t: any): {
+    x: any;
+    y: any;
+};
+export function cubicBezierTangent(p0: any, p1: any, p2: any, p3: any, t: any): {
+    x: number;
+    y: number;
+    magnitude: number;
+};
+export function distance2D(p1: any, p2: any): number;
+/**
+ * **The insight:** We don't change lerp. We change **t**.
+
+```javascript
+// Linear (boring)
+const x = lerp(a, b, t);
+
+// Beautiful
+const easedT = easeOutCubic(t);
+const x = lerp(a, b, easedT);
+```
+
+Easing functions transform `t` from a straight line into a curve. Same lerp, different feel.
+ */
+export function easeInQuad(t: any): number;
+export function easeOutQuad(t: any): number;
+export function easeInOutQuad(t: any): number;
+export function easeInCubic(t: any): number;
+export function easeOutCubic(t: any): number;
+export function easeInOutCubic(t: any): number;
+/**
+ *
+- **EaseIn**: Slow start, fast end (accelerate)
+- **EaseOut**: Fast start, slow end (decelerate)
+- **EaseInOut**: Slow both ends, fast middle (S-curve)
+
+ */
+export function easeInQuart(t: any): number;
+export function easeOutQuart(t: any): number;
+export function easeInOutQuart(t: any): number;
+export function easeOutElastic(t: any): number;
+export function easeInElastic(t: any): number;
+export function easeOutBounce(t: any): number;
+export function easeInBounce(t: any): number;
+export function easeOutBack(t: any): number;
+export class BezierChain {
+    segments: any[];
+    addSegment(p0: any, p1: any, p2: any, p3: any): void;
+    addSmoothSegment(p2: any, p3: any): void;
+    getPoint(globalT: any): any;
+    getTangent(globalT: any): {
+        x: number;
+        y: number;
+        magnitude: number;
+    };
+    removeFirstSegment(): void;
+}

package/dist/types/engine/lib.d.ts

@@ -0,0 +1,119 @@
+export function profile(name: any, fn: any): any;
+export function profileAsync(name: any, fn: any): Promise<any>;
+/**
+ * minimal hot-reloader - treats game module as a hot-swappable DLL
+ *
+ * @param {Object} options
+ * @param {string} options.entry - Path to game module
+ * @param {boolean} [options.watch=true] - Enable file watching
+ * @param {number} [options.debounce=100] - Debounce ms for file changes
+ * @param {string[]} [options.watchFiles=[]] - Additional files to watch for changes
+ * @returns {Promise<Object>} Game module proxy
+ */
+export function hotloader(state: any, options: {
+    entry: string;
+    watch?: boolean;
+    debounce?: number;
+    watchFiles?: string[];
+}): Promise<any>;
+/**
+ * Clamp a rectangle to canvas bounds
+ * Returns null if completely outside canvas
+ */
+export function clampRectToCanvas(x: any, y: any, width: any, height: any, canvasWidth: any, canvasHeight: any): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Check if a pixel should be drawn (canvas + viewport clipping)
+ * @param {Camera2D} camera
+ */
+export function shouldDrawPixel(x: any, y: any, canvas: any, camera: Camera2D): boolean;
+/**
+ * optimized drawAtlasRegionToCanvas with micro-optimized fast paths.
+ *
+ * @param {{data: Uint8Array, width: number, height: number}} atlas
+ * @param {{x: number, y: number, width: number, height: number}} srcRect
+ * @param {PixelBuffer} canvas
+ * @param {{x: number, y: number, width: number, height: number}} destRect
+ * @param {{algorithm?: "bilinear" | "nn", flipH?: boolean, flipV?: boolean, modulate?: {r:number,g:number,b:number,a:number}, assumeOpaque?: boolean, camera?: Camera2D}} options
+ */
+export function drawAtlasRegionToCanvas(atlas: {
+    data: Uint8Array;
+    width: number;
+    height: number;
+}, srcRect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, canvas: PixelBuffer, destRect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, options?: {
+    algorithm?: "bilinear" | "nn";
+    flipH?: boolean;
+    flipV?: boolean;
+    modulate?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    assumeOpaque?: boolean;
+    camera?: Camera2D;
+}): void;
+export const globalPerf: Profiler;
+export function getModulePaths(): {
+    __filename: string;
+    __dirname: string;
+    require: NodeJS.Require | (() => never);
+};
+import { PixelBuffer } from "tessera.js";
+declare class Profiler {
+    scopePool: ScopeData[];
+    poolIndex: number;
+    scopeStack: any[];
+    currentScope: any;
+    rootScopes: any[];
+    frameCount: number;
+    frameTimes: any[];
+    frameStart: number;
+    scopeStats: Map<any, any>;
+    enabled: boolean;
+    mismatchCount: number;
+    acquireScope(name: any): ScopeData;
+    start(name: any): void;
+    _finalizeScope(scope: any): void;
+    end(name: any): void;
+    frame(): void;
+    getStats(name: any): any;
+    getAllStats(): any[];
+    percentile(samples: any, p: any): any;
+    report(): void;
+    exportTrace(): string;
+    reset(): void;
+    enable(): void;
+    disable(): void;
+}
+declare class ScopeData {
+    name: string;
+    depth: number;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    parent: any;
+    children: any[];
+    callCount: number;
+    totalTime: number;
+    minTime: number;
+    maxTime: number;
+    samples: any[];
+    reset(): void;
+    resetStats(): void;
+}
+export {};