@rpgjs/physic
Version:
A deterministic 2D top-down physics library for RPG, sandbox and MMO games
271 lines • 7.82 kB
TypeScript
import { PhysicsEngine } from './PhysicsEngine';
import { Entity } from '../physics/Entity';
import { Vector2 } from '../core/math/Vector2';
/**
* Direction value for zone orientation (used for cone-shaped zones)
*/
export type ZoneDirection = 'up' | 'down' | 'left' | 'right';
/**
* Configuration for a static zone (fixed position in the world)
*/
export interface StaticZoneConfig {
/** Zone position in world coordinates */
position: Vector2 | {
x: number;
y: number;
};
/** Zone radius */
radius: number;
/** Cone angle in degrees (360 = full circle, < 360 = cone) */
angle?: number;
/** Direction for cone-shaped zones */
direction?: ZoneDirection;
/** Whether line-of-sight is required (blocks through static entities) */
limitedByWalls?: boolean;
/** Optional metadata */
metadata?: Record<string, any>;
}
/**
* Configuration for a zone attached to an entity
*/
export interface AttachedZoneConfig {
/** Entity to attach the zone to */
entity: Entity;
/** Offset from entity position (default: {x: 0, y: 0}) */
offset?: Vector2 | {
x: number;
y: number;
};
/** Zone radius */
radius: number;
/** Cone angle in degrees (360 = full circle, < 360 = cone) */
angle?: number;
/** Direction for cone-shaped zones (can be relative to entity rotation or fixed) */
direction?: ZoneDirection;
/** Whether line-of-sight is required (blocks through static entities) */
limitedByWalls?: boolean;
/** Optional metadata */
metadata?: Record<string, any>;
}
/**
* Union type for zone configuration
*/
export type ZoneConfig = StaticZoneConfig | AttachedZoneConfig;
/**
* Zone event callbacks
*/
export interface ZoneCallbacks {
/**
* Called when entities enter the zone
* @param entities - Array of entities that entered
*/
onEnter?: (entities: Entity[]) => void;
/**
* Called when entities exit the zone
* @param entities - Array of entities that exited
*/
onExit?: (entities: Entity[]) => void;
}
/**
* Public zone information
*/
export interface ZoneInfo {
id: string;
type: 'static' | 'attached';
position: Vector2;
radius: number;
angle: number;
direction: ZoneDirection;
limitedByWalls: boolean;
metadata?: Record<string, any> | undefined;
}
/**
* Zone manager for detecting entities within circular/cone-shaped areas.
*
* Zones can be used for vision, skill ranges, explosions, and other gameplay mechanics
* that need to detect entities without physical collisions.
*
* @example
* ```typescript
* const engine = new PhysicsEngine({ timeStep: 1/60 });
* const zones = new ZoneManager(engine);
*
* // Create a static zone
* const zoneId = zones.createZone({
* position: { x: 100, y: 100 },
* radius: 50,
* onEnter: (entities) => console.log('Entities entered:', entities),
* });
*
* // Create a zone attached to an entity
* const player = engine.createEntity({ position: { x: 0, y: 0 }, radius: 10 });
* const visionZone = zones.createAttachedZone(player, {
* radius: 100,
* angle: 90,
* direction: 'right',
* onEnter: (entities) => console.log('Player sees:', entities),
* });
*
* // Update zones after each physics step
* engine.step();
* zones.update();
* ```
*/
export declare class ZoneManager {
private readonly engine;
private readonly zones;
/**
* Creates a new zone manager
*
* @param engine - Physics engine instance
*/
constructor(engine: PhysicsEngine);
/**
* Creates a new zone
*
* @param config - Zone configuration
* @param callbacks - Optional event callbacks
* @returns Zone identifier
*
* @example
* ```typescript
* const zoneId = zones.createZone({
* position: { x: 100, y: 100 },
* radius: 50,
* angle: 180,
* direction: 'right',
* }, {
* onEnter: (entities) => console.log('Entered:', entities),
* onExit: (entities) => console.log('Exited:', entities),
* });
* ```
*/
createZone(config: ZoneConfig, callbacks?: ZoneCallbacks): string;
/**
* Creates a zone attached to an entity (convenience method)
*
* @param entity - Entity to attach the zone to
* @param config - Zone configuration
* @param callbacks - Optional event callbacks
* @returns Zone identifier
*
* @example
* ```typescript
* const visionZone = zones.createAttachedZone(player, {
* radius: 100,
* angle: 90,
* direction: 'right',
* offset: { x: 0, y: -10 },
* }, {
* onEnter: (entities) => console.log('Player sees:', entities),
* });
* ```
*/
createAttachedZone(entity: Entity, config: Omit<AttachedZoneConfig, 'entity'>, callbacks?: ZoneCallbacks): string;
/**
* Updates a zone's configuration
*
* @param id - Zone identifier
* @param updates - Partial configuration updates
* @returns True if the zone was found and updated
*
* @example
* ```typescript
* zones.updateZone(zoneId, { radius: 75, angle: 120 });
* ```
*/
updateZone(id: string, updates: Partial<ZoneConfig>): boolean;
/**
* Registers or updates callbacks for a zone
*
* @param id - Zone identifier
* @param callbacks - Event callbacks
* @returns True if the zone was found
*
* @example
* ```typescript
* zones.registerCallbacks(zoneId, {
* onEnter: (entities) => console.log('Entered:', entities),
* onExit: (entities) => console.log('Exited:', entities),
* });
* ```
*/
registerCallbacks(id: string, callbacks: ZoneCallbacks): boolean;
/**
* Removes a zone
*
* @param id - Zone identifier
* @returns True if the zone was found and removed
*/
removeZone(id: string): boolean;
/**
* Gets zone information
*
* @param id - Zone identifier
* @returns Zone information or undefined
*/
getZone(id: string): ZoneInfo | undefined;
/**
* Gets all entities currently inside a zone
*
* @param id - Zone identifier
* @returns Array of entities inside the zone
*/
getEntitiesInZone(id: string): Entity[];
/**
* Gets all zone identifiers
*
* @returns Array of zone IDs
*/
getAllZoneIds(): string[];
/**
* Clears all zones
*/
clear(): void;
/**
* Updates all zones, detecting entities entering/exiting
*
* This should be called after each physics step to keep zones synchronized.
*
* @param _deltaTime - Optional delta time (not used currently, but kept for future use)
*
* @example
* ```typescript
* engine.step();
* zones.update();
* ```
*/
update(_deltaTime?: number): void;
/**
* Checks if an entity is inside a zone
*
* @param zone - Zone record
* @param entity - Entity to check
* @returns True if the entity is inside the zone
*/
private isEntityInsideZone;
/**
* Checks if there's a clear line of sight between two points
*
* @param start - Start position
* @param end - End position
* @param ignoreEntityId - Entity UUID to ignore (usually the target entity)
* @returns True if line of sight is clear
*/
private hasLineOfSight;
/**
* Converts direction string to angle in radians
*
* @param dir - Direction
* @returns Angle in radians
*/
private directionToAngle;
/**
* Normalizes angle to [-π, π]
*
* @param angle - Angle in radians
* @returns Normalized angle
*/
private normalizeAngle;
}
//# sourceMappingURL=ZoneManager.d.ts.map