Physics2D

Club GSAP plugin

Quick Start

Trial URL

Physics2DPlugin is a Club GSAP perk, join today or grab this trial URL to take it for a spin for free.  Works on localhost, Codepen, CodeSandbox and Stackblitz.

``gsap.registerPlugin(Physics2DPlugin) ``

Minimal usage

``gsap.to(element, {  duration: 2,  physics2D: { velocity: 300, angle: -60, gravity: 400 },});``

Description​

Provides simple physics functionality for tweening an Object's `x` and `y` coordinates (or `left` and `top`) based on a combination of `velocity`, `angle`, `gravity`, `acceleration`, `accelerationAngle`, and/or `friction`. It is not intended to replace a full-blown physics engine and does not offer collision detection, but serves as a way to easily create interesting physics-based effects with the GreenSock Animation Platform.

Config Object​

Description

• velocity

Number - The initial velocity of the object measured in pixels per time unit. Default: `0`.
• angle

Number - The initial angle (in degrees) at which the object should travel. This only matters when a `velocity` is defined. For example, if the object should start out traveling at -60 degrees (towards the upper right), the `angle` would be `-60`. Default: `0`.
• gravity

Number - The amount of downward acceleration applied to the object, measured in pixels per second. You can either use `gravity` or `acceleration`, not both because `gravity` is the same thing as `acceleration` applied at an `accelerationAngle` of `90`. Think of gravity as a convenience property that automatically sets the `accelerationAngle` for you. Default: `null`.
• acceleration

Number - The amount of acceleration applied to the object, measured in pixels per second, it would be measured per frame). To apply the acceleration in a specific direction that is different than the angle, use the `accelerationAngle` property. You can either use `gravity` or `acceleration`, not both because `gravity` is the same thing as `acceleration` applied at an `accelerationAngle` of `90`. Default: `null`.
• accelerationAngle

Number - The angle at which acceleration is applied (if any), measured in degrees. So if, for example, you want the object to accelerate towards the left side of the screen, you’d use an `accelerationAngle` of `180`. If you define a `gravity` value, it will automatically set the `accelerationAngle` to `90` (downward). Default: `null`.
• friction

Number - A value between 0 and 1 where 0 is no friction, 0.08 is a small amount of friction, and 1 will completely prevent any movement. This is not meant to be precise or scientific in any way, but it serves as an easy way to apply a friction-like physics effect to your tween. Generally it is best to experiment with this number a bit - start with very small values like 0.02. Also note that friction requires more processing than physics tweens without any friction. Default: `0`.
• xProp

String - By default, the `x` property of the target object is used to control x-axis movement, but if you’d prefer to use a different property name, use `xProp` like `xProp: "left"`. Default: `"x"`.
• yProp

String - By default, the `y` property of the target object is used to control y-axis movement, but if you’d prefer to use a different property name, use `yProp` like `yProp: "top"`. Default: `"y"`.
info

Parameters are not intended to be dynamically updateable, but one unique convenience is that everything is reverseable. So if you spawn a bunch of particle tweens, for example, and throw them into a timeline, you could simply call `reverse()` on the timeline to watch the particles retrace their steps right back to the beginning. Keep in mind that any easing equation you define for your tween will be completely ignored for these properties.

Usage​

``gsap.to(element, {  duration: 2,  physics2D: { velocity: 300, angle: -60, gravity: 400 },});//orgsap.to(element, {  duration: 2,  physics2D: { velocity: 300, angle: -60, friction: 0.1 },});//orgsap.to(element, {  duration: 2,  physics2D: {    velocity: 300,    angle: -60,    acceleration: 50,    accelerationAngle: 180,  },});``

Physics2DPlugin is a Club GSAP membership benefit. You must have a valid membership to use this class without violating the terms of use. Visit the club page to sign up or get more details.

FAQs​

How do I include Physics2DPlugin in my project?

See the installation page for all the options (CDN, NPM, download, etc.) where there's even an interactive helper that provides the necessary code. Easy peasy. Don't forget to register Physics2DPlugin like this in your project:

``gsap.registerPlugin(Physics2DPlugin)``

Is this included in the GSAP core?

No, you must load/import it separately

Is this only for Club GSAP members?

Yes. It's our way of saying "Thank you" to those who support our efforts. If you're not a member, what are you waiting for? Satisfaction is guaranteed or your money back. Take your animation skills to the next level. If you're already a member, you can download GSAP along with this and the other bonus plugins from your account dashboard. See the installation page for details about how to get it into your project via a `<script>` tag or NPM, Yarn, etc.

You betcha! There's a trial (but fully-functional) version of Physics2DPlugin that you can use on Codepen as much as you want for free. Get the URLs here. It's a fantastic way to experiment. Note: the trial version of the plugins will only work on the CodePen domain.

It works fine during development, but suddenly stops working in the production build! What do I do?

Your build tool is probably dropping the plugin when tree shaking and you forgot to register Physics2DPlugin (which protects it from tree shaking). Just register the plugin like this:

``gsap.registerPlugin(Physics2DPlugin)``

Is it bad to register a plugin multiple times?

No, it's perfectly fine. It doesn't help anything, nor does it hurt.