Ballistics Engine (WebAssembly)

High-performance ballistics trajectory calculations for JavaScript and TypeScript applications. This package provides WebAssembly bindings for the ballistics-engine library, delivering near-native performance in the browser.

Project Website: https://ballistics.rs/

Installation

npm install ballistics-engine

Quick Start

ES Modules (Browser/Bundler)

import init, { Calculator } from 'ballistics-engine';

// Initialize the WASM module first
await init();

// Create a calculator with default values (.308 Win, 168gr at 2700 fps)
const calc = new Calculator();

// Configure your load
calc
  .setVelocity(2700)           // fps
  .setBC(0.475)                // G1 ballistic coefficient
  .setMass(168)                // grains
  .setDiameter(0.308)          // inches
  .setZeroRange(200)           // zero at 200 yards
  .setWind(10, 90);            // 10 mph from the right

// Calculate trajectory at a specific range
const result = calc.calculateTrajectory(500);
console.log(result);
// { range_yards: 500, drop_inches: -48.2, windage_inches: 15.3, velocity_fps: 2145, energy_ftlb: 1715, time_sec: 0.62 }

// Get full trajectory table
const trajectory = calc.getFullTrajectory();
console.log(trajectory);
// Array of trajectory points from 0 to max range

// Clean up when done
calc.free();

With TypeScript

import init, { Calculator } from 'ballistics-engine';

async function main() {
  await init();

  const calc = new Calculator()
    .setVelocity(3000)
    .setBC(0.620)
    .setMass(140)
    .setDiameter(0.264)
    .setDragModel('g7')
    .setZeroRange(100);

  const result = calc.calculateTrajectory(1000);
  console.log(`Drop at 1000 yards: ${result.drop_inches.toFixed(1)} inches`);

  calc.free();
}

main();

API Reference

Calculator Class

A fluent, chainable API for trajectory calculations.

Constructor

const calc = new Calculator();

Creates a calculator with sensible defaults:

• .308 Winchester 168gr at 2700 fps
• G1 drag model
• Standard atmosphere (59°F, 29.92 inHg)

Configuration Methods

All methods return this for chaining.

| Method | Parameters | Description | |--------|------------|-------------| | setVelocity(fps) | number | Muzzle velocity in feet per second | | setBC(bc) | number | Ballistic coefficient (G1 or G7) | | setMass(grains) | number | Bullet weight in grains | | setDiameter(inches) | number | Bullet diameter in inches | | setDragModel(model) | 'g1' | 'g7' | Drag model to use | | setZeroRange(yards) | number | Zero distance in yards | | setSightHeight(inches) | number | Scope height above bore | | setMaxRange(yards) | number | Maximum calculation range | | setWind(mph, degrees) | number, number | Wind speed and direction (0°=headwind, 90°=from right) | | setTemperature(fahrenheit) | number | Ambient temperature | | setPressure(inHg) | number | Barometric pressure | | setHumidity(percent) | number | Relative humidity (0-100) | | setAltitude(feet) | number | Shooting altitude | | enableSpinDrift(enabled, twistRate?) | boolean, number? | Enable spin drift (twist rate in inches) | | enableCoriolis(enabled, latitude?) | boolean, number? | Enable Coriolis effect |

Calculation Methods

// Calculate at specific range
const point = calc.calculateTrajectory(500);

// Get full trajectory table
const trajectory = calc.getFullTrajectory();

Result Object

interface TrajectoryPoint {
  range_yards: number;      // Distance from muzzle
  drop_inches: number;      // Bullet drop (negative = below line of sight)
  windage_inches: number;   // Wind deflection (positive = right)
  velocity_fps: number;     // Remaining velocity
  energy_ftlb: number;      // Remaining energy
  time_sec: number;         // Time of flight
}

WasmBallistics Class

A CLI-style interface for running commands as strings.

import init, { WasmBallistics } from 'ballistics-engine';

await init();

const ballistics = new WasmBallistics();

// Run trajectory command
const output = ballistics.runCommand(
  'trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --auto-zero 200 --max-range 1000 -o json'
);

console.log(JSON.parse(output));

ballistics.free();

Examples

Long-Range Trajectory

const calc = new Calculator()
  .setVelocity(2850)
  .setBC(0.690)              // G7 BC
  .setMass(230)
  .setDiameter(0.338)
  .setDragModel('g7')
  .setZeroRange(100)
  .setMaxRange(1500)
  .setWind(10, 270)          // 10 mph from left
  .setAltitude(5000)         // High altitude
  .setTemperature(75);

const trajectory = calc.getFullTrajectory();

// Find data at 1000 yards
const point1000 = trajectory.find(p => p.range_yards === 1000);
console.log(`At 1000 yards: ${point1000.drop_inches.toFixed(1)}" drop, ${point1000.windage_inches.toFixed(1)}" wind`);

Environmental Effects

// Hot day, high altitude
const calc = new Calculator()
  .setVelocity(2700)
  .setBC(0.475)
  .setMass(168)
  .setDiameter(0.308)
  .setTemperature(95)        // Hot day
  .setAltitude(8000)         // Mountain shooting
  .setPressure(24.5)         // Lower pressure at altitude
  .setHumidity(20);          // Dry air

// Velocity will stay higher due to thinner air

With Spin Drift

const calc = new Calculator()
  .setVelocity(2700)
  .setBC(0.475)
  .setMass(168)
  .setDiameter(0.308)
  .enableSpinDrift(true, 10)  // 1:10" twist, right-hand
  .setZeroRange(100)
  .setMaxRange(1000);

// Spin drift adds to windage at long range
const point = calc.calculateTrajectory(1000);
console.log(`Spin drift at 1000: ${point.windage_inches.toFixed(1)}"`);

Browser Usage

With a Bundler (Vite, Webpack, etc.)

import init, { Calculator } from 'ballistics-engine';

async function setupBallistics() {
  await init();
  // Ready to use
}

Without a Bundler (Script Tag)

<script type="module">
  import init, { Calculator } from './node_modules/ballistics-engine/ballistics_engine.js';

  init().then(() => {
    const calc = new Calculator();
    // ...
  });
</script>

Performance

WebAssembly provides near-native performance:

• Single trajectory (1000 yards): ~1ms
• Full trajectory table (1500 points): ~5ms
• Zero calculation: ~2ms

TypeScript Support

Full TypeScript definitions are included. Import types:

import type { Calculator, WasmBallistics } from 'ballistics-engine';

Memory Management

The Calculator and WasmBallistics classes allocate memory in the WASM heap. Call .free() when done to prevent memory leaks:

const calc = new Calculator();
try {
  // Use calculator
  const result = calc.calculateTrajectory(500);
} finally {
  calc.free();
}

Or use the Symbol.dispose for automatic cleanup (when supported):

{
  using calc = new Calculator();
  const result = calc.calculateTrajectory(500);
} // Automatically freed

Related Packages

• Node.js package: Use ballistics-engine from npm (same package, works in Node.js too)
• Rust crate: crates.io/crates/ballistics-engine
• Python package: pypi.org/project/ballistics-engine

License

MIT OR Apache-2.0

Links

• Documentation
• GitHub Repository
• Live Demo