An interactive TypeScript space simulation library where celestial mechanics meet artistic expression
Where Stars Drift is a high-performance canvas-based simulation engine that brings space to life. Watch black holes consume stars, starship fleets navigate in formation, and nebulas drift across the cosmic void - all rendered in real-time with realistic physics.
Born from a simple starfield background, it evolved into a complete 2D space engine inspired by classics like Homeworld and Freelancer.
- Gravitational simulation with spatial optimization (quadtree)
- Black holes that actually consume stars and merge with each other
- Fleet formations with tactical AI and collision avoidance
- 60 FPS with 1000+ entities through aggressive optimization
- 5 black hole types - Each with unique visual effects (vortex, accretion disk, lensing, warped disk)
- 9 ship categories - From nimble fighters to massive capital ships
- Dynamic fleets - V-formation, defensive sphere, line abreast, and more
- Clan system - Color-coded factions with unique behaviors
- TypeScript-first with full type safety
- Framework agnostic - Pure canvas, works everywhere
- Highly configurable - Control every aspect of the simulation
- Performance monitoring built-in for optimization
Try it: Demo
Screenshot: (Coming Soon) A simulation showing a vortex black hole consuming stars while fleets patrol in formation
npm install @where-stars-drift/coreimport { WhereStarsDrift } from '@where-stars-drift/core';
const canvas = document.getElementById('canvas') as HTMLCanvasElement;
const simulation = new WhereStarsDrift(canvas, {
starsCount: 1000,
interactive: true,
debug: false,
showCatalog: false,
showGrid: true,
showGithubLink: true
});
simulation.start();
// Get basic stats
const stats = simulation.getStats();
console.log(`FPS: ${stats.fps}, Stars: ${stats.starCount}, Ships: ${stats.starshipCount}`);'use client';
import { useRef, useEffect } from 'react';
import { WhereStarsDrift } from '@where-stars-drift/core';
export function SpaceBackground() {
const canvasRef = useRef<HTMLCanvasElement>(null);
useEffect(() => {
if (!canvasRef.current) return;
const simulation = new WhereStarsDrift(canvasRef.current, {
starsCount: 500,
interactive: true,
showGrid: false
});
simulation.start();
return () => simulation.destroy();
}, []);
return <canvas ref={canvasRef} className="fixed inset-0 -z-10" />;
}// Stars with orbital systems
- Regular stars with twinkling
- Pulsars with rotation effects
- Ringed planets
- Multiple orbit lanes with docking points
// Black Holes (5 types)
- Standard: Classic singularity
- Lensing: Gravitational light bending
- Accretion Disk: Rotating matter disk
- Vortex: Swirling particle effects
- Warped Disk: Spacetime distortion
// All with realistic physics:
- Star consumption with supernovas
- Black hole mergers
- Gravitational attraction
- Energy streams between black holes// 9 Ship Categories
- Capital Ships: Dreadnought, Battleship, Carrier
- Cruisers: Heavy, Light, Battlecruiser
- Escorts: Destroyer, Frigate, Corvette
- Support: Monitor, Troop Transport
- Small Craft: Fighter, Bomber
- Exploration: Explorer, Science Frigate, Pathfinder
- Commerce: Hauler, Colony Ship, Shuttle
- Mining: Mining Vessel, Gas Miner, Salvage Ship
- Diplomatic: Courier, Hospital Ship
// Fleet Formations
- V-Formation (classic)
- Line Abreast
- Defensive Sphere
- Column
- Wedge
- And more...
// AI Behaviors
- Patrol between stars
- Dock at orbital stations
- Form/disband fleets dynamically
- Flee from mouse cursor
- Maintain formation spacing- Nebulas: Drifting cosmic clouds
- Comets: Periodic visitors
- Meteors: Random events
- Supernovas: Explosion effects when stars are consumed
- Energy Streams: Bezier curves between black holes
- Cosmic Dust: Subtle static background layer
- Trails: Ship movement trails// Optimizations
- Quadtree spatial partitioning
- Frustum culling (off-screen entities skipped)
- Cached array references
- Pre-rendered static layers
- Incremental quadtree updates
// Monitoring
const metrics = simulation.getPerformanceMetrics();
// Returns: fps, avgFps, frameTime, updateTime,
// renderTime, physicsTime, bottleneck, etc.
// Results
- 60 FPS with 1000 entities
- 45+ FPS with 2000 entities
- Scales to mobile devicesconst simulation = new WhereStarsDrift(canvas, {
// Number of background stars
starsCount: 1000, // default: 1000
// Enable mouse interaction (ships flee from cursor)
interactive: true, // default: true
// Show debug information and FPS counter
debug: false, // default: false
// Show entity catalog panel (developer tool)
showCatalog: false, // default: false
// Show background sector grid
showGrid: true, // default: true
// Show "Where Stars Drift" link in corner
showGithubLink: true // default: true
});// Change settings at runtime
simulation.setInteractive(false); // Disable mouse interaction
simulation.setDebug(true); // Show debug overlay
simulation.setShowCatalog(true); // Show entity catalog
simulation.setShowGrid(false); // Hide sector grid
simulation.setShowGithubLink(false); // Hide GitHub link
// Get current statistics
const stats = simulation.getStats();
// Returns: { fps, avgFps, starCount, starshipCount, frameCount }
console.log(`FPS: ${stats.fps.toFixed(0)}`);
console.log(`Stars: ${stats.starCount}`);
console.log(`Starships: ${stats.starshipCount}`);
// Lifecycle methods
simulation.start(); // Start animation loop
simulation.stop(); // Pause animation
simulation.destroy(); // Clean up resourcesThe following features are planned but not yet implemented:
// ๐ฎ PLANNED - Not available yet!
const simulation = new WhereStarsDrift(canvas, {
// Granular entity counts
entities: {
starsCount: 1000,
nebulasCount: 5,
blackHolesCount: 3,
starshipsCount: 30,
fleetsCount: 2,
clansCount: 3
},
// Show/hide specific layers
visibility: {
nebulas: true,
starships: false,
energyStreams: true,
cosmicDust: true
},
// Black hole type control
blackHoles: {
types: ['VORTEX', 'ACCRETION_DISK'],
distribution: 'equal'
},
// Cosmic dust layer
cosmicDust: {
enabled: true,
particleCount: 500,
twinkleEffect: true
}
});
// ๐ฎ PLANNED - Performance metrics
const metrics = simulation.getPerformanceMetrics();
// { fps, frameTime, updateTime, renderTime, physicsTime,
// bottleneck, performanceScore, ... }
// ๐ฎ PLANNED - Visibility controls
simulation.setVisibility('nebulas', false);See: v1.2.0 Milestone for complete roadmap
- Core simulation engine
- 5 black hole types with unique visuals
- 9 ship categories with 20+ ship classes
- 10+ fleet formations
- Quadtree spatial optimization
- Clan system
- Physics simulation (gravity, collisions)
- Visual effects (nebulas, supernovas, energy streams)
- Debug tools and catalogs
- TypeScript with strict mode
- NPM package published
- Performance optimizations (frustum culling, caching)
- Enhanced configuration API
- Performance monitoring system
- Class hierarchy refactoring (abstract ships & black holes)
- Cosmic dust layer
- Adaptive quality system
- Save/load simulation state
- Camera system (pan, zoom, follow)
- Event system for custom behaviors
- Sound effects
- More entity types (wormholes, space stations, asteroids)
- WebGL renderer (optional)
Replace boring static backgrounds with a living universe:
const simulation = new WhereStarsDrift(canvas, {
entities: { starsCount: 500, blackHolesCount: 1 },
visibility: { starships: false, fleets: false }
});Represent data as entities:
// Each star could represent a data point
// Clusters = black holes
// Connections = energy streamsBuild RTS-style space games:
// Already includes:
// - Fleet formations
// - Tactical AI
// - Collision detection
// - Physics simulationDemonstrate physics concepts:
// Gravity simulation
// Orbital mechanics
// N-body problems
// Spatial optimizationCreate unique cosmic scenes:
const simulation = new WhereStarsDrift(canvas, {
blackHoles: {
types: ['VORTEX'],
distribution: { 'VORTEX': 10 }
},
entities: { starsCount: 2000 }
});
// Capture frames for artworkWhere Stars Drift is more than a library - it's a love letter to space simulation games.
- Every black hole tells a story - Watch them merge, consume stars, and grow stronger
- Every starship has purpose - Patrol routes, docking procedures, fleet formations
- Every star drifts with intention - Physics-driven, not random
This is a passion project for:
- ๐ฎ Space game enthusiasts
- ๐ป Creative coders
- ๐ฌ Physics simulation lovers
- ๐จ Generative artists
- ๐ Anyone who looks up at the night sky and wonders
This is currently a private project, but contributions are welcome by invitation.
Interested in contributing?
- Performance optimizations
- New entity types
- Visual effects
- Physics improvements
- Documentation
Reach out at @vlavrynovych
Proprietary License
Copyright ยฉ 2026 Volodymyr Lavrynovych. All Rights Reserved.
This software is proprietary. See LICENSE for details.
The NPM package @where-stars-drift/core is available for personal and commercial use under specific terms.
Inspired by:
- Homeworld series - Formation mechanics and fleet control
- Freelancer - Space atmosphere and visual style
- Elite Dangerous - Scale and immersion
- The beauty of the cosmos
Technical Inspiration:
- Quadtree spatial partitioning
- N-body physics simulation
- Canvas2D rendering optimization
Special Thanks:
- To Victoria, the first black hole in this universe ๐ซ
- To everyone who looks up at the stars and dreams
- NPM Package: @where-stars-drift/core
- Website: (Coming Soon)
- GitHub Organization: @where-stars-drift
Made with โค๏ธ and TypeScript
"In space, no one can hear you compile" ๐
Photo by Carlos Kenobi on Unsplash