agentjs-core
Version:
A comprehensive agent-based modeling framework with built-in p5.js visualization
295 lines • 8.3 kB
TypeScript
/**
* Visualizer - Main visualization class with p5Instance.js integration
*/
/// <reference types="@types/p5-global" />
import type { Agent } from '../core/agents/Agent';
import type { Environment } from '../core/environment/Environment';
import type { NetworkManager } from '../core/network/NetworkManager';
import type { AgentId, Position } from '../types/core';
import { AgentDefinitionVisualizer } from './AgentDefinitionVisualizer';
import { AnimationEngine } from './AnimationEngine';
import { AgentTrailSystem } from './AgentTrailSystem';
import { HeatMapSystem, type HeatMapLayer } from './HeatMapSystem';
import { ParticleEffectsSystem, type ParticleEffectType } from './ParticleEffectsSystem';
/** Visualization configuration */
export interface VisualizerConfig {
readonly canvas: {
width: number;
height: number;
background: number;
};
readonly rendering: {
frameRate: number;
enableAntiAliasing: boolean;
pixelDensity: number;
};
readonly agents: {
defaultSize: number;
sizeProperty?: string;
colorProperty?: string;
minSize: number;
maxSize: number;
};
readonly camera: {
enablePan: boolean;
enableZoom: boolean;
minZoom: number;
maxZoom: number;
};
}
/** Agent visual appearance */
export interface AgentVisuals {
size: number;
color: Color | string;
transparency: number;
shape: 'circle' | 'square' | 'triangle';
}
/** Camera state */
export interface CameraState {
x: number;
y: number;
zoom: number;
}
/**
* Visualizer - Main visualization system for AgentJS
*
* Features:
* - p5Instance.js integration with TypeScript support
* - Real-time agent rendering with property-based visuals
* - Interactive camera controls (pan/zoom)
* - Performance optimization for 100+ agents
* - Configurable rendering pipeline
*
* Educational Context: Provides visual feedback for agent-based
* simulations, making complex behaviors observable and understandable.
*/
export declare class Visualizer {
/** p5Instance.js instance */
private p5Instance;
/** Reference to agents map */
private agents;
/** Reference to environment */
private environment;
/** Reference to network manager */
private networkManager;
/** Visualization configuration */
private config;
/** Camera state */
private camera;
/** Canvas container element */
private container;
/** Animation frame ID for cleanup */
private animationId;
/** Performance monitoring */
private readonly frameStats;
/** Real-time agent definition visualizer */
private definitionVisualizer;
/** Animation engine for smooth transitions */
private animationEngine;
/** Agent trail system for movement history */
private trailSystem;
/** Heat map system for spatial analysis */
private heatMapSystem;
/** Particle effects system for visual feedback */
private particleSystem;
constructor(config?: Partial<VisualizerConfig>);
/**
* Initialize visualization with container element
*/
initialize(containerElement: HTMLElement): void;
/**
* p5Instance.js setup function
*/
private setup;
/**
* p5Instance.js draw function - main rendering loop
*/
private draw;
/**
* Render all agents
*/
private renderAgents;
/**
* Render a single agent with definition extent visualization
*/
private renderAgentWithDefinition;
/**
* Render a single agent (legacy method, kept for compatibility)
*/
private _renderAgent;
/**
* Calculate visual properties for an agent
*
* MVP Visual Design: Uses primary colors and geometric shapes
* - Red: Exploitation/danger states
* - Blue: Support/safety states
* - Green: Growth/empowerment states
* - Yellow: Resources/opportunities
* - Orange: Vulnerability/warning states
*/
private calculateAgentVisuals;
/**
* Get agent shape based on type (MVP geometric shapes)
*
* MVP Design Mapping:
* - Circles: Community members (default)
* - Triangles: Leaders/influencers
* - Squares: Resources/institutions
*
* Post-MVP: Will be replaced with custom character artwork
*/
private getAgentShape;
/**
* Draw triangle shape
*/
private drawTriangle;
/**
* Render network connections (MVP geometric line visualization)
*
* MVP Design:
* - Supportive connections: Blue lines (#2563EB)
* - Exploitative connections: Red lines (#DC2626)
* - Economic connections: Green dashed lines (#059669)
*/
private renderConnections;
/**
* Draw dashed line for economic connections
*/
private drawDashedLine;
/**
* Render environment background (MVP zone visualization)
*
* MVP Design:
* - Safe zones: Light blue overlay (rgba(37, 99, 235, 0.1))
* - Danger zones: Light red overlay (rgba(220, 38, 38, 0.1))
* - Resource areas: Light yellow overlay (rgba(254, 240, 138, 0.2))
* - Neutral areas: Default background (#F5F5F4)
*/
private renderEnvironment;
/**
* Render environment zones with MVP color overlays
*/
private renderEnvironmentZones;
/**
* Get environment boundaries
*/
private getEnvironmentBounds;
/**
* Render UI overlay
*/
private renderUI;
/**
* Handle mouse press events
*/
private handleMousePressed;
/** Previous mouse coordinates for dragging */
private previousMouseX;
private previousMouseY;
/**
* Handle mouse drag events
*/
private handleMouseDragged;
/**
* Handle mouse wheel events for zooming
*/
private handleMouseWheel;
/**
* Handle window resize
*/
private handleWindowResize;
/**
* Update frame rate statistics
*/
private updateFrameStats;
/**
* Set agents to visualize
*/
setAgents(agents: Map<AgentId, Agent>): void;
/**
* Set environment to visualize
*/
setEnvironment(environment: Environment): void;
/**
* Set network manager to visualize connections
*/
setNetworkManager(networkManager: NetworkManager): void;
/**
* Update visualization configuration
*/
updateConfig(newConfig: Partial<VisualizerConfig>): void;
/**
* Get current camera state
*/
getCameraState(): CameraState;
/**
* Set camera state
*/
setCameraState(state: Partial<CameraState>): void;
/**
* Reset camera to default position
*/
resetCamera(): void;
/**
* Get current frame rate
*/
getFrameRate(): number;
/**
* Get definition extent statistics
*/
private getDefinitionStats;
/**
* Get definition visualizer instance
*/
getDefinitionVisualizer(): AgentDefinitionVisualizer;
/**
* Enable/disable heat map layer
*/
toggleHeatMapLayer(layer: HeatMapLayer): boolean;
/**
* Enable/disable agent trails
*/
toggleAgentTrails(enabled: boolean): void;
/**
* Create particle effect at position
*/
createParticleEffect(type: ParticleEffectType, position: Position): string;
/**
* Animate agent to new position
*/
animateAgentToPosition(agentId: AgentId, newPosition: Position, duration?: number): void;
/**
* Get animation engine instance
*/
getAnimationEngine(): AnimationEngine;
/**
* Get trail system instance
*/
getTrailSystem(): AgentTrailSystem;
/**
* Get heat map system instance
*/
getHeatMapSystem(): HeatMapSystem;
/**
* Get particle system instance
*/
getParticleSystem(): ParticleEffectsSystem;
/**
* Get combined performance statistics
*/
getAdvancedStats(): {
visualizer: {
fps: number;
agents: number;
zoom: number;
};
animation: any;
trails: any;
heatMaps: any;
particles: any;
};
/**
* Destroy the visualizer and clean up resources
*/
destroy(): void;
}
//# sourceMappingURL=Visualizer.d.ts.map