[![License](https://img.shields.io/badge/License-MIT-blue)](#license) [![CodePen Demos](https://img.shields.io/badge/CodePen-Demos-black?logo=codepen)](https://codepen.io/collection/JYOKxx) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40idevgames%2Fgravity-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.

🎮 **[View Live Demos & Examples on CodePen](https://codepen.io/collection/JYOKxx)** 🎮 Perfect for creating browser-based games, interactive experiences, and physics simulations without the overhead of canvas rendering. Native DOM elements become physics bodies! --- ## What is Gravity.js? Gravity.js brings real physics to the browser using: - **CSS Rendering**: No canvas overhead - uses native DOM positioning - **Data Attribute Configuration**: Set up physics bodies with HTML attributes - **Collision Detection**: SAT (Separating Axis Theorem) for OBB (Oriented Bounding Box) - **Zero Dependencies**: Standalone library, works great with State.js and Keys.js - **Lightweight**: Minimal footprint, maximum performance --- ## Features ✅ **Physics Body Types**: Dynamic, Static, and Kinematic bodies ✅ **Shape Support**: Box (OBB with rotation) ✅ **Realistic Physics**: Mass, restitution, friction, forces, impulses, and rotation ✅ **Collision Detection**: SAT-based OBB collision with automatic resolution and events ✅ **Collision Sensors**: Trigger zones without physical response ✅ **Collision Groups**: Filter which bodies can collide ✅ **CSS Variables**: Access physics state in your CSS ✅ **State.js Integration**: Collisions trigger state changes ✅ **Keys.js Integration**: Player input for interactive games ✅ **Sleep System**: Bodies at rest are optimized automatically --- ## Installation ### NPM ```bash npm i @idevgames/gravity-js ``` ### Direct Include ```html ``` ### CDN ```html ``` --- ## Quick Start ### Basic Physics Body ```html
I'm a physics body!
``` ### Create a Ground ```html
Ground
``` ### Complete Example ```html
``` --- ## Physics Body Types Set the body type with `data-gravity-type`: ### Dynamic ```html
``` - Affected by gravity and forces - Collides with all body types - Default body type ### Static ```html
``` - Never moves - Infinite mass - Perfect for ground, walls, platforms ### Kinematic ```html
``` - Moves but has infinite mass - Not affected by forces - Perfect for moving platforms --- ## Shape Types Set collision shape with `data-gravity-shape`: ### Box (OBB) ```html
``` - Default shape - Uses element's width and height - Oriented Bounding Box collision using SAT - Supports rotation at any angle - Automatically detects rotation from CSS `transform: rotate()` ## Physics Properties ### Mass ```html
``` - Affects momentum and force response - Default: `1` ### Restitution (Bounciness) ```html
``` - How much velocity is retained after collision - Range: `0` (no bounce) to `1` (perfect bounce) - Default: `0.3` ### Friction ```html
``` - Surface friction during collisions - Range: `0` (slippery) to `1` (sticky) - Default: `0.5` ### Density ```html
``` - Material density - Default: `1` ### Fixed Rotation ```html
``` - Prevents body from rotating - Useful for characters and upright objects - Default: `false` ### Initial Rotation ```html
``` - Automatically reads CSS `transform: rotate()` for initial rotation - Collision box rotates with the element - Can also use `data-gravity-rotation="45"` (in degrees) ### Container Bounds ```html
Contained!
``` - Add `data-gravity-container` to a parent element - Creates invisible walls, ceiling, and floor - Dynamic bodies bounce off container edges - Perfect for keeping objects in view with cursor/mouse interaction --- ## Initial Velocity & Forces ### Initial Velocity (Static) ```html
``` - Set starting velocity with X/Y values - X: horizontal, Y: vertical - Accepts CSS variables: `data-gravity-velocity-x="--cursor-x"` ### Initial Velocity (Directional) ```html
``` - Set starting velocity with directional values - Right/Left are combined: `right - left` - Up/Down are combined: `down - up` - Also accepts CSS variables: `data-gravity-velocity-right="--cursor-x"` - Perfect for jumps: `data-gravity-velocity-up="300"` ### Continuous Forces (Static) ```html
``` - Applied every physics update - Use for constant propulsion ### Dynamic Forces (CSS Variables) ```html
``` - Read forces from CSS variables (perfect for Keys.js integration) - Accepts comma-separated CSS variable names (values are summed) - Right/Left forces are combined: `(right - left) * multiplier` - Up/Down forces are combined: `(down - up) * multiplier` - Use with Keys.js for declarative player control --- ## CSS Variables Gravity.js exposes physics state as CSS variables for dynamic styling: ```css .my-element { /* Position */ left: var(--gravity-x); top: var(--gravity-y); /* Rotation */ transform: rotate(var(--gravity-rotation)); /* Velocity-based effects */ opacity: calc(var(--gravity-speed) / 100); /* Collision-based effects */ background: calc(var(--gravity-collision) * 255, 0, 0); } ``` ### Available CSS Variables - `--gravity-x` - Horizontal position (px) - `--gravity-y` - Vertical position (px) - `--gravity-rotation` - Rotation angle (deg) - `--gravity-velocity-x` - Horizontal velocity - `--gravity-velocity-y` - Vertical velocity - `--gravity-speed` - Total speed magnitude - `--gravity-collision` - `1` when colliding, `0` otherwise --- ## Collision Detection Collisions are automatically detected and resolved. When a collision occurs: ### CSS Classes Added ```css .gravity-colliding { /* Applied to bodies currently in collision */ } .gravity-collision-playerId { /* Applied when colliding with element id="playerId" */ } ``` ### Custom Events Dispatched ```javascript element.addEventListener('gravitycollision', (e) => { console.log('Collision with:', e.detail.other); console.log('Other ID:', e.detail.otherId); }); element.addEventListener('gravityexit', (e) => { console.log('Stopped colliding with:', e.detail.other); }); ``` ### Data Attributes Updated ```html
``` --- ## Collision Sensors (Triggers) Create trigger zones that detect collisions without physical response: ```html
``` Perfect for: - Checkpoint zones - Collectible items - Trigger areas - Event zones --- ## Collision Groups Filter which bodies can collide: ```html
``` Bodies only collide with: - Other bodies in the same group - Bodies in the `default` group --- ## World Settings Configure global physics on the `` element: ```html ``` ### World Attributes - `data-gravity-world-gravity` - Sets both X and Y gravity - `data-gravity-world-gravity-x` - Horizontal gravity (default: `0`) - `data-gravity-world-gravity-y` - Vertical gravity (default: `9.8`) - `data-gravity-damping` - Velocity damping (default: `0.99`) - `data-gravity-angular-damping` - Rotation damping (default: `0.99`) --- ## JavaScript API While Gravity.js works without JavaScript, you can use these methods for advanced control: ### Apply Force ```javascript gravity.applyForce('playerId', 50, 0); // Apply continuous force ``` ### Apply Impulse ```javascript gravity.applyImpulse('playerId', 0, -300); // One-time force (jump) ``` ### Set Velocity ```javascript gravity.setVelocity('playerId', 10, 0); // Set velocity directly ``` ### Get Body Data ```javascript const body = gravity.getBody('playerId'); console.log(body.x, body.y, body.velocityX, body.velocityY); ``` ### Pause/Resume Simulation ```javascript gravity.pauseSimulation(); gravity.resumeSimulation(); ``` --- ## Integration with State.js Gravity.js works seamlessly with [State.js](https://github.com/iDev-Games/State-JS) for game state management: ```html
Score: 0
``` When player collides with coin: 1. Gravity.js detects collision 2. Updates `data-collision-with` attribute 3. State.js watches attribute change 4. Increments score automatically --- ## Integration with Keys.js Combine with [Keys.js](https://github.com/iDev-Games/Keys-JS) for player input - **NO JavaScript required!** ### Declarative Integration (Recommended) Keys.js sets CSS variables that Gravity.js can read automatically: ```html
``` **How it works:** - Keys.js sets `--key-*` CSS variables (0 when released, 1 when pressed) - Gravity.js reads these via `data-gravity-force-right/left/up/down` attributes - Each attribute accepts comma-separated CSS variable names (e.g., `--key-d, --key-right`) - Multiple variables are summed together automatically - Forces are automatically combined: right - left for X, down - up for Y - `data-gravity-force-multiplier` scales the force strength - No JavaScript required - pure CSS variable integration! ### JavaScript Integration (Advanced) For more control, use the JavaScript API: ```html ``` --- ## Complete Game Example ```html
Score: 0
``` --- ## Browser Support Gravity.js works in all modern browsers: - Chrome/Edge (latest) - Firefox (latest) - Safari (latest) Requires: - ES6 class support - requestAnimationFrame - CSS custom properties (variables) - Map and Set --- ## Performance Gravity.js is optimized for performance: - ✅ Spatial grid for broad-phase collision detection - ✅ Sleep system for bodies at rest - ✅ Efficient attribute caching - ✅ Fixed timestep physics simulation - ✅ requestAnimationFrame for smooth rendering --- ## Companion Libraries ### Complete Browser Game Engine Stack **Gravity.js** (Physics) Physics simulation, collision detection, and dynamics **[State.js](https://github.com/iDev-Games/State-JS)** (State Management) Game state, variables, and reactive data binding **[Keys.js](https://github.com/iDev-Games/Keys-JS)** (Input) Keyboard input handling and key state tracking Together they form a complete, zero-dependency game engine for the browser! --- ## Data Attribute Reference ### Body Configuration | Attribute | Type | Default | Description | |-----------|------|---------|-------------| | `data-gravity` | - | - | Enables physics on element | | `data-gravity-type` | `dynamic\|static\|kinematic` | `dynamic` | Body type | | `data-gravity-shape` | `box` | `box` | Collision shape | | `data-gravity-mass` | number | `1` | Body mass | | `data-gravity-restitution` | 0-1 | `0.3` | Bounciness | | `data-gravity-friction` | 0-1 | `0.5` | Surface friction | | `data-gravity-density` | number | `1` | Material density | | `data-gravity-fixed-rotation` | boolean | `false` | Prevent rotation | | `data-gravity-sensor` | boolean | `false` | Trigger-only collider | | `data-gravity-group` | string | `default` | Collision group | ### Initial Motion | Attribute | Type | Default | Description | |-----------|------|---------|-------------| | `data-gravity-velocity-x` | number | `0` | Initial horizontal velocity | | `data-gravity-velocity-y` | number | `0` | Initial vertical velocity | | `data-gravity-force-x` | number | `0` | Continuous horizontal force | | `data-gravity-force-y` | number | `0` | Continuous vertical force | ### Directional Motion | Attribute | Type | Default | Description | |-----------|------|---------|-------------| | `data-gravity-velocity-right` | number | `0` | Initial rightward velocity | | `data-gravity-velocity-left` | number | `0` | Initial leftward velocity | | `data-gravity-velocity-up` | number | `0` | Initial upward velocity (perfect for jumps!) | | `data-gravity-velocity-down` | number | `0` | Initial downward velocity | | `data-gravity-force-right` | string | - | CSS variable(s) for rightward force (e.g., `--key-d, --key-right`) | | `data-gravity-force-left` | string | - | CSS variable(s) for leftward force (e.g., `--key-a, --key-left`) | | `data-gravity-force-up` | string | - | CSS variable(s) for upward force (e.g., `--key-w, --key-up`) | | `data-gravity-force-down` | string | - | CSS variable(s) for downward force (e.g., `--key-s, --key-down`) | | `data-gravity-force-multiplier` | number | `100` | Multiplier for directional force values | ### World Settings (on ``) | Attribute | Type | Default | Description | |-----------|------|---------|-------------| | `data-gravity-world-gravity` | number | `9.8` | Global gravity (X and Y) | | `data-gravity-world-gravity-x` | number | `0` | Horizontal gravity | | `data-gravity-world-gravity-y` | number | `9.8` | Vertical gravity | | `data-gravity-damping` | 0-1 | `0.99` | Velocity damping | | `data-gravity-angular-damping` | 0-1 | `0.99` | Rotation damping | --- ## License MIT License - feel free to use in personal and commercial projects! --- ## Author Created by **iDev Games** Follow for updates: - [GitHub](https://github.com/iDev-Games) - [Dev.to](https://dev.to/idevgames) --- ## Contributing Contributions welcome! Please open issues and pull requests on GitHub. --- **Gravity.js** - Turn the browser into a physics-powered game engine! 🎮⚡