Where Stars Drift ✨

A TypeScript canvas library for creating interactive space simulations with realistic physics, celestial bodies, and dynamic fleet behaviors.

Born from a simple starfield background, Where Stars Drift evolved into a complete 2D space simulation engine inspired by classics like Homeworld and Freelancer.

Table of Contents

• 🚀 What's New in v1.2.0?
• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• ⚙️ Configuration (SimulationConfig)
  • General Settings
  • Entity Settings (entities)
• 🌌 Features in Detail
  • Stars
  • Black Holes
  • Starships
  • Physics & Interaction
• 🎯 Roadmap
• 📄 License
• 🤝 Contributing

🚀 What's New in v1.2.0?

Version 1.2.0 is a massive leap forward in performance, customization, and architectural maturity.

• Up to 5x Performance Boost: A re-architected core loop with frustum culling and optimized caching now comfortably renders 1500+ entities at 60 FPS.
• Hierarchical Performance Profiler: A powerful new in-game panel to visually identify performance bottlenecks in real-time.
• Advanced Configuration: Granular controls to toggle visibility and set counts for every entity type, plus configure black hole spawning.
• True Polymorphism: Starship and BlackHole classes are now truly polymorphic, with specialized subclasses for unique behaviors (e.g., CapitalShip, VortexBlackHole).
• New Visuals & Systems:
  • A rich, atmospheric CosmicDust layer with a configurable twinkle effect.
  • An AdaptiveQuality system that automatically adjusts effects to maintain a target framerate.

✨ Features

• Celestial Bodies: Multiple star types, pulsars, ringed planets, and black holes with gravitational effects.
• Dynamic Entities: Starships with AI behaviors, fleet formations, clans, and tactical movements.
• Visual Effects: Nebulas, comets, meteors, supernovas, and energy streams between black holes.
• Physics Engine: Real gravity simulation, collision detection, and spatial optimization via quadtree.
• Interactive: Mouse-driven interactions, and responsive animations.
• Highly Configurable: Granular control over every entity type's visibility, count, and behavior.

📦 Installation

npm install @where-stars-drift/core

🚀 Quick Start

The simulation provides a rich set of defaults, so you only need to specify what you want to change. All properties are optional.

import { WhereStarsDrift } from '@where-stars-drift/core';

// Get your canvas element
const canvas = document.getElementById('simulation-canvas') as HTMLCanvasElement;

// Create a highly customized simulation instance. All properties are optional.
const simulation = new WhereStarsDrift(canvas, {
  interactive: true,
  debug: false,
  showPerformancePanel: true, // Show the new performance metrics
  entities: {
    stars: {
      count: 800, // More stars for a denser field
    },
    blackHoles: {
      count: 5,
      // Only spawn specific types of black holes
      types: ['VORTEX', 'ACCRETION_DISK'],
    },
    starships: {
      enabled: true,
      count: 50,
      fleets: {
        enabled: true,
        count: 5,
      }
    },
    cosmicDust: {
      enabled: true,
      particleCount: 1500,
      twinkleEffect: true,
    }
  }
});

simulation.start();

// To clean up when the component unmounts
// simulation.destroy();

⚙️ Configuration (SimulationConfig)

When creating a WhereStarsDrift instance, you can pass a configuration object to customize its behavior. All properties are optional. The simulation provides a rich default configuration, so you only need to override what you want to change.

General Settings

These properties control the overall behavior and display of the simulation.

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | interactive | boolean | true | Enables mouse interactions like stars fleeing the cursor. Does not affect core simulation AI. | | debug | boolean | false | Enables debug mode, which shows visualization helpers like entity hover info and target lines. | | showCatalog | boolean | false | Toggles the visibility of the interactive debug catalog panel. debug must be true. | | showPerformancePanel| boolean | false | Toggles the visibility of the performance metrics overlay. | | showGrid | boolean | true | Toggles the visibility of the background sector grid. | | showGithubLink | boolean | true | Toggles the visibility of the link to the project's GitHub repository. | | adaptiveQuality | boolean | true | Automatically adjusts visual effects quality to maintain target FPS. |

Entity Settings (entities)

The entities object provides granular control over each type of object in the simulation. You can enable/disable them, set their counts, and configure type-specific properties.

Stars

{
  entities: {
    stars: {
      enabled: true,
      count: 30,
      types: ['Standard', 'Pulsar', 'RingedPlanet'],
      pulsarChance: 0.02,
      ringedPlanetChance: 0.03,
    }
  }
}

Starships & Fleets

{
  entities: {
    starships: {
      enabled: true,
      count: 30,
      fleets: {
        enabled: true,
        count: 3,
      },
    }
  }
}

Black Holes

{
  entities: {
    blackHoles: {
      enabled: true,
      count: 3,
      types: ['ACCRETION_DISK', 'VORTEX', 'LENSING', 'WARPED_DISK', 'STANDARD'],
      distribution: 'random', // or 'equal' or Record<BlackHoleType, number>
    }
  }
}

Nebulas

{
  entities: {
    nebulas: {
      enabled: true,
      count: 5,
      isStatic: false, // Optional: if true, nebulas will not move
    }
  }
}

Comets

{
  entities: {
    comets: {
      enabled: true,
      count: 1,
    }
  }
}

Cosmic Dust

A subtle, atmospheric layer of fine dust particles to enhance the depth of space.

{
  entities: {
    cosmicDust: {
      enabled: true,
      particleCount: 500,
      particleSize: 1.5,
      opacity: 0.6,
      colorVariation: true,
      twinkleEffect: true, // If true, dust twinkles. Can impact performance.
    }
  }
}

🌌 Features in Detail

Stars

• Regular Stars: Twinkling stars with various colors and optional coronas.
• Pulsars: Rotating stars with a rhythmic pulsing effect.
• Ringed Planets: Planets with one or more orbital rings, complete with docking points for starships.

Black Holes

• Multiple visual styles (e.g., Lensing, Accretion Disk, Vortex).
• Gravitational pull affecting nearby stars and other black holes.
• Star consumption that triggers supernova effects.
• Energy streams rendered between interacting black holes.

Starships

• A wide variety of ship classes (Fighter, Corvette, Frigate, Capital, etc.).
• AI behaviors (idle, traveling, docking, orbiting, fleeing).
• A clan system with unique colors and icons.
• Complex fleet formations with tactical movements.

Physics & Interaction

• Gravity: Gravitational forces realistically simulated between massive bodies.
• Collision Detection: Efficiently managed via a spatial quadtree to handle black hole mergers.
• Orbital Mechanics: Ships can enter orbits around stars.
• Mouse Interaction: Ships can flee from the cursor, and entities can be hovered to display debug info.

Cosmic Dust

• Atmospheric Depth: A highly performant background layer of fine dust particles to create a richer space environment.
• Configurable: Control particle count, size, opacity, and color variation.
• Twinkle Effect: An optional, subtle shimmer effect to bring the background to life, which is also managed by the adaptive quality system.

🎯 Roadmap

• [X] Performance optimizations
• [X] Additional fleet formation patterns
• [X] More starship classes and behaviors
• [ ] React/Vue/Angular wrapper components
• [ ] Camera System (Pan, Zoom, Follow)
• [ ] Save/Load Simulation State
• [ ] Event System for Custom Behaviors
• [ ] Sound Effects for Key Events
• [ ] More Entity Types (Wormholes, Stations, Asteroids)
• [ ] WebGL Renderer (Performance Boost)

📄 License

Copyright © 2026 Volodymyr Lavrynovych. All Rights Reserved.

This software is proprietary and confidential. See LICENSE for details.

🤝 Contributing

This is a private repository. Contributions are by invitation only.

Dedicated to Victoria, the first black hole in this universe 💫