eulerjs API / @eulerjs/core

@eulerjs/core

The engine: worlds, bodies, colliders, joints, scene queries and the JavaScript backend.

Classes

Class	Description
BaseJoint	What every joint has: the bodies it ties, the loads it carries and when it breaks.
Body	A rigid body. The body frame is the frame its mass properties are expressed in, normally the local frame of the mesh it was built from. Dynamics happen about the centre of mass; position is the frame's origin, so a bound object's origin lands exactly on it.
BoxCollider	A box, centred on the collider's position, its edges along the collider's axes.
CapsuleCollider	A cylinder with rounded ends, along its y axis: the usual shape for limbs and characters.
Collider	The shape a body collides with: a description that every backend turns into its own shape. Its material and filter settings can be changed at any time.
ConeCollider	A solid cone along its y axis, tip up, such as a traffic cone. Its mass, ray casts and contacts with planes are exact; against other shapes it collides as a 16-sided pyramid.
ConeTwistJoint	A ball joint whose axis may only tilt within a cone and twist within limits, like a shoulder or a hip: the joint for ragdolls.
ConvexCollider	The convex hull of a set of points: any convex shape, such as a rock, a bevelled crate or the hull of a model. Coplanar triangles are merged into one polygon face, so a box-shaped hull has six square faces, which is what gives whole contact patches.
CylinderCollider	A solid cylinder along its y axis, such as a barrel, a log or a wheel. Its mass, ray casts and contacts with planes and spheres are exact, so it rolls smoothly on the ground; against other shapes it collides as a 16-sided prism.
DistanceJoint	Keeps two points, on two bodies or on a body and the world, a fixed distance apart. Its settings can be changed between steps; the backend reads them every step.
EulerError	Base class for every error eulerjs throws, so callers can catch the engine's errors as a group.
FixedJoint	Holds two bodies together as one, or a body in place in the world, until it breaks.
HeightfieldCollider	Terrain: a grid of heights, centred on the collider's origin, each cell split into two triangles. Solid below the surface, so whatever ends up beneath it is pushed back up. Only for static and kinematic bodies.
HingeJoint	Lets two bodies turn about one axis only, like a door on its hinges, a wheel on its axle or an elbow.
InvalidMassError	Mass, inertia or another physical quantity is missing, non-finite or physically impossible.
InvalidMeshError	A mesh can't be used for the requested computation, e.g. it isn't closed or is inside out.
JavaScriptBackend	The built-in backend, in plain JavaScript: semi-implicit Euler integration with an exact gyroscopic term, and joints and contacts solved over substeps substeps per step, by extended position-based dynamics (XPBD) or by soft step (see JavaScriptBackendOptions).
MassProperties	Mass, centre of mass and inertia tensor of a rigid body, all in the body's own frame. The inertia tensor is taken about the centre of mass.
PlaneCollider	An infinite flat ground: everything on the side its normal points away from is solid. Its normal is the collider's +y axis; turn it with rotation. Only for static and kinematic bodies.
SixDofJoint	The general joint: a frame fixed in each body, and for each of the six ways frame B can move relative to frame A (along its three axes, and twisting and swinging about them) whether it may, between which limits, and what drives it. Hinges, sliders, fixed joints and cone-twist joints are particular settings of it. Its settings can be changed between steps.
SliderJoint	Lets two bodies slide along one axis only, without turning, like a drawer, a piston or a lift.
SphereCollider	A sphere, centred on the collider's position.
TargetJoint	Pulls a body toward a pose in the world, as a spring and damper with limits: for dragging a body with the mouse, carrying it, or leading an active ragdoll along by its hips. Move the target with setTarget as often as you like. It pulls as hard as a spring of its frequency on the body's mass, so a body it holds up sags by g / (2π frequency)²; take away its gravity (gravityScale = 0) to have it hold the pose exactly.
Voxels	A solid approximated by equal cubes, in the frame of the geometry it was built from. Used to sample how much of a hull is under water, and to give open meshes mass properties.
World	The simulation: bodies, joints and plugins, stepped at a fixed timestep by its backend. Make one next to your three.js scene, add bodies bound to your objects, and call update with each frame's time to step it and move the objects to their bodies.

Interfaces

Interface	Description
BaseJointOptions	-
Behavior	Per-body extension, e.g. buoyancy or a sail. Runs every fixed step while the body is in a world.
BodyInstance	One instance of an InstancedMesh, for a body to be drawn as.
BodyMotion	Where a body is and how it moves: what the world and a backend exchange every step.
BodyOptions	-
BoxColliderOptions	-
CapsuleColliderOptions	-
ColliderOptions	-
ColliderPose	Where a collider is in the world on the current substep.
ConeColliderOptions	-
ConeTwistJointOptions	-
Contact	A contact that pushed two bodies apart during the last step, for reading after it.
ContactEvent	Two colliders that started or stopped touching.
ConvexColliderOptions	-
ConvexFace	One flat face of a hull: its outward normal, its plane (normal · point = offset) and its corners, counter-clockwise from outside.
CylinderColliderOptions	-
DistanceJointOptions	-
HeightfieldColliderOptions	-
HingeJointOptions	-
InstancedBodyOptions	Options for the bodies world.addInstances makes, one for each instance of an InstancedMesh.
JavaScriptBackendOptions	-
JointBreakEvent	A joint that broke, having carried more than its breakForce or breakTorque; the world has removed it.
JointDrive	A drive pushes an axis toward a target, as a spring-damper with a force limit: a motor holds a speed (targetVelocity, and by default infinite damping), a servo holds a position (targetPosition with a stiffness, and some damping to keep it from ringing). Force = stiffness × (targetPosition - position) + damping × (targetVelocity - velocity), at most maxForce, all solved implicitly so that any stiffness is stable.
JointFrame	A frame fixed in a body, in the body's own frame, or in the world for a joint without body B.
JointLimits	The lowest and highest an axis may go.
JointMeasurement	Where a joint's moving frame is relative to its base frame (see SixDofJoint.roles).
MeshMassOptions	-
MeshTopology	-
ObjectBodyOptions	Options for a body made from a three.js object, which supplies its shape and starting pose.
OrientationDrive	A drive that turns the moving frame toward an orientation relative to the base frame, about whichever axis takes it there (a slerp drive): the servo for ball joints, such as an active ragdoll's shoulders and hips. Stiffness and damping as for a JointDrive, in N·m/rad and N·m·s/rad, or frequency and dampingRatio.
OverlapHit	A collider that a shape overlaps.
OverlapOptions	Which colliders a scene query finds.
PhysicsBackend	What actually simulates a world. The world, its bodies and joints are the same whatever the backend; the backend keeps its own copy of each body and the world keeps the two in step:
Plugin	World-level extension. Every hook is optional and runs once per fixed step, in this order: beforeStep, then every body's behaviours, then applyForces, then the backend simulates, then afterStep.
QueryFilter	Which colliders a scene query finds.
QueryHit	Where a ray, or a shape swept along a line, first touches a collider.
RayCastOptions	Which colliders a scene query finds.
SensorEvent	Something that came into, or left, a sensor.
SensorOverlap	Two colliders overlapping during the last step, at least one of them a sensor.
ShapeCastOptions	Which colliders a scene query finds.
SixDofJointOptions	-
SliderJointOptions	-
SphereColliderOptions	-
StepSettings	The world's settings a backend steps with. The world passes itself; they can change between steps.
TargetJointOptions	-
VoxelizeOptions	-
WorldEvents	The events a world sends, after each step, by name.
WorldOptions	-

Type Aliases

Type Alias	Description
AxisMotion	What a joint lets one of its six axes do: nothing ('locked'), anything ('free'), or move between two limits, in metres along a linear axis or radians about an angular one.
BodyType	- dynamic bodies are moved by forces and gravity. - kinematic bodies move with the velocity you give them and ignore forces. - static bodies never move.
ColliderShorthand	The shapes collider can name, to be fitted around an object's meshes.
Joint	Every kind of joint: hinges, sliders, fixed and cone-twist joints are SixDofJoints. A backend that can't simulate one throws when it is added.
MassSpecification	How much a mesh weighs: either its total mass or the density of its material.
SixAxes	The three linear axes, then the three angular ones (twist about x, swing about y, swing about z).
TriangleVisitor	-
WorldEventListener	-
WorldEventName	-

Variables

Variable	Description
DEFAULT_CELLS_ALONG_LONGEST_SIDE	How many cells fit along the longest side of a geometry when no cell size is given.
DEFAULT_DENSITY	Density used when a body made from an object is given neither a mass nor a density: water.
ROUND_ROLLING_RESISTANCE	The rolling resistance a ball, capsule, cylinder or cone has unless told otherwise: without any, one rolling on flat ground keeps all its speed for ever, as an ideal rigid body would, where a real one is slowed by the give in both surfaces. A barrel knocked rolling at 1.5 m/s comes to rest in about 12 s.

Functions

Function	Description
analyzeTopology	Counts how many triangles share each edge after welding vertices closer than weldTolerance. Welding snaps positions to a grid of that size, so two vertices that straddle a grid line can stay unwelded; keep the tolerance well below the mesh's smallest edge. Triangles two of whose corners weld together are left out: they enclose nothing, and older three.js cones have a ring of them at the tip, which would otherwise share each edge there with two more triangles.
fitCollider	A collider of the given shape fitted around a geometry, in the geometry's frame: its bounding box, its bounding sphere, its convex hull, or a cylinder, cone or capsule standing along its y axis, as three.js's own cylinder, cone and capsule geometries do, as wide as the wider of x and z. What world.addBody(object, { collider: 'box' }) and the rest fit; options sets the rest of the collider, its friction say, all but where it sits, which the fit decides.
forEachTriangle	Calls visit once per triangle of an indexed or non-indexed geometry. The vectors passed to visit are reused between calls, so copy them if they need to outlive the call.
geometryOfObject	Every mesh under object (itself included) as one non-indexed geometry, in the frame of object's world position and orientation. Scale is baked into the vertices, so the result is in world units and can be given to a body, which has no scale. Undefined when there are no meshes.