Gravity.js

Documentation ^v1.0.0

What is Gravity.js?

Gravity.js is a lightweight physics engine that renders using CSS. Configure physics bodies, collisions, and dynamics entirely through data attributes - no JavaScript required for basic physics interactions.

Using the power of CSS rendering and data attributes, Gravity.js enables collision detection, triggers, and realistic physics in your browser games and applications. It integrates seamlessly with State.js for game state management and Keys.js for player input.

Perfect for creating browser-based games, interactive experiences, and physics simulations without the overhead of canvas rendering. Native DOM elements become physics bodies!

Demo 1: Falling Boxes

Dynamic Bodies with Gravity

Boxes fall under gravity and bounce on the ground. Different masses and restitution values create varied behaviors.

Demo 2: Tower of Boxes

Stack Physics & Projectile

A tower of stacked boxes with a projectile ball that knocks them down! High friction keeps boxes stable until impact.

Demo 3: Platforms

Static Platform Bodies

Static platforms don't move. Watch the dynamic box bounce between platforms with realistic physics!

How To Install?

Add the gravity.js file into your project and include it in your HTML head tags:

                        <script src="https://cdn.jsdelivr.net/npm/@idevgames/gravity-js/src/gravity.js"></script>

Or use npm:

                        npm i @idevgames/gravity-js

How To Use?

Add the data attribute "data-gravity" or class "enable-gravity" to your HTML element to make it a physics body:

                        <div data-gravity data-gravity-type="dynamic"></div>

The element will automatically become a physics body and respond to gravity and collisions!

Physics Body Types

Three body types are available via data-gravity-type:

dynamic - Moves and collides (default)

static - Never moves (ground, walls, platforms)

kinematic - Moves but infinite mass (moving platforms)

Shape Types

Set collision shape with data-gravity-shape:

box - Rectangle collision (default, uses element dimensions)

Physics Properties

Customize physics behavior with these data attributes:

data-gravity-mass="1" - Body mass (affects momentum)

data-gravity-restitution="0.3" - Bounciness (0-1)

data-gravity-friction="0.5" - Surface friction (0-1)

data-gravity-density="1" - Material density

data-gravity-fixed-rotation="true" - Prevent rotation

Initial Velocity & Forces

Set initial motion or continuous forces:

data-gravity-velocity-x="10" - Initial horizontal velocity

data-gravity-velocity-y="-5" - Initial vertical velocity

data-gravity-force-x="2" - Continuous horizontal force

data-gravity-force-y="0" - Continuous vertical force

CSS Variables

Gravity.js exposes physics state as CSS variables:

--gravity-x, --gravity-y

--gravity-rotation

--gravity-velocity-x, --gravity-velocity-y

--gravity-speed

--gravity-collision (1 when colliding)

Use these in your CSS for dynamic effects based on physics state!

Collision Detection

Collisions are detected automatically and trigger:

CSS class .gravity-colliding added during collision

CSS class .gravity-collision-[id] for specific collisions

Custom event gravitycollision on collision start

Custom event gravityexit on collision end

Data attribute data-collision-with updated with colliding element ID

Collision Sensors (Triggers)

Create trigger zones with data-gravity-sensor="true":

                        <div data-gravity data-gravity-type="static" data-gravity-sensor="true"></div>

Sensors detect collisions but don't create physical responses. Perfect for trigger zones, checkpoints, and event areas!

Collision Groups

Filter collisions with data-gravity-group:

                        <div data-gravity data-gravity-group="player"></div>
                        <div data-gravity data-gravity-group="enemy"></div>

Bodies only collide with others in the same group or the default group.

World Settings

Configure global physics on the body element:

data-gravity-world-gravity="9.8" - Global gravity strength

data-gravity-world-gravity-x="0" - Horizontal gravity

data-gravity-world-gravity-y="9.8" - Vertical gravity

data-gravity-damping="0.99" - Velocity damping

data-gravity-angular-damping="0.99" - Rotation damping

JavaScript API

Optional JavaScript methods for advanced control:

                        gravity.applyForce(elementId, x, y)
                        gravity.applyImpulse(elementId, x, y)
                        gravity.setVelocity(elementId, x, y)
                        gravity.getBody(elementId)
                        gravity.pauseSimulation()
                        gravity.resumeSimulation()

Integration with State.js

Gravity.js works seamlessly with State.js for game state management:

                        <div id="player" data-gravity data-state data-state-watch="collision-with"></div>
                        <div id="coin" data-gravity data-gravity-sensor="true"></div>

Collision events update data attributes that State.js can watch and react to. Use collision sensors to trigger state changes!

Integration with Keys.js

Combine with Keys.js for player input:

                        document.addEventListener('keydown', (e) => {
                            if (keys.isKeyDown('space')) {
                                gravity.applyImpulse('player', 0, -300);
                            }
                            if (keys.isKeyDown('right')) {
                                gravity.applyForce('player', 50, 0);
                            }
                        });

Create fully interactive games with physics, input, and state management!

BUILD PHYSICS GAMES

WITH PURE CSS RENDERING

Gravity.js + State.js + Keys.js = Complete Browser Game Engine

Check out the companion libraries:

State.js - Game State Management

Keys.js - Keyboard Input

Keep up to date on dev.to