@rpgjs/common 4.3.0 → 5.0.0-alpha.1

package/dist/Physic.d.ts

@@ -0,0 +1,619 @@
+import { Direction, RpgCommonPlayer } from './Player';
+import * as Matter from 'matter-js';
+export interface ZoneOptions {
+    /** World x‑coordinate (ignored if linkedTo) */
+    x?: number;
+    /** World y‑coordinate (ignored if linkedTo) */
+    y?: number;
+    /** Circle radius (px) */
+    radius: number;
+    /** Vision aperture. 360 = full circle, <360 = cone */
+    angle?: number;
+    /** Facing direction used when angle < 360 */
+    direction?: Direction;
+    /** If supplied, zone tracks this hitbox id */
+    linkedTo?: string;
+    /** If true, walls (static hitboxes) stop vision */
+    limitedByWalls?: boolean;
+}
+export interface SlidingOptions {
+    /** Enable collision sliding */
+    enabled?: boolean;
+    /** Sliding friction factor (0-1, where 0 = no sliding, 1 = perfect sliding) */
+    friction?: number;
+    /** Minimum velocity threshold for sliding to occur */
+    minVelocity?: number;
+}
+export interface ZoneData {
+    id: string;
+    /** 'static' if x/y provided, otherwise 'linked' */
+    type: 'static' | 'linked';
+    /** Underlying Matter sensor body */
+    body: Matter.Body;
+    /** Host hitbox id when type === 'linked' */
+    linkedTo?: string;
+    /** Aperture in radians (π*2 for full circle) */
+    aperture: number;
+    /** limitedByWalls flag */
+    limitedByWalls: boolean;
+}
+/**
+ * Class to manage physics in a 2D RPG world without gravity using MatterJS
+ *
+ * Provides management for:
+ * - Static hitboxes (map elements, obstacles)
+ * - Movable hitboxes (players, events)
+ * - Collision detection and tracking
+ * - Collision events (enter/exit)
+ * - Zones (sensor areas that detect entities without physical collision)
+ */
+export declare class RpgCommonPhysic {
+    private engine;
+    private world;
+    private hitboxes;
+    private collisions;
+    private collisionEvents;
+    private movementEvents;
+    private zones;
+    private zoneCollisions;
+    private zoneEvents;
+    private collisionNormals;
+    private lastVelocities;
+    private intendedMovements;
+    private collisionData;
+    /**
+     * Initialize the physics engine with no gravity
+     *
+     * @example
+     * ```ts
+     * const physic = new RpgCommonPhysic();
+     * ```
+     */
+    constructor();
+    /**
+     * Updates the physics simulation
+     *
+     * @param delta - Time delta in milliseconds
+     *
+     * @example
+     * ```ts
+     * // Update physics in game loop
+     * physic.update(16); // 16ms = ~60fps
+     * ```
+     */
+    update(delta: number): void;
+    /**
+     * Synchronize all physics bodies with their associated players
+     *
+     * Updates player positions based on their physics bodies after physics calculations
+     *
+     * @example
+     * ```ts
+     * // Called automatically in update()
+     * physic.syncBodies();
+     * ```
+     */
+    private syncBodies;
+    /**
+     * Synchronize linked zones to follow their host hitboxes
+     *
+     * Updates zones that are linked to players or other movable hitboxes
+     *
+     * @example
+     * ```ts
+     * // Called automatically in update()
+     * physic.syncLinkedZones();
+     * ```
+     */
+    private syncLinkedZones;
+    /**
+     * Convert a Direction enum value to radians
+     *
+     * @param dir - Direction enum value
+     * @returns Angle in radians
+     */
+    private directionToAngle;
+    /**
+     * Convert a movement vector to a Direction enum value
+     *
+     * Determines the primary direction based on the larger component
+     * of the movement vector. Returns null if no significant movement.
+     *
+     * @param dx - X displacement
+     * @param dy - Y displacement
+     * @returns Direction enum value or null if no movement
+     */
+    private vectorToDirection;
+    /**
+     * Add a static hitbox (immovable objects like walls, obstacles)
+     *
+     * @param id - Unique identifier for the hitbox
+     * @param x - X position
+     * @param y - Y position
+     * @param width - Width of hitbox
+     * @param height - Height of hitbox
+     * @returns The id of the created hitbox
+     *
+     * @example
+     * ```ts
+     * // Add a wall
+     * physic.addStaticHitbox('wall1', 100, 50, 32, 128);
+     * ```
+     */
+    addStaticHitbox(id: string, x: number, y: number, width: number, height: number): string;
+    /**
+     * Add a movable hitbox (players, NPCs, dynamic objects)
+     *
+     * @param player - Player object that owns this hitbox
+     * @param x - X position
+     * @param y - Y position
+     * @param width - Width of hitbox
+     * @param height - Height of hitbox
+     * @param options - Additional body options
+     * @param slidingOptions - Collision sliding configuration
+     * @returns The id of the created hitbox
+     *
+     * @example
+     * ```ts
+     * // Add a player with sliding enabled (only against walls)
+     * const player = new RpgCommonPlayer();
+     * player.id = 'player1';
+     * physic.addMovableHitbox(player, 200, 300, 24, 32, {}, {
+     *   enabled: true,
+     *   friction: 0.8,
+     *   minVelocity: 0.5
+     * });
+     * ```
+     */
+    addMovableHitbox(player: RpgCommonPlayer, x: number, y: number, width: number, height: number, options?: {}, slidingOptions?: SlidingOptions): string;
+    /**
+     * Update a hitbox's position and size
+     *
+     * @param id - ID of the hitbox to update
+     * @param x - New X position
+     * @param y - New Y position
+     * @param width - New width (optional)
+     * @param height - New height (optional)
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Update player position
+     * physic.updateHitbox('player1', newX, newY);
+     *
+     * // Update both position and size
+     * physic.updateHitbox('player1', newX, newY, newWidth, newHeight);
+     * ```
+     */
+    updateHitbox(id: string, x: number, y: number, width?: number, height?: number): boolean;
+    /**
+     * Remove a hitbox from the world
+     *
+     * @param id - ID of the hitbox to remove
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Remove an enemy
+     * physic.removeHitbox('enemy1');
+     * ```
+     */
+    removeHitbox(id: string): boolean;
+    /**
+     * Register collision event callbacks for a hitbox
+     *
+     * @param id - ID of the hitbox
+     * @param onCollisionEnter - Callback when entering collision
+     * @param onCollisionExit - Callback when exiting collision
+     *
+     * @example
+     * ```ts
+     * // Register collision events for player
+     * physic.registerCollisionEvents('player1',
+     *   (hitboxIds) => console.log('Player hit:', hitboxIds),
+     *   (hitboxIds) => console.log('Player no longer hitting:', hitboxIds)
+     * );
+     * ```
+     */
+    registerCollisionEvents(id: string, onCollisionEnter?: (collidedWith: string[]) => void, onCollisionExit?: (collidedWith: string[]) => void): void;
+    /**
+     * Get all hitbox IDs currently colliding with the specified hitbox
+     *
+     * @param id - ID of the hitbox to check collisions for
+     * @returns Array of hitbox IDs or empty array if none found
+     *
+     * @example
+     * ```ts
+     * // Get all enemies colliding with player
+     * const collidingEnemies = physic.getCollisions('player1');
+     * ```
+     */
+    getCollisions(id: string): string[];
+    /**
+     * Check if two hitboxes are colliding
+     *
+     * @param id1 - First hitbox ID
+     * @param id2 - Second hitbox ID
+     * @returns Boolean indicating if they are colliding
+     *
+     * @example
+     * ```ts
+     * // Check if player is touching the door
+     * if (physic.areColliding('player1', 'door')) {
+     *   // Open the door
+     * }
+     * ```
+     */
+    areColliding(id1: string, id2: string): boolean;
+    /**
+     * Handle collision start events from MatterJS
+     */
+    private handleCollisionStart;
+    /**
+     * Handle collision end events from MatterJS
+     */
+    private handleCollisionEnd;
+    /**
+     * Extract entity ID and zone status from a physics body
+     *
+     * @param body - Matter.js body
+     * @returns Object containing ID and isZone flag
+     */
+    private extractId;
+    /**
+     * Process a zone enter event
+     *
+     * @param zoneId - ID of the zone
+     * @param hitId - ID of the hitbox entering the zone
+     */
+    private processZoneEnter;
+    /**
+     * Process a zone exit event
+     *
+     * @param zoneId - ID of the zone
+     * @param hitId - ID of the hitbox exiting the zone
+     */
+    private processZoneExit;
+    /**
+     * Check if there is a clear line of sight between two points
+     *
+     * @param start - Starting point
+     * @param end - Ending point
+     * @returns True if no static hitbox blocks the line
+     */
+    private hasLineOfSight;
+    /**
+     * Record a collision between two hitboxes
+     */
+    private recordCollision;
+    /**
+     * Remove a collision record between two hitboxes
+     */
+    private removeCollision;
+    /**
+     * Move a body based on player movement data
+     *
+     * Applies velocity to a physics body based on the player's current speed
+     * and automatically updates the player's position and intended direction
+     *
+     * @param player - The player object containing movement data
+     * @param direction - The intended movement direction
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Move a player's physics body
+     * physic.moveBody(player, Direction.Right);
+     * ```
+     */
+    moveBody(player: RpgCommonPlayer, direction: Direction): boolean;
+    /**
+     * Stop movement for a player
+     *
+     * Clears the intended direction and stops any ongoing movement.
+     * This should be called when the player releases movement keys.
+     *
+     * @param player - The player object to stop
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Player releases all movement keys
+     * physic.stopMovement(player);
+     * ```
+     */
+    stopMovement(player: RpgCommonPlayer): boolean;
+    /**
+     * Synchronize a player's position to its physics body
+     *
+     * Updates the physics body position based on the player's current position
+     * Useful when player position is changed outside of physics system
+     *
+     * @param playerId - ID of the player to synchronize
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // After teleporting a player
+     * player.x.set(newX);
+     * player.y.set(newY);
+     * physic.syncPlayerToBody(player.id);
+     * ```
+     */
+    syncPlayerToBody(playerId: string): boolean;
+    /**
+     * Get a physics body by entity ID
+     *
+     * Used by the MovementManager to apply movement strategies
+     *
+     * @param id - Entity ID
+     * @returns The Matter.js body or undefined if not found
+     *
+     * @example
+     * ```ts
+     * // Get a body to apply movement
+     * const body = physic.getBody('player1');
+     * if (body) Matter.Body.setVelocity(body, { x: 5, y: 0 });
+     * ```
+     */
+    getBody(id: string): Matter.Body | undefined;
+    /**
+     * Apply a translation to a body directly
+     *
+     * Used as a clean interface for the movement system.
+     * Automatically determines and sets the intended direction for players.
+     *
+     * @param id - Entity ID
+     * @param dx - X displacement in pixels
+     * @param dy - Y displacement in pixels
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Move entity 5px right, 2px down
+     * physic.applyTranslation('player1', 5, 2);
+     * ```
+     */
+    applyTranslation(id: string, dx: number, dy: number): boolean;
+    /**
+     * Set the velocity of a body directly
+     *
+     * Used as a clean interface for the movement system
+     *
+     * @param id - Entity ID
+     * @param vx - X velocity component
+     * @param vy - Y velocity component
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Set entity velocity to 5px/s right
+     * physic.setVelocity('player1', 5, 0);
+     * ```
+     */
+    setVelocity(id: string, vx: number, vy: number): boolean;
+    /**
+     * Apply a force to a body
+     *
+     * Used as a clean interface for the movement system
+     *
+     * @param id - Entity ID
+     * @param forceX - X force component
+     * @param forceY - Y force component
+     * @param position - Application point (optional, default is body center)
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Apply force to push entity
+     * physic.applyForce('player1', 0.05, 0);
+     * ```
+     */
+    applyForce(id: string, forceX: number, forceY: number, position?: Matter.Vector): boolean;
+    /**
+     * Get the Matter.js world object
+     *
+     * Useful for advanced manipulation and querying of the physics world
+     *
+     * @returns Matter.js World object
+     *
+     * @example
+     * ```ts
+     * // Query for all bodies in an area
+     * const world = physic.getWorld();
+     * const bodies = Matter.Query.region(world.bodies, area);
+     * ```
+     */
+    getWorld(): Matter.World;
+    /**
+     * Create a new Zone sensor. Never collides physically but triggers events.
+     *
+     * @param id - Unique identifier for the zone
+     * @param opts - Zone options
+     * @returns The id of the created zone
+     *
+     * @example
+     * ```ts
+     * // 90° cone vision in front of guard1 (120px range)
+     * physic.addZone('guardVision', {
+     *   linkedTo: 'guard1',
+     *   radius: 120,
+     *   angle: 90,
+     *   direction: Direction.Right,
+     *   limitedByWalls: true
+     * });
+     * ```
+     */
+    addZone(id: string, opts: ZoneOptions): string;
+    getZone(id: string): ZoneData | undefined;
+    /**
+     * Remove a zone from the world
+     *
+     * @param id - ID of the zone to remove
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Remove a detection zone
+     * physic.removeZone('guardVision');
+     * ```
+     */
+    removeZone(id: string): boolean;
+    /**
+     * Register zone enter/exit callbacks
+     *
+     * @param id - ID of the zone
+     * @param onEnter - Callback when an entity enters the zone
+     * @param onExit - Callback when an entity exits the zone
+     *
+     * @example
+     * ```ts
+     * // Register zone events
+     * physic.registerZoneEvents('guardVision',
+     *   (hitIds) => console.log('Entities spotted:', hitIds),
+     *   (hitIds) => console.log('Entities lost:', hitIds)
+     * );
+     * ```
+     */
+    registerZoneEvents(id: string, onEnter?: (hitIds: string[]) => void, onExit?: (hitIds: string[]) => void): void;
+    /**
+     * Get all entity IDs currently inside a zone
+     *
+     * @param id - ID of the zone to check
+     * @returns Array of entity IDs or empty array if none found
+     *
+     * @example
+     * ```ts
+     * // Check which entities are in guard's vision
+     * const spotted = physic.getEntitiesInZone('guardVision');
+     * if (spotted.includes('player1')) {
+     *   // Guard saw the player!
+     * }
+     * ```
+     */
+    getEntitiesInZone(id: string): string[];
+    /**
+     * Check for movement state changes on all movable hitboxes
+     *
+     * Detects when objects start or stop moving and triggers appropriate events
+     *
+     * @example
+     * ```ts
+     * // Called automatically in update()
+     * physic.checkMovementChanges();
+     * ```
+     */
+    private checkMovementChanges;
+    /**
+     * Register movement event callbacks for a hitbox
+     *
+     * @param id - ID of the hitbox
+     * @param onStartMoving - Callback when object starts moving
+     * @param onStopMoving - Callback when object stops moving
+     *
+     * @example
+     * ```ts
+     * // Register movement events for player
+     * physic.registerMovementEvents('player1',
+     *   () => console.log('Player started moving'),
+     *   () => console.log('Player stopped moving')
+     * );
+     * ```
+     */
+    registerMovementEvents(id: string, onStartMoving?: () => void, onStopMoving?: () => void): void;
+    /**
+     * Check if a hitbox is currently moving
+     *
+     * @param id - ID of the hitbox to check
+     * @returns Boolean indicating if the object is in motion
+     *
+     * @example
+     * ```ts
+     * // Check if player is moving
+     * if (physic.isMoving('player1')) {
+     *   // Player is in motion
+     * }
+     * ```
+     */
+    isMoving(id: string): boolean;
+    /**
+     * Unregister movement events for a hitbox
+     *
+     * @param id - ID of the hitbox
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Remove movement event listeners
+     * physic.unregisterMovementEvents('player1');
+     * ```
+     */
+    unregisterMovementEvents(id: string): boolean;
+    /**
+     * Enable or disable collision sliding for a hitbox
+     *
+     * @param id - ID of the hitbox
+     * @param enabled - Whether to enable sliding
+     * @param options - Sliding configuration options
+     * @returns Boolean indicating success
+     *
+     * @example
+     * ```ts
+     * // Enable sliding for an existing player
+     * physic.setSliding('player1', true, {
+     *   friction: 0.9,
+     *   minVelocity: 1.0
+     * });
+     * ```
+     */
+    setSliding(id: string, enabled: boolean, options?: SlidingOptions): boolean;
+    /**
+     * Check if sliding is enabled for a hitbox
+     *
+     * @param id - ID of the hitbox
+     * @returns Boolean indicating if sliding is enabled
+     *
+     * @example
+     * ```ts
+     * // Check if player has sliding enabled
+     * if (physic.isSlidingEnabled('player1')) {
+     *   // Player can slide along walls
+     * }
+     * ```
+     */
+    isSlidingEnabled(id: string): boolean;
+    /**
+     * Get sliding options for a hitbox
+     *
+     * @param id - ID of the hitbox
+     * @returns Sliding options or undefined if not found
+     *
+     * @example
+     * ```ts
+     * // Get current sliding configuration
+     * const options = physic.getSlidingOptions('player1');
+     * console.log('Friction:', options?.friction);
+     * ```
+     */
+    getSlidingOptions(id: string): SlidingOptions | undefined;
+    private applySlidingCorrections;
+    private storeCollisionNormals;
+    /**
+     * Determine if a collision is partial (corner/edge) or full frontal
+     *
+     * @param bodyA - First collision body
+     * @param bodyB - Second collision body
+     * @param intendedMovement - The intended movement vector
+     * @returns Object with collision analysis
+     */
+    private analyzeCollision;
+    private resolveMovableCollisions;
+    /**
+     * Check if two bodies are actually touching/overlapping
+     */
+    private areBodiesTouching;
+    /**
+     * Check if a body is moving towards another body
+     */
+    private isMovingTowards;
+}