Dynamics.applyGravity()

Applies continuous uniaxial (vertical) gravitational acceleration to elements, complete with floor and ceiling bounce physics. The engine uses frame-by-frame velocity interpolation rather than pre-computed tweens to ensure highly dynamic and reactive movement.

---

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 { Dynamics } from 'animx/dynamics'

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 values represent absolute Y-axis pixel offsets relative to the element's initial origin coordinate.

In this demonstration, we apply an initialVelocityY vector to shoot the box upwards into the ceiling before gravitational deceleration resolves it against the floor constraint.

Execute trajectory to observe manual floor and ceiling constraints.

60 FPS

Dynamics.applyGravity('.box', {
  gravity: 980,
  bounce: 0.8,
  floor: 200,            // Y position of the floor
  ceiling: 0,            // Y position of the ceiling
  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',
  onPress() {
    if (gravEngine) gravEngine.kill(); // Stop falling while held
  },
  onRelease() {
    gravEngine = Dynamics.applyGravity('.box', {
      gravity: 2000,
      bounce: 0.4,
      bounds: '#stage'
    });
  }
});

---

Properties & Methods

Configuration Options

Option	Type	Default	Description
gravity	number	980	Constant vertical acceleration vector (px/s²). Negative values invert gravity upwards.
bounce	number	0.6	Coefficient of restitution upon hitting the floor or ceiling (0.0 - 1.0).
bounds	string | Element | { minX?: number, maxX?: number, minY?: number, maxY?: number }	null	A container element or explicit bounds. AnimX will compute floor and ceiling constraints.
floor	number	innerHeight - 50	The absolute Y pixel boundary for the floor, relative to the element's initial (untransformed) coordinate origin.
ceiling	number	undefined	The absolute Y pixel boundary for the ceiling, relative to the element's initial origin.
initialVelocityY	number	0	Instantaneous vertical velocity applied when the simulation starts (px/s).
onBounce	Function	null	Callback triggered when the element impacts the floor or ceiling. Provides (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.