Love2D APIPhysicsOn this pagePhysics Description: Can simulate 2D rigid body physics in a realistic manner. This module is based on Box2D, and this API corresponds to the Box2D API as closely as possible. setMeter Type: Function. Description: Sets the pixels to meter scale factor. All coordinates in the physics module are divided by this number and converted to meters, and it creates a convenient way to draw the objects directly to the screen without the need for graphics transformations. It is recommended to create shapes no larger than 10 times the scale. This is important because Box2D is tuned to work well with shape sizes from 0.1 to 10 meters. The default meter scale is 30. Signature: setMeter: function(scale: number) Parameters: ParameterTypeDescriptionscalenumberThe scale factor as an integer. getMeter Type: Function. Description: Returns the meter scale factor. All coordinates in the physics module are divided by this number, creating a convenient way to draw the objects directly to the screen without the need for graphics transformations. It is recommended to create shapes no larger than 10 times the scale. This is important because Box2D is tuned to work well with shape sizes from 0.1 to 10 meters. Signature: getMeter: function(): number Returns: Return TypeDescriptionnumberThe scale factor as an integer. newWorld Type: Function. Description: Creates a new World. Signature: newWorld: function(x_gravity?: number, y_gravity?: number, sleep?: boolean): World Parameters: ParameterTypeDescriptionx_gravitynumberThe x component of gravity. (Default: 0.)y_gravitynumberThe y component of gravity. (Default: 0.)sleepbooleanWhether the bodies in this world are allowed to sleep. (Default: true.) Returns: Return TypeDescriptionWorldA brave new World. newBody Type: Function. Description: Creates a new body. There are three types of bodies. Static bodies do not move, have a infinite mass, and can be used for level boundaries. Dynamic bodies are the main actors in the simulation, they collide with everything. Kinematic bodies do not react to forces and only collide with dynamic bodies. The mass of the body gets calculated when a Fixture is attached or removed, but can be changed at any time with Body:setMass or Body:resetMassData. Signature: newBody: function(world: World, x?: number, y?: number, body_type?: string): Body Parameters: ParameterTypeDescriptionworldWorldThe world to create the body in.xnumberThe x position of the body. (Default: 0.)ynumberThe y position of the body. (Default: 0.)body_typestringThe type of the body. (Default: 'static'.) Returns: Return TypeDescriptionBodyA new body. newFixture Type: Function. Description: Creates and attaches a Fixture to a body. Note that the Shape object is copied rather than kept as a reference when the Fixture is created. To get the Shape object that the Fixture owns, use Fixture:getShape. Signature: newFixture: function(body: Body, shape: Shape, density?: number): Fixture Parameters: ParameterTypeDescriptionbodyBodyThe body which gets the fixture attached.shapeShapeThe shape to be copied to the fixture.densitynumberThe density of the fixture. (Default: 1.) Returns: Return TypeDescriptionFixtureThe new fixture. newCircleShape Type: Function. Description: Creates a new CircleShape. Signature: newCircleShape: function(radius: number): CircleShape Parameters: ParameterTypeDescriptionradiusnumberThe radius of the circle. Returns: Return TypeDescriptionCircleShapeshape — The new shape. newCircleShape Type: Function. Description: Creates a new CircleShape. Signature: newCircleShape: function(x: number, y: number, radius: number): CircleShape Parameters: ParameterTypeDescriptionxnumberThe x position of the circle.ynumberThe y position of the circle.radiusnumberThe radius of the circle. Returns: Return TypeDescriptionCircleShapeshape — The new shape. newRectangleShape Type: Function. Description: Shorthand for creating rectangular PolygonShapes. -- By default, the local origin is located at the '''center''' of the rectangle as opposed to the top left for graphics. Signature: newRectangleShape: function(width: number, height: number): PolygonShape Parameters: ParameterTypeDescriptionwidthnumberThe width of the rectangle.heightnumberThe height of the rectangle. Returns: Return TypeDescriptionPolygonShapeshape — A new PolygonShape. newRectangleShape Type: Function. Description: Shorthand for creating rectangular PolygonShapes. -- By default, the local origin is located at the '''center''' of the rectangle as opposed to the top left for graphics. Signature: newRectangleShape: function(x: number, y: number, width: number, height: number, angle?: number): PolygonShape Parameters: ParameterTypeDescriptionxnumberThe offset along the x-axis.ynumberThe offset along the y-axis.widthnumberThe width of the rectangle.heightnumberThe height of the rectangle.anglenumberThe initial angle of the rectangle. (Default: 0.) Returns: Return TypeDescriptionPolygonShapeshape — A new PolygonShape. newPolygonShape Type: Function. Description: Creates a new PolygonShape. -- This shape can have 8 vertices at most, and must form a convex shape. Signature: newPolygonShape: function(points: {number}): PolygonShape Parameters: ParameterTypeDescriptionpoints{number}A list of vertices to construct the polygon, in the form of {x1, y1, x2, y2, x3, y3, ...}. Returns: Return TypeDescriptionPolygonShapeshape — A new PolygonShape. newPolygonShape Type: Function. Description: Creates a new PolygonShape. -- This shape can have 8 vertices at most, and must form a convex shape. Signature: newPolygonShape: function(points: number...): PolygonShape Parameters: ParameterTypeDescriptionpointsnumber...A list of vertices to construct the polygon, in the form of {x1, y1, x2, y2, x3, y3, ...}. Returns: Return TypeDescriptionPolygonShapeshape — A new PolygonShape. newEdgeShape Type: Function. Description: Creates a new EdgeShape. Signature: newEdgeShape: function(x1: number, y1: number, x2: number, y2: number): Shape Parameters: ParameterTypeDescriptionx1numberThe x position of the first point.y1numberThe y position of the first point.x2numberThe x position of the second point.y2numberThe y position of the second point. Returns: Return TypeDescriptionShapeThe new shape. newChainShape Type: Function. Description: Creates a new ChainShape. Signature: newChainShape: function(loop: boolean, points: {number}): ChainShape Parameters: ParameterTypeDescriptionloopbooleanIf the chain should loop back to the first point.points{number}A list of points to construct the ChainShape, in the form of {x1, y1, x2, y2, ...}. Returns: Return TypeDescriptionChainShapeshape — The new shape. newChainShape Type: Function. Description: Creates a new ChainShape. Signature: newChainShape: function(loop: boolean, points: number...): ChainShape Parameters: ParameterTypeDescriptionloopbooleanIf the chain should loop back to the first point.pointsnumber...A list of points to construct the ChainShape, in the form of {x1, y1, x2, y2, ...}. Returns: Return TypeDescriptionChainShapeshape — The new shape. newDistanceJoint Type: Function. Description: Creates a DistanceJoint between two bodies. This joint constrains the distance between two points on two bodies to be constant. These two points are specified in world coordinates and the two bodies are assumed to be in place when this joint is created. The first anchor point is connected to the first body and the second to the second body, and the points define the length of the distance joint. Signature: newDistanceJoint: function(body1: Body, body2: Body, x1: number, y1: number, x2: number, y2: number, collide_connected?: boolean): Joint Parameters: ParameterTypeDescriptionbody1BodyThe first body to attach to the joint.body2BodyThe second body to attach to the joint.x1numberThe x position of the first anchor point (world space).y1numberThe y position of the first anchor point (world space).x2numberThe x position of the second anchor point (world space).y2numberThe y position of the second anchor point (world space).collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionJointThe new distance joint. newRevoluteJoint Type: Function. Description: Creates a pivot joint between two bodies. -- This joint connects two bodies to a point around which they can pivot. Signature: newRevoluteJoint: function(body1: Body, body2: Body, x: number, y: number, collide_connected?: boolean): RevoluteJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body.body2BodyThe second body.xnumberThe x position of the connecting point.ynumberThe y position of the connecting point.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionRevoluteJointjoint — The new revolute joint. newRevoluteJoint Type: Function. Description: Creates a pivot joint between two bodies. -- This joint connects two bodies to a point around which they can pivot. Signature: newRevoluteJoint: function(body1: Body, body2: Body, x1: number, y1: number, x2: number, y2: number, collide_connected?: boolean, reference_angle?: number): RevoluteJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body.body2BodyThe second body.x1numberThe x position of the first connecting point.y1numberThe y position of the first connecting point.x2numberThe x position of the second connecting point.y2numberThe y position of the second connecting point.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.)reference_anglenumberThe reference angle between body1 and body2, in radians. (Default: 0.) Returns: Return TypeDescriptionRevoluteJointjoint — The new revolute joint. newPrismaticJoint Type: Function. Description: Creates a PrismaticJoint between two bodies. -- A prismatic joint constrains two bodies to move relatively to each other on a specified axis. It does not allow for relative rotation. Its definition and operation are similar to a revolute joint, but with translation and force substituted for angle and torque. Signature: newPrismaticJoint: function(body1: Body, body2: Body, x: number, y: number, axis_x: number, axis_y: number, collide_connected?: boolean): PrismaticJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body to connect with a prismatic joint.body2BodyThe second body to connect with a prismatic joint.xnumberThe x coordinate of the anchor point.ynumberThe y coordinate of the anchor point.axis_xnumberThe x coordinate of the axis vector.axis_ynumberThe y coordinate of the axis vector.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionPrismaticJointjoint — The new prismatic joint. newPrismaticJoint Type: Function. Description: Creates a PrismaticJoint between two bodies. -- A prismatic joint constrains two bodies to move relatively to each other on a specified axis. It does not allow for relative rotation. Its definition and operation are similar to a revolute joint, but with translation and force substituted for angle and torque. Signature: newPrismaticJoint: function(body1: Body, body2: Body, x1: number, y1: number, x2: number, y2: number, axis_x: number, axis_y: number, collide_connected?: boolean, reference_angle?: number): PrismaticJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body to connect with a prismatic joint.body2BodyThe second body to connect with a prismatic joint.x1numberThe x coordinate of the first anchor point.y1numberThe y coordinate of the first anchor point.x2numberThe x coordinate of the second anchor point.y2numberThe y coordinate of the second anchor point.axis_xnumberThe x coordinate of the axis unit vector.axis_ynumberThe y coordinate of the axis unit vector.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.)reference_anglenumberThe reference angle between body1 and body2, in radians. (Default: 0.) Returns: Return TypeDescriptionPrismaticJointjoint — The new prismatic joint. newWeldJoint Type: Function. Description: Creates a constraint joint between two bodies. A WeldJoint essentially glues two bodies together. The constraint is a bit soft, however, due to Box2D's iterative solver. Signature: newWeldJoint: function(body1: Body, body2: Body, x: number, y: number, collide_connected?: boolean): WeldJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body to attach to the joint.body2BodyThe second body to attach to the joint.xnumberThe x position of the anchor point (world space).ynumberThe y position of the anchor point (world space).collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionWeldJointjoint — The new WeldJoint. newWeldJoint Type: Function. Description: Creates a constraint joint between two bodies. A WeldJoint essentially glues two bodies together. The constraint is a bit soft, however, due to Box2D's iterative solver. Signature: newWeldJoint: function(body1: Body, body2: Body, x1: number, y1: number, x2: number, y2: number, collide_connected?: boolean, reference_angle?: number): WeldJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body to attach to the joint.body2BodyThe second body to attach to the joint.x1numberThe x position of the first anchor point (world space).y1numberThe y position of the first anchor point (world space).x2numberThe x position of the second anchor point (world space).y2numberThe y position of the second anchor point (world space).collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.)reference_anglenumberThe reference angle between body1 and body2, in radians. (Default: 0.) Returns: Return TypeDescriptionWeldJointjoint — The new WeldJoint. newFrictionJoint Type: Function. Description: Create a friction joint between two bodies. A FrictionJoint applies friction to a body. Signature: newFrictionJoint: function(body1: Body, body2: Body, x: number, y: number, collide_connected?: boolean): FrictionJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body to attach to the joint.body2BodyThe second body to attach to the joint.xnumberThe x position of the anchor point.ynumberThe y position of the anchor point.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionFrictionJointjoint — The new FrictionJoint. newFrictionJoint Type: Function. Description: Create a friction joint between two bodies. A FrictionJoint applies friction to a body. Signature: newFrictionJoint: function(body1: Body, body2: Body, x1: number, y1: number, x2: number, y2: number, collide_connected?: boolean): FrictionJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body to attach to the joint.body2BodyThe second body to attach to the joint.x1numberThe x position of the first anchor point.y1numberThe y position of the first anchor point.x2numberThe x position of the second anchor point.y2numberThe y position of the second anchor point.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionFrictionJointjoint — The new FrictionJoint. newRopeJoint Type: Function. Description: Creates a joint between two bodies. Its only function is enforcing a max distance between these bodies. Signature: newRopeJoint: function(body1: Body, body2: Body, x1: number, y1: number, x2: number, y2: number, max_length: number, collide_connected?: boolean): Joint Parameters: ParameterTypeDescriptionbody1BodyThe first body to attach to the joint.body2BodyThe second body to attach to the joint.x1numberThe x position of the first anchor point.y1numberThe y position of the first anchor point.x2numberThe x position of the second anchor point.y2numberThe y position of the second anchor point.max_lengthnumberThe maximum distance for the bodies.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionJointThe new RopeJoint. newPulleyJoint Type: Function. Description: Creates a PulleyJoint to join two bodies to each other and the ground. The pulley joint simulates a pulley with an optional block and tackle. If the ratio parameter has a value different from one, then the simulated rope extends faster on one side than the other. In a pulley joint the total length of the simulated rope is the constant length1 + ratio * length2, which is set when the pulley joint is created. Pulley joints can behave unpredictably if one side is fully extended. It is recommended that the method setMaxLengths be used to constrain the maximum lengths each side can attain. Signature: newPulleyJoint: function(body1: Body, body2: Body, ground_x1: number, ground_y1: number, ground_x2: number, ground_y2: number, x1: number, y1: number, x2: number, y2: number, ratio?: number, collide_connected?: boolean): Joint Parameters: ParameterTypeDescriptionbody1BodyThe first body to connect with a pulley joint.body2BodyThe second body to connect with a pulley joint.ground_x1numberThe x coordinate of the first body's ground anchor.ground_y1numberThe y coordinate of the first body's ground anchor.ground_x2numberThe x coordinate of the second body's ground anchor.ground_y2numberThe y coordinate of the second body's ground anchor.x1numberThe x coordinate of the pulley joint anchor in the first body.y1numberThe y coordinate of the pulley joint anchor in the first body.x2numberThe x coordinate of the pulley joint anchor in the second body.y2numberThe y coordinate of the pulley joint anchor in the second body.rationumberThe joint ratio. (Default: 1.)collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: true.) Returns: Return TypeDescriptionJointThe new pulley joint. newWheelJoint Type: Function. Description: Creates a wheel joint. Signature: newWheelJoint: function(body1: Body, body2: Body, x: number, y: number, axis_x: number, axis_y: number, collide_connected?: boolean): WheelJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body.body2BodyThe second body.xnumberThe x position of the anchor point.ynumberThe y position of the anchor point.axis_xnumberThe x position of the axis unit vector.axis_ynumberThe y position of the axis unit vector.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionWheelJointjoint — The new WheelJoint. newWheelJoint Type: Function. Description: Creates a wheel joint. Signature: newWheelJoint: function(body1: Body, body2: Body, x1: number, y1: number, x2: number, y2: number, axis_x: number, axis_y: number, collide_connected?: boolean): WheelJoint Parameters: ParameterTypeDescriptionbody1BodyThe first body.body2BodyThe second body.x1numberThe x position of the first anchor point.y1numberThe y position of the first anchor point.x2numberThe x position of the second anchor point.y2numberThe y position of the second anchor point.axis_xnumberThe x position of the axis unit vector.axis_ynumberThe y position of the axis unit vector.collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionWheelJointjoint — The new WheelJoint. newMouseJoint Type: Function. Description: Create a joint between a body and the mouse. This joint actually connects the body to a fixed point in the world. To make it follow the mouse, the fixed point must be updated every timestep (example below). The advantage of using a MouseJoint instead of just changing a body position directly is that collisions and reactions to other joints are handled by the physics engine. Signature: newMouseJoint: function(body: Body, x: number, y: number): Joint Parameters: ParameterTypeDescriptionbodyBodyThe body to attach to the mouse.xnumberThe x position of the connecting point.ynumberThe y position of the connecting point. Returns: Return TypeDescriptionJointThe new mouse joint. newMotorJoint Type: Function. Description: Creates a joint between two bodies which controls the relative motion between them. Position and rotation offsets can be specified once the MotorJoint has been created, as well as the maximum motor force and torque that will be be applied to reach the target offsets. Signature: newMotorJoint: function(body1: Body, body2: Body, correction_factor?: number, collide_connected?: boolean): Joint Parameters: ParameterTypeDescriptionbody1BodyThe first body to attach to the joint.body2BodyThe second body to attach to the joint.correction_factornumberThe joint's initial position correction factor, in the range of 1. (Default: 0.3.)collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionJointThe new MotorJoint. newGearJoint Type: Function. Description: Create a GearJoint connecting two Joints. The gear joint connects two joints that must be either prismatic or revolute joints. Using this joint requires that the joints it uses connect their respective bodies to the ground and have the ground as the first body. When destroying the bodies and joints you must make sure you destroy the gear joint before the other joints. The gear joint has a ratio the determines how the angular or distance values of the connected joints relate to each other. The formula coordinate1 + ratio * coordinate2 always has a constant value that is set when the gear joint is created. Signature: newGearJoint: function(joint1: Joint, joint2: Joint, ratio?: number, collide_connected?: boolean): Joint Parameters: ParameterTypeDescriptionjoint1JointThe first joint to connect with a gear joint.joint2JointThe second joint to connect with a gear joint.rationumberThe gear ratio. (Default: 1.)collide_connectedbooleanSpecifies whether the two bodies should collide with each other. (Default: false.) Returns: Return TypeDescriptionJointThe new gear joint.