hecs-plugin-physx v0.17.0

Hecs Plugin PhysX

A plugin for Hecs that adds functionality to simulate physx-js bodies.

Usage

Install via npm/yarn:

yarn add hecs hecs-plugin-physx physx-js

This plugin depends on physx-js and expects you to load the wasm module as a global variable PhysX before instantiating your World. (note: this isn't ideal and will be improved on)

import PHYSX from 'physx-js'
import { World } from 'hecs'
import PhysXPlugin from 'hecs-plugin-physx'

function createWorld() {
  const world = new World({
    plugins: [PhysXPlugin],
    systems: [/* your systems */],
    components: [/* your components */],
  })
}

window.PhysX = PHYSX({
  onRuntimeInitialized() {
    createWorld()
  }
})

A world instance with this plugin installed can now use all of the features below:

World.physics

This prop is available if you want to extends the plugin. It contains all the shared parts for simulation such as the scene, layers and cooking.

World.physics.layers

Use this to specify which layers collide with each other. Layers are set on each Collider component (see below). There are 7 layers available and they all collide with each other by default.

const { layers } = world.physics
const Layers = {
  DEFAULT: 0,
  GHOST: 1,
}
layers.setCollision(Layers.DEFAULT, Layers.GHOST, false)

World.physics.setPassive(Boolean)

In certain cases such as an editor, you may want to register the plugin and its components but not have the physics simulated. Setting passive to false will disable the systems that build rigid bodies, collider shapes, and simulate physics.

RigidBody (Component)

This component describes the rigidbody the entity should have.

import { Transform } from 'hecs-plugins-core'
import { RigidBody } from 'hecs-plugins-physx'

entity
  .add(Transform)
  .add(RigidBody, { kind: 'DYNAMIC' })

Notes: Internally the plugin looks for a RigidBody component and will build the actual rigid body and attach it as a RigidBodyRef component. You can use this if you need to access the actual rigid body.

Collider (Component)

Describes a collider shape that should be attached to a rigid body. The shape will be attached to the closest entity that has a RigidBody component, starting from the current entity and walking up its parents. You can create compound colliders by having one parent RigidBody entity and multiple child Collider entities.

Notes: Internally this plugin looks for a Collider component, builds the shape and adds it as a ColliderRef component. It also attaches a ColliderBody component which contains the actual RigidBody is has been attached to.

import { Transform, Vector3 } from 'hecs-plugins-core'
import { Collider } from 'hecs-plugins-physx'

entity
  .add(Transform)
  .add(Collider, { 
    shape: 'BOX',
    boxSize: new Vector3(2, 4, 2),
  })

FixedJoint (Component)

Describes a fixed joint that should be attached to another entity.

Notes: Internally this plugin looks for a FixedJoint component, constructs the actual joint and adds it as a FixedJointRef component. When a fixed joint breaks, the FixedJoint and FixedJointRef components will be removed automatically. If you are adding your own functionality that depends on a fixed joint it is better to use the actual ref to determine it's existence.

import { Transform, Vector3 } from 'hecs-plugins-core'
import { RigidBody, Collider, FixedJoint } from 'hecs-plugins-physx'

entity
  .add(Transform)
  .add(RigidBody, { kind: 'DYNAMIC' })
  .add(Collider)
  .add(FixedJoint)