[WIP] use-ammojs

Fast Physics hooks for use with react-three-fiber.

Built on top of three-ammo, which runs the wasm ammo.js library in a seperate web-worker and syncs three objects using SharedArrayBuffers.

Why not use use-cannon instead?

use-cannon is great and a inspiration for this package, but it is missing features and lacks performance with many objects or large gltf imports. ammo.js is a direct wrapper around the powerful Bullet Physics engine.

At the time of writing however use-cannon is more mature and great for small projects.

Roadmap

• Create a Physics World as a React context and simulate it in a web-worker
• Sync three objects to physics rigid-bodies
• Expose useful functions from the bullet api trough the hook (e.g. setPosition/applyImpulse/more...)
• Add Raycast queries
• Add Constraints between rigid bodies
• Improve the automatic shape detection (set shapeType automatically based on the three Mesh type)
• Add Softbody support (ropes, cloth, squishy balls, see docs)
• Add Examples to the documentation
• Implement convenience features (pausing simulation / access to physics performance info)
• Support collision callbacks

Documentation

1. Wrap your scene in a Physics Provider

import { Physics } from "use-ammojs";

<Physics drawDebug>
  [...] 
</Physics>

2.a Make objects physical

Automatically parse Shape parameters from the three Mesh (courtesy of three-to-ammo):

import { Box } from "@react-three/drei";
import { usePhysics, ShapeType } from "use-ammojs";

function MyBox(){
    const [ref] = usePhysics(() => ({ mass: 1, position: [0, 2, 4], shapeType: ShapeType.BOX }));

    return (
      <Box ref={ref}>
        <meshBasicMaterial attach="material" color="red" />
      </Box>
    );
}

or define Collision Shapes manually:

TODO

or add collisions to an imported gltf scene:

TODO

2.a Make objects squishy

TODO

3.a Add Constraints

TODO

3.b Add Raycasts

TODO

4 Update positions

TODO

Local Development of use-ammojs

const path = require("path");

[...]

// Fix that prevents a duplicate react library being imported when using a linked yarn package
webpackConfig.resolve.alias = {
  ...webpackConfig.resolve.alias,
  react: path.resolve("./node_modules/react"),
  "react-three-fiber": path.resolve("./node_modules/react-three-fiber"),
  three: path.resolve("./node_modules/three"),
};

[...]

1. Run yarn link in use-cannonjs root directory
2. Run yarn link use-cannonjs in your project's directory
3. Run yarn start in use-cannonjs to start the development bunlder
4. Run your project