Dynamics.applyGravity()

Simulates gravity on an element along a configurable axis, accelerating it toward a boundary and bouncing it on impact. Accepts a target element and an options object, and returns an engine instance with a kill() method to stop the simulation.

---

1. Basic Bounds Drop

Providing a bounds container automatically calculates the exact pixel coordinates for the floor and ceiling constraints, ensuring accurate collision boundaries.

Drop element to observe boundary restitution.

60 FPS

import { applyGravity } from 'animx/plugins/Dynamics';

applyGravity('.box', {
  gravity: 1500,
  bounce: 0.6,
  bounds: '#stage' // Auto-computes floor and ceiling
})

---

2. Numeric Floor & Ceiling

You can manually define absolute numeric boundaries via the floor and ceiling properties. These represent pixel offsets along the active axis, relative to the element's initial (untransformed) position.

In this demonstration, initialVelocityY shoots the box upward into the ceiling before gravity decelerates it back toward the floor.

Execute trajectory to observe manual floor and ceiling constraints.

60 FPS

applyGravity('.box', {
  gravity: 980,
  bounce: 0.8,
  floor: 200,            // Far boundary (bottom when direction: 'y')
  ceiling: 0,            // Near boundary (top when direction: 'y')
  initialVelocityY: -800 // Fire upward first (negative = up)
});

---

3. Interactive Grab and Drop

Gravitational physics integrate directly with the Interactable module. You can terminate the simulation (kill()) during pointer manipulation, and re-initialize it upon pointer release for seamless drag-and-drop physics.

Interact with the element to observe simulation termination and re-initialization.

60 FPS

let gravEngine = null;

Interactable.create('.box', {
  bounds: '#stage',
  edgeResistance: 1,   // Hard clamp: element cannot leave the bounds
  onPress() {
    if (gravEngine) gravEngine.kill(); // Stop falling while held
  },
  onRelease() {
    gravEngine = applyGravity('.box', {
      gravity: 2000,
      bounce: 0.4,
      bounds: '#stage'
    });
  }
});

---

4. Direction Toggle

The direction option controls the axis gravity acts on. Switching it to 'x' makes the element fall horizontally instead of vertically, with all the same bounce and bounds behaviour.

Select an axis to apply gravity along.

↓ pulling down

60 FPS

let engine = null;

function launch(direction) {
  if (engine) engine.kill();
  apply('.box', { x: 0, y: 0 });
  engine = applyGravity('.box', {
    direction, // 'y' or 'x'
    gravity: 980,
    bounce: 0.7,
    bounds: '#stage'
  });
}

document.querySelector('#btn-vertical').onclick   = () => launch('y');
document.querySelector('#btn-horizontal').onclick = () => launch('x');

---

Properties & Methods

Configuration Options

Option	Type	Default	Description
gravity	number	980	Acceleration along the active axis (px/s²). Negative values reverse the pull direction.
direction	'y' | 'x'	'y'	The axis gravity acts on. 'y' pulls downward, 'x' pulls rightward.
bounce	number	0.6	Coefficient of restitution on impact (0.0 - 1.0).
bounds	string | Element | Object	null	A container element or custom coordinate object (e.g. {minX, maxX, minY, maxY}). AnimX computes the floor and ceiling from it.
floor	number	innerHeight - 50	The far boundary in the active axis (right edge when direction: 'x'), in transform-space pixels.
ceiling	number	undefined	The near boundary in the active axis (left edge when direction: 'x'), in transform-space pixels.
initialVelocityY	number	0	Initial velocity when direction: 'y' (px/s). Negative shoots upward.
initialVelocityX	number	0	Initial velocity when direction: 'x' (px/s). Negative shoots leftward.
onBounce	Function	null	Called when the element hits the floor or ceiling. Receives (side, impactVelocity).

Engine Methods

Calling applyGravity returns an instance with the following methods:

Method	Description
kill()	Terminates the physics simulation loop.
state	Exposes internal physics state object containing y (current offset) and vy (current vertical velocity) variables.