A real-time simulation system for maritime convoy defense with autonomous drone support, threat detection, and advanced snapshot logging capabilities.
This project simulates a convoy navigating through a series of checkpoints while avoiding restricted zones and detecting potential threats. The system features autonomous drones that orbit the convoy, providing extended detection coverage and shared threat intelligence.
- 🚢 Convoy Navigation: Autonomous pathfinding through checkpoints with arrival behavior
- 🛸 Drone Support: Configurable number of orbiting drones (0-8) with enhanced detection
⚠️ Threat Detection: Real-time threat classification (HIGH/MEDIUM/LOW/MINIMAL)- 🚫 Restricted Zones: Circular and rectangular zones to navigate around
- 📊 Snapshot Logging: Comprehensive data capture and export system
- ☁️ AWS Integration: Optional cloud storage with AWS Timestream
- 🎮 Interactive Controls: Real-time drone count adjustment
- 📈 Live Monitoring: Real-time statistics and threat analysis
npm installnpm run devOpen your browser to http://localhost:5173 and watch the simulation run!
- Autonomous Navigation: Uses seeking behavior to reach checkpoints
- Detection Radius: ~20nm (60px at scale)
- Arrival Behavior: Slows down when approaching checkpoints
- Threat Awareness: Detects and classifies nearby threats
- Orbital Movement: Circle around convoy at 100px radius
- Enhanced Detection: ~25nm radius (70px), better than convoy
- Shared Intelligence: All drone detections combined with convoy
- Configurable Count: Adjust from 0-8 drones in real-time
- Wander Behavior: Organic, unpredictable movement patterns
- Independent Detection: Each attacker tracks the convoy
- Variable Speed: Different speeds for realistic behavior
- Boundary Wrapping: Wrap around screen edges
- Circular Zones: Defined by center point and radius
- Rectangular Zones: Defined by position and dimensions
- Visual Warnings: Striped patterns and warning colors
- Navigation Obstacles: Areas to avoid during pathfinding
The simulation includes a comprehensive snapshot logging system that captures detailed state information for analysis.
Each snapshot contains:
- Convoy Data: Position, velocity, speed, detected threats, current checkpoint
- Drone Data: Position, orbit angle, detected threats for each drone
- Attacker Data: Position, velocity, wander angle for each attacker
- Threat Intelligence: Total count, classifications, proximity data
- Mission Progress: Checkpoints completed, distance to goal
- Performance Metrics: Average speed, threat proximity
- Metadata: Timestamp, frame number, session ID, event type
Captured every 10 seconds automatically during simulation.
Captured immediately when:
- ✅ Checkpoint reached
- ✅ New threat detected
- ⏳ Threat level changes (future)
- ⏳ High threat proximity (future)
- View Live Data: Expand the "SNAPSHOT MONITOR" panel below the canvas
- See Statistics: Session duration, total snapshots, checkpoints completed
- Browse Snapshots: Scroll through recent captures in the table
- Filter Data: Toggle between "All" and "Events Only" views
- Export Data: Click "Download JSON" to export all snapshots
- Clear Data: Click "Clear" to reset local storage
Snapshot settings can be configured via .env file:
# Capture interval in milliseconds
VITE_SNAPSHOT_INTERVAL=10000
# Enable event-based snapshots
VITE_SNAPSHOT_EVENTS=true
# Local buffer size (max snapshots stored)
VITE_SNAPSHOT_BUFFER_SIZE=1000
# AWS integration (optional)
VITE_AWS_ENABLED=false
VITE_SNAPSHOT_AUTO_SEND=falseFor persistent storage and advanced querying, you can integrate with AWS Timestream.
-
Create AWS Resources
# See AWS_SETUP.md for detailed instructions cat AWS_SETUP.md -
Configure Environment
cp .env.example .env # Edit .env with your AWS credentials -
Enable AWS
VITE_AWS_ENABLED=true VITE_AWS_REGION=us-east-1 VITE_AWS_ACCESS_KEY_ID=your_key VITE_AWS_SECRET_ACCESS_KEY=your_secret VITE_SNAPSHOT_AUTO_SEND=true
Once data is in Timestream, you can run SQL queries:
-- Average threats over time
SELECT
bin(time, 1m) as time_bucket,
avg(measure_value::double) as avg_threats
FROM "ConvoySimulation"."SimulationSnapshots"
WHERE measure_name = 'total_threats'
AND time > ago(1h)
GROUP BY bin(time, 1m);
-- Convoy position over time
SELECT time, measure_name, measure_value::double
FROM "ConvoySimulation"."SimulationSnapshots"
WHERE entity = 'convoy'
AND measure_name IN ('position_x', 'position_y')
ORDER BY time ASC;convoy-defense/
├── src/
│ ├── components/
│ │ ├── ConvoyCanvas.jsx # Main simulation canvas
│ │ └── SnapshotViewer.jsx # Snapshot monitoring UI
│ ├── utils/
│ │ ├── vector.js # Vector math utilities
│ │ └── snapshotCapture.js # Snapshot capture logic
│ ├── services/
│ │ └── awsTimestreamService.js # AWS integration
│ ├── config/
│ │ └── aws-config.js # Configuration management
│ ├── App.jsx # Main application component
│ └── main.jsx # Application entry point
├── .env.example # Environment variables template
├── AWS_SETUP.md # AWS setup guide
└── SNAPSHOT_SYSTEM_README.md # Snapshot system documentation
Seeking (Convoy)
- Calculates desired velocity toward target
- Implements arrival behavior (slows near target)
- Smooth velocity transitions
Wander (Attackers)
- Random direction changes
- Smooth velocity blending
- Boundary wrapping for continuous movement
Orbit (Drones)
- Circular motion around convoy
- Maintains fixed radius
- Follows convoy position
Detection Logic
- Calculate distance between entities
- Compare to detection radius
- Add to detected threats list
- Combine convoy and drone detections
- Share intelligence across all friendly units
Threat Classification
- HIGH: Distance < 100px, heading toward convoy, speed > 0.05
- MEDIUM: Distance < 150px, heading toward convoy
- LOW: Distance < 200px
- MINIMAL: Beyond 200px
- Convoy: Blue circle (20px radius)
- Drones: Purple circles (6px radius)
- Attackers: Red circles (10px radius)
- Checkpoints: Purple rings (active), green checks (completed)
- Final Goal: Green triangle
- Detection Radii: Semi-transparent colored circles
- Detection Lines: Dashed lines to detected threats
- Restricted Zones: Orange striped areas
npm run buildnpm run previewnpm run lint- React 19 - UI framework
- Vite - Build tool and dev server
- HTML5 Canvas - 2D rendering
- AWS SDK - Timestream integration (optional)
- ESLint - Code linting
- Frame Rate: 60 FPS target
- Snapshot Overhead: <1% CPU impact
- Memory Usage: ~1KB per snapshot
- Local Storage: ~1MB per 1000 snapshots
- Maritime Security Training: Simulate convoy protection scenarios
- Drone Deployment Analysis: Test different drone configurations
- Threat Detection Research: Analyze detection patterns and coverage
- Pathfinding Algorithms: Test navigation through restricted areas
- Data Analysis: Export and analyze simulation behavior
- A* pathfinding implementation
- Collision avoidance with restricted zones
- Multiple convoy ships in formation
- Drone deployment strategies
- Real-time threat response behaviors
- Mission replay from snapshots
- 3D visualization mode
- Multiplayer/collaborative scenarios
- AWS_SETUP.md - Complete AWS Timestream setup guide
- SNAPSHOT_SYSTEM_README.md - Snapshot system documentation
- .env.example - Configuration options
This is a simulation project for maritime convoy defense research and training. Feel free to:
- Add new behaviors and movement patterns
- Implement additional threat detection algorithms
- Create visualization improvements
- Add new snapshot event types
- Enhance the AI decision-making
MIT
For issues or questions:
- Check the documentation files
- Review browser console for errors
- See AWS_SETUP.md for AWS-specific issues
Built with React + Vite | Data powered by AWS Timestream (optional)