Ammo.js Wrapper

A TypeScript wrapper for Ammo.js with improved WASM loading and TypeScript typings.

Features

• TypeScript Support: Full TypeScript definitions from ammojs-typed
• Improved WASM Loading: Automatically loads WASM files from alongside the JavaScript files
• Environment Support: Works in browsers, Node.js, and Web Workers
• Module Formats: Supports both CommonJS and ES Modules
• Bundle Friendly: Works with webpack, Rollup, Vite, and other bundlers

Installation

npm install ammo

Usage

Basic Usage

import { Ammo } from 'ammo';

// Initialize Ammo.js
Ammo().then((ammo) => {
  // Use Ammo.js as usual
  const vec = new ammo.btVector3(0, 0, 0);
  // ...
});

With TypeScript

import { Ammo, AmmoInstance } from 'ammo';

Ammo().then((ammo: AmmoInstance) => {
  // Fully typed Ammo.js instance
  const vec = new ammo.btVector3(0, 0, 0);
  
  // Create a physics world
  const collisionConfiguration = new ammo.btDefaultCollisionConfiguration();
  const dispatcher = new ammo.btCollisionDispatcher(collisionConfiguration);
  const broadphase = new ammo.btDbvtBroadphase();
  const solver = new ammo.btSequentialImpulseConstraintSolver();
  const world = new ammo.btDiscreteDynamicsWorld(
    dispatcher,
    broadphase,
    solver,
    collisionConfiguration
  );
  
  // Set gravity
  world.setGravity(new ammo.btVector3(0, -9.81, 0));
  
  // ... rest of your physics code
});

Custom WASM Path

import { Ammo } from 'ammo';

// Initialize with custom WASM path
Ammo({ 
  wasmPath: '/path/to/ammo.wasm.wasm',
  onReady: (ammo) => {
    // Called when Ammo.js is ready to use
    console.log('Ammo.js is ready!');
  }
}).then((ammo) => {
  // Use Ammo.js
});

Advanced Configuration

import { Ammo, AmmoInitOptions } from 'ammo';

const options: AmmoInitOptions = {
  // Custom WASM path
  wasmPath: '/path/to/ammo.wasm.wasm',
  
  // Called when Ammo.js is ready
  onReady: (ammo) => {
    console.log('Ammo.js is ready!');
  },
  
  // Custom locateFile function for advanced WASM loading
  locateFile: (filename, prefix) => {
    if (filename.endsWith('.wasm')) {
      return `/custom/wasm/path/${filename}`;
    }
    return prefix + filename;
  }
};

Ammo(options).then((ammo) => {
  // Use Ammo.js
});

API Reference

Main Export

import { Ammo } from 'ammo';

The Ammo export is a function that initializes Ammo.js and returns a Promise that resolves to the Ammo.js instance.

Types

import { AmmoInitOptions, AmmoInstance, AmmoModule } from 'ammo';

• AmmoInitOptions: Options for initializing Ammo.js
• AmmoInstance: The type of the Ammo.js instance
• AmmoModule: The type of the Ammo.js module

Initialization Options

interface AmmoInitOptions {
  // Optional path to the Ammo WASM file
  wasmPath?: string;
  
  // Optional callback for when Ammo is loaded
  onReady?: (ammo: AmmoInstance) => void;
  
  // Optional locateFile function to customize WASM file location
  locateFile?: (filename: string, prefix: string) => string;
}

Troubleshooting

WASM File Not Found

If you get an error like "Failed to fetch" or "Unable to load WASM file", make sure:

1. The WASM file is in the correct location
2. The path to the WASM file is correct
3. Your server is configured to serve .wasm files with the correct MIME type (application/wasm)

Node.js Support

In Node.js environments, make sure you have the following configurations:

1. Set the correct WASM file path in the options
2. If using TypeScript, ensure your tsconfig.json has the correct module resolution settings

Tests

The package includes tests for different environments:

# Run Node.js tests
npm run test:node

# Run TypeScript type tests
npm run test:types

# Start a server to run browser tests
npm run test:browser

License

This project is licensed under the MIT License - see the LICENSE file for details.