Elastica

⚠️ Still in development mode - API might change ⚠️

Introduction

Elastica is a JavaScript library providing a physics engine for simulating elastic collision using Aligned axis bounding boxes (AABBs) and grid hash for efficient collision detection. It has a React wrapper which provides hooks and components for managing the state and interactions of your elements. Apply your own Cinematic equation for position and velocity of particles.

Installation

npm i @darkroom.engineering/elastica

Setup

import Elastica, {
  AxisAlignedBoundaryBox,
  initalConditionsPresets,
  updatePresets,
} from '@darkroom.engineering/elastica/react'

Elastica will wrap your component getting the dimensions for borders calculations and the grid size for collisions.

<Elastica
  config={{
    collisions: true,
    borders: 'rigid',
  }}
  initialCondition={initalConditionsPresets.random}
  update={updatePresets.dvdScreenSaver}
>
  {[{ name: 'DVD' }].map(({ name }, index) => (
    <AxisAlignedBoundaryBox key={index}>{name}</AxisAlignedBoundaryBox>
  ))}
</Elastica>

AxisAlignedBoundaryBox will wray your elements getting their size for collisions and positioning.

API

ReactElastica

Prop	Type	Default	Description
`children`	`ReactNode`	N/A	Represents the child elements or components rendered within the `ReactElastica` component. These elements are part of the elastic collision simulation.
`className`	`string`	N/A	Specifies a CSS class for styling the `ReactElastica` container, allowing custom styling and theming.
`showHashGrid`	`boolean`	`false`	Shows the hash grid for measuing correct grid size.
`config`	`object`	See below	Configuration object controlling various aspects of the physics simulation.
└─ `gridSize`	`number`	`8`	Defines the size of the hash grid, bigger grid reduces number of computation by collisions but should not be smaller than biggest element.
└─ `collisions`	`boolean`	`true`	Enables or disables collision detection between elements.
└─ `borders`	`string`	`'rigid'`	Defines the border behavior. `'rigid'` indicates immovable borders, preventing objects from passing through the container's edges. `'Periodic'` translates elements to opposite border when reaching limit.
└─ `containerOffsets`	`object`	See below	Specifies the offsets from the container's edges for the simulation area, allowing for padding or margins.
└── `top`	`number`	`0`	Top offset.
└── `bottom`	`number`	`0`	Bottom offset.
└── `left`	`number`	`0`	Left offset.
└── `right`	`number`	`0`	Right offset.
`initialCondition`	`function`	`() => {}`	Function to set the initial conditions of the simulation, such as starting positions and velocities of elements. It is called once when the component mounts. Engine instance Class passed as props
`update`	`function`	`() => {}`	Callback function called on each simulation update, where cinematic equations have to be applied to each element. Engine instance Class passed as props.

Aligned Axis Boundary Box

Prop	Type	Default	Description
`className`	`string`	N/A	Specifies a CSS class for styling the boundary box. This allows for custom styling of the container holding the children elements.
`children`	`ReactNode`	N/A	Represents the child elements or components that will be enclosed within the boundary box. These children are subject to the constraints of the boundary box.
`...props`	`object`	N/A	Additional props that can be passed to the component. These props can include any other attributes or handlers needed for the custom behavior of the boundary box.

useElastica

Hook that exposes the Elastica instance and provides a set of functions for managing the simulation.

initalConditionsPresets

Object containing preset functions for setting initial conditions of the simulation.

updatePresets

Object containing preset functions for updating the simulation.

Examples

For more examples check demo github

darkroomengineering/elastica