Gravity.js

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:

Shape Types

Set collision shape with data-gravity-shape:

Physics Properties

Customize physics behavior with these data attributes:

Initial Velocity & Forces

Initial Velocity (Static):

Initial Velocity (Directional):

Directional velocities are combined: (right - left) for horizontal, (down - up) for vertical. All velocity attributes accept CSS variables (e.g., --cursor-x from Cursor.js). Perfect for State.js to spawn projectiles dynamically!

Container Bounds:

Dynamic bodies will bounce off container edges. Perfect for keeping objects in view with cursor/mouse interaction!

Continuous Forces (Static):

Dynamic Forces (CSS Variables):

Perfect for Keys.js integration! Accepts comma-separated CSS variable names (values are summed). Forces are combined: (right - left) for horizontal, (down - up) for vertical.

CSS Variables

Gravity.js exposes physics state as CSS variables:

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

Collision Detection

Collisions are detected automatically and trigger:

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!

Constraints & Joints (v1.2.0)

Connect bodies together with distance constraints using JavaScript:

const constraint = gravity.addConstraint(elementIdA, elementIdB, {
    length: 100,        // Distance to maintain (defaults to current distance)
    stiffness: 0.9,     // How strongly constraint pulls (0-1, default 0.5)
    breakForce: 50      // Tension threshold for breaking (0 = unbreakable, default 0)
});
                    

Constraint Parameters:

Constraint Breaking Event:

element.addEventListener('constraintbreak', (event) => {
    console.log('Constraint broke!', event.detail.constraint);
});
                    

Perfect for ropes, chains, cloth simulation, and destructible structures! See Demo 5 for a tearable cloth example.

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:

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!