@lampix/physics v0.4.1
Lampix Physics Layout
The @lampix/physics library is built upon and uses Matter.JS. With it you can create a “physical” environment / simulation that helps you replicate real life object interactions like deformation, rolling, attraction, gravity, etc.
Table of Contents
Usage / Installation
npm install @lampix/physics.
import lampixPhysics from '@lampix/physics'.
Create the setupOptions object
setupOptions = {
width: yourScreenWidth,
height: yourScreenHeight,
noWalls: disableWallsOutsideTheScreen,
noRenderer: disableMatterJSRenderer
}
Instantiate the library (preferably when your app is still loading) by creating an object
MatterSetup = lampixPhysics
and then creating a local object with
new MatterSetup(setupOptions)
Project Source Structure
@types
Used to import the matter-attractors types. No modifications needed here.
objects
Houses different Object types like Circular, Polygon, Contraint, etc. You can add here future object types.
utils
Here you can find the different functions needed to build objects, add attractors, check for screen space, remove objects, move them around, scale them, etc. More of these functionalities should be added here.
index.js
The standard index file needed to load the library.
matter_types.js
A repository for the object types needed to create different physical bodies, add attraction properties, render options, etc.
Objects
GlobalObject
This is the smallest building block for any and all Matter Objects. It can become either a body, a constraint or a composite.
MatterBody
Archetype for all sorts of physical bodies which extends the GlobalObject.
MatterObjects
Is a global singleton that is needed when the library creates new objects.
ObjectCircular
This is a circular body that extends the MatterBody class. You can build such an object by creating a CircularBodyOptions object and passing it to the appropiate utils function.
ObjectComposite
A composite body which consists of more bodies. Still in the works.
ObjectConstraint
This is a Constraint which can be placed between two bodies. Check out the ConstraintOptions to find out what options you have to making one.
ObjectPolygon
A physical body with more than 4 sides.
ObjectRectangle
A physical body with just 4 sides.
Utils
addAttracted
This adds a new attracted body to a specific attractor.
addAttractor
Adds a new Attractor body to the world.
addAttractorOrbit
This adds Orbit functionality to the Attractor so that attracted bodies don't stick to their attractor. Check out the object for more information.
applyForceToBody
This can be used to “hit” a physical body with a given force.
attractAllToOne
Is used to attract everybody else to the body that has this applied to it.
attractSomeToOne
A very complex function that helps you decide which bodies attract which other ones. You can basically have 2 or more different physical bodies that exert attraction forces on whichever other bodies you so desire.
checkIfSpaceOccupied
Can be used to determine whether or not a position on the screen is already occupied by some other body.
checkOnScreen
You can check whether or not a body is currently within the screen bounds or not. This can be helpful if you disable the screen Walls.
clearMatter
Call to clear the whole Matter world. If you use this you will have to re-create the Matter world with the MatterSetup method.
createCircular
Used to make a circular object.
createComposite
Can be used to create a composite of 2 or more objects. Still in the works.
createConstraint
Used to make a line constraint between 2 objects. The line is slightly elastic but will try to keep the 2 objects within the same distance of each other.
createPolygon
Used to make a 5+ sided object.
createRectangle
Used for making 4 sided objects.
deleteBody
This function is called when you want to remove a body from the world.
deleteComposite
This is called to remove a composite from the world.
deleteConstraint
Removes a constraint from the world.
getAngleBetweenTwoPoints
Returns the angle between two given points.
MatterSetup
This is a complex class that needs to be called in order for a valid instance of @lampix/physics to be created. You need to feed it a valid MatterSetupObject in order to build one. Please refer to the class comments for more information.
randomAlphaMinMaxDeg
This function gives you a random degree between the min and max given values.
removeAttracted
Removes a given attracted body from the local attractor to attracted list. The result of calling this function is that the given attracted body will no longer be subjected to vectorial forces towards the attractor body.
removeAttractor
Removes a given attractor body from the local ATAM list. The result is that this body will no longer be an attractor to others.
rotateBody
Function for rotating an existing body.
scaleBody
Scales a body in size instantly.
scaleBodyOverTime
Sets a body to be scaled over a delta T time.
setPositionOfBody
Used to move instantly an existing body.
setStaticToBody
Function for making an existing object static or not. (static objects are NOT affected by any physical forces)
suggestPositionWithinScreenBounds
This calculates a valid position within the screen bounds for a desired recommendation object. Refer to the code for more information. This function will soon be refactored.
translateBody
Function for moving an existing object. Might get deleted in the future.
updateMatterEngine
Needed to update the physics engine as fast as you with. You may either call it at your discretion, which makes you responsible for how often the physics will update or you may pass it a timestep variable which will automate the update process.
matter_types
XYPos
Used to describe a 2D point by using an x and y.
ObjectIdentifiers
Necessary when you want to use the suggesstPositionWithinScreenBounds function. The variables needed are the object index, center x and center y and width and height.
Circle
Used to define a circular object. Uses center x, center y and radius.
ATAMObject
Attractor si Attracted object map. Constains at least an attractor and may contain orbitMin and orbitMax for defining orbits as well as the list of attracted objects.
AttractedObject
This defines the attracted object used in the ATAMObject map. You can define a customOrbit which will supersede the attractor orbit definitions. You can also stop any attraction if you so desire.
MatterSetupObject
Needed for setting up the @lampix/physics instance. It uses a width and height as well as booleans for noWalls and noRenderer.
BasicBodyOptions
Interface that defines the basic attributes that any and all matter bodies need. This includes x and y and the matterOptions which are optional.
MatterBodyOptions
Are the Matter JS options that may be used when you create a body. Check out the online documentation for more information.
MatterColFilterOptions
Used within the MatterBodyOptions if you want to define special collision filter rules.
MatterPluginOptions
Define the attraction function that the target object is subjected to.
MatterRenderOptions
Specific render options which may be used when you define a Matter object.
MatterSpriteOptions
Matter JS can use Sprites so you may want to define this if your object consists of a texture / sprite.
RectangleBodyOptions
This extends the BasicBodyOptions in order to create rectangle shaped bodies. It only uses a width and height.
CircularBodyOptions
Used to make circular objects and extends the BasicBodyOptions. You only need to define the radius of the object.
PolygonBodyOptions
Extends the BasicBodyOptions and is used when making 5+ sided objects. You need to define the radius and the amount of sides the objects has.
ConstraintOptions
This interface is needed when making a constraint. It needs to be given a MatterConstraintOptions object. Additionally you may specify a constraint color, the growOver number which is a delta T for growth animation time and an animSteps number for specifying how many animation steps there are.
MatterConstraintOptions
The required object for defining a Matter JS constraint. Here you have to specify bodyA and bodyB, which should be the two bodies that are being linked together, pointA and pointB which should be the points where the link occurs. You will also need to specify the length and the stiffness of the constraint. Additionally you may give it a render object which should be instanced before hand.
License
(The MIT License)
Copyright (c) 2018 Lampix
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.