Love2D APIBodyOn this pageBody Description: Bodies are objects with velocity and position. type Type: Function. Description: Gets the type of the object as a string. Signature: type: function(self: Body): string Returns: Return TypeDescriptionstringThe type as a string. Of Type: Function. Description: Checks whether an object is of a certain type. If the object has the type with the specified name in its hierarchy, this function will return true. Signature: typeOf: function(self: Body, type_name: string): boolean Parameters: ParameterTypeDescriptiontype_namestringThe name of the type to check for. Returns: Return TypeDescriptionbooleanTrue if the object is of the specified type, false otherwise. release Type: Function. Description: Destroys the object's Lua reference. The object will be completely deleted if it's not referenced by any other LÖVE object or thread. This method can be used to immediately clean up resources without waiting for Lua's garbage collector. Signature: release: function(self: Body): boolean Returns: Return TypeDescriptionbooleanTrue if the object was released by this call, false if it had been previously released. destroy Type: Function. Description: Explicitly destroys the Body and all fixtures and joints attached to it. An error will occur if you attempt to use the object after calling this function. In 0.7.2, when you don't have time to wait for garbage collection, this function may be used to free the object immediately. Signature: destroy: function(self: Body) isDestroyed Type: Function. Description: Gets whether the Body is destroyed. Destroyed bodies cannot be used. Signature: isDestroyed: function(self: Body): boolean Returns: Return TypeDescriptionbooleanWhether the Body is destroyed. getPosition Type: Function. Description: Get the position of the body. Note that this may not be the center of mass of the body. Signature: getPosition: function(self: Body): number, number Returns: Return TypeDescriptionnumberThe x position.numberThe y position. setPosition Type: Function. Description: Set the position of the body. Note that this may not be the center of mass of the body. This function cannot wake up the body. Signature: setPosition: function(self: Body, x: number, y: number) Parameters: ParameterTypeDescriptionxnumberThe x position.ynumberThe y position. getX Type: Function. Description: Get the x position of the body in world coordinates. Signature: getX: function(self: Body): number Returns: Return TypeDescriptionnumberThe x position in world coordinates. setX Type: Function. Description: Set the x position of the body. This function cannot wake up the body. Signature: setX: function(self: Body, x: number) Parameters: ParameterTypeDescriptionxnumberThe x position. getY Type: Function. Description: Get the y position of the body in world coordinates. Signature: getY: function(self: Body): number Returns: Return TypeDescriptionnumberThe y position in world coordinates. setY Type: Function. Description: Set the y position of the body. This function cannot wake up the body. Signature: setY: function(self: Body, y: number) Parameters: ParameterTypeDescriptionynumberThe y position. getTransform Type: Function. Description: Get the position and angle of the body. Note that the position may not be the center of mass of the body. An angle of 0 radians will mean 'looking to the right'. Although radians increase counter-clockwise, the y axis points down so it becomes clockwise from our point of view. Signature: getTransform: function(self: Body): number, number, number Returns: Return TypeDescriptionnumberThe x component of the position.numberThe y component of the position.numberThe angle in radians. setTransform Type: Function. Description: Set the position and angle of the body. Note that the position may not be the center of mass of the body. An angle of 0 radians will mean 'looking to the right'. Although radians increase counter-clockwise, the y axis points down so it becomes clockwise from our point of view. This function cannot wake up the body. Signature: setTransform: function(self: Body, x: number, y: number, angle: number) Parameters: ParameterTypeDescriptionxnumberThe x component of the position.ynumberThe y component of the position.anglenumberThe angle in radians. getAngle Type: Function. Description: Get the angle of the body. The angle is measured in radians. If you need to transform it to degrees, use math.deg. A value of 0 radians will mean 'looking to the right'. Although radians increase counter-clockwise, the y axis points down so it becomes ''clockwise'' from our point of view. Signature: getAngle: function(self: Body): number Returns: Return TypeDescriptionnumberThe angle in radians. setAngle Type: Function. Description: Set the angle of the body. The angle is measured in radians. If you need to transform it from degrees, use math.rad. A value of 0 radians will mean 'looking to the right'. Although radians increase counter-clockwise, the y axis points down so it becomes ''clockwise'' from our point of view. It is possible to cause a collision with another body by changing its angle. Signature: setAngle: function(self: Body, angle: number) Parameters: ParameterTypeDescriptionanglenumberThe angle in radians. getLinearVelocity Type: Function. Description: Gets the linear velocity of the Body from its center of mass. The linear velocity is the ''rate of change of position over time''. If you need the ''rate of change of angle over time'', use Body:getAngularVelocity. If you need to get the linear velocity of a point different from the center of mass: Body:getLinearVelocityFromLocalPoint allows you to specify the point in local coordinates. Body:getLinearVelocityFromWorldPoint allows you to specify the point in world coordinates. See page 136 of 'Essential Mathematics for Games and Interactive Applications' for definitions of local and world coordinates. Signature: getLinearVelocity: function(self: Body): number, number Returns: Return TypeDescriptionnumberThe x-component of the velocity vectornumberThe y-component of the velocity vector setLinearVelocity Type: Function. Description: Sets a new linear velocity for the Body. This function will not accumulate anything; any impulses previously applied since the last call to World:update will be lost. Signature: setLinearVelocity: function(self: Body, x: number, y: number) Parameters: ParameterTypeDescriptionxnumberThe x-component of the velocity vector.ynumberThe y-component of the velocity vector. getAngularVelocity Type: Function. Description: Get the angular velocity of the Body. The angular velocity is the ''rate of change of angle over time''. It is changed in World:update by applying torques, off centre forces/impulses, and angular damping. It can be set directly with Body:setAngularVelocity. If you need the ''rate of change of position over time'', use Body:getLinearVelocity. Signature: getAngularVelocity: function(self: Body): number Returns: Return TypeDescriptionnumberThe angular velocity in radians/second. setAngularVelocity Type: Function. Description: Sets the angular velocity of a Body. The angular velocity is the ''rate of change of angle over time''. This function will not accumulate anything; any impulses previously applied since the last call to World:update will be lost. Signature: setAngularVelocity: function(self: Body, velocity: number) Parameters: ParameterTypeDescriptionvelocitynumberThe new angular velocity, in radians per second getLinearDamping Type: Function. Description: Gets the linear damping of the Body. The linear damping is the ''rate of decrease of the linear velocity over time''. A moving body with no damping and no external forces will continue moving indefinitely, as is the case in space. A moving body with damping will gradually stop moving. Damping is not the same as friction - they can be modelled together. Signature: getLinearDamping: function(self: Body): number Returns: Return TypeDescriptionnumberThe value of the linear damping. setLinearDamping Type: Function. Description: Sets the linear damping of a Body See Body:getLinearDamping for a definition of linear damping. Linear damping can take any value from 0 to infinity. It is recommended to stay between 0 and 0.1, though. Other values will make the objects look 'floaty'(if gravity is enabled). Signature: setLinearDamping: function(self: Body, damping: number) Parameters: ParameterTypeDescriptiondampingnumberThe new linear damping getAngularDamping Type: Function. Description: Gets the Angular damping of the Body The angular damping is the ''rate of decrease of the angular velocity over time'': A spinning body with no damping and no external forces will continue spinning indefinitely. A spinning body with damping will gradually stop spinning. Damping is not the same as friction - they can be modelled together. However, only damping is provided by Box2D (and LOVE). Damping parameters should be between 0 and infinity, with 0 meaning no damping, and infinity meaning full damping. Normally you will use a damping value between 0 and 0.1. Signature: getAngularDamping: function(self: Body): number Returns: Return TypeDescriptionnumberThe value of the angular damping. setAngularDamping Type: Function. Description: Sets the angular damping of a Body See Body:getAngularDamping for a definition of angular damping. Angular damping can take any value from 0 to infinity. It is recommended to stay between 0 and 0.1, though. Other values will look unrealistic. Signature: setAngularDamping: function(self: Body, damping: number) Parameters: ParameterTypeDescriptiondampingnumberThe new angular damping. getMass Type: Function. Description: Get the mass of the body. Static bodies always have a mass of 0. Signature: getMass: function(self: Body): number Returns: Return TypeDescriptionnumberThe mass of the body (in kilograms). setMass Type: Function. Description: Sets a new body mass. Signature: setMass: function(self: Body, mass: number) Parameters: ParameterTypeDescriptionmassnumberThe mass, in kilograms. getInertia Type: Function. Description: Gets the rotational inertia of the body. The rotational inertia is how hard is it to make the body spin. Signature: getInertia: function(self: Body): number Returns: Return TypeDescriptionnumberThe rotational inertial of the body. setInertia Type: Function. Description: Set the inertia of a body. Signature: setInertia: function(self: Body, inertia: number) Parameters: ParameterTypeDescriptioninertianumberThe new moment of inertia, in kilograms * pixel squared. getMassData Type: Function. Description: Returns the mass, its center, and the rotational inertia. Signature: getMassData: function(self: Body): number, number, number, number Returns: Return TypeDescriptionnumberThe x position of the center of mass.numberThe y position of the center of mass.numberThe mass of the body.numberThe rotational inertia. setMassData Type: Function. Description: Overrides the calculated mass data. Signature: setMassData: function(self: Body, center_x: number, center_y: number, mass: number, inertia: number) Parameters: ParameterTypeDescriptioncenter_xnumberThe x position of the center of mass.center_ynumberThe y position of the center of mass.massnumberThe mass of the body.inertianumberThe rotational inertia. resetMassData Type: Function. Description: Resets the mass of the body by recalculating it from the mass properties of the fixtures. Signature: resetMassData: function(self: Body) getGravityScale Type: Function. Description: Returns the gravity scale factor. Signature: getGravityScale: function(self: Body): number Returns: Return TypeDescriptionnumberThe gravity scale factor. setGravityScale Type: Function. Description: Sets a new gravity scale factor for the body. Signature: setGravityScale: function(self: Body, scale: number) Parameters: ParameterTypeDescriptionscalenumberThe new gravity scale factor. getLocalCenter Type: Function. Description: Get the center of mass position in local coordinates. Use Body:getWorldCenter to get the center of mass in world coordinates. Signature: getLocalCenter: function(self: Body): number, number Returns: Return TypeDescriptionnumberThe x coordinate of the center of mass.numberThe y coordinate of the center of mass. getWorldCenter Type: Function. Description: Get the center of mass position in world coordinates. Use Body:getLocalCenter to get the center of mass in local coordinates. Signature: getWorldCenter: function(self: Body): number, number Returns: Return TypeDescriptionnumberThe x coordinate of the center of mass.numberThe y coordinate of the center of mass. isFixedRotation Type: Function. Description: Returns whether the body rotation is locked. Signature: isFixedRotation: function(self: Body): boolean Returns: Return TypeDescriptionbooleanTrue if the body's rotation is locked or false if not. setFixedRotation Type: Function. Description: Set whether a body has fixed rotation. Bodies with fixed rotation don't vary the speed at which they rotate. Calling this function causes the mass to be reset. Signature: setFixedRotation: function(self: Body, fixed: boolean) Parameters: ParameterTypeDescriptionfixedbooleanWhether the body should have fixed rotation. isAwake Type: Function. Description: Returns the sleep status of the body. Signature: isAwake: function(self: Body): boolean Returns: Return TypeDescriptionbooleanTrue if the body is awake or false if not. setAwake Type: Function. Description: Wakes the body up or puts it to sleep. Signature: setAwake: function(self: Body, awake: boolean) Parameters: ParameterTypeDescriptionawakebooleanThe body sleep status. isSleepingAllowed Type: Function. Description: Returns the sleeping behaviour of the body. Signature: isSleepingAllowed: function(self: Body): boolean Returns: Return TypeDescriptionbooleanTrue if the body is allowed to sleep or false if not. setSleepingAllowed Type: Function. Description: Sets the sleeping behaviour of the body. Should sleeping be allowed, a body at rest will automatically sleep. A sleeping body is not simulated unless it collided with an awake body. Be wary that one can end up with a situation like a floating sleeping body if the floor was removed. Signature: setSleepingAllowed: function(self: Body, allowed: boolean) Parameters: ParameterTypeDescriptionallowedbooleanTrue if the body is allowed to sleep or false if not. isActive Type: Function. Description: Returns whether the body is actively used in the simulation. Signature: isActive: function(self: Body): boolean Returns: Return TypeDescriptionbooleanTrue if the body is active or false if not. setActive Type: Function. Description: Sets whether the body is active in the world. An inactive body does not take part in the simulation. It will not move or cause any collisions. Signature: setActive: function(self: Body, active: boolean) Parameters: ParameterTypeDescriptionactivebooleanIf the body is active or not. isBullet Type: Function. Description: Get the bullet status of a body. There are two methods to check for body collisions: at their location when the world is updated (default) using continuous collision detection (CCD) The default method is efficient, but a body moving very quickly may sometimes jump over another body without producing a collision. A body that is set as a bullet will use CCD. This is less efficient, but is guaranteed not to jump when moving quickly. Note that static bodies (with zero mass) always use CCD, so your walls will not let a fast moving body pass through even if it is not a bullet. Signature: isBullet: function(self: Body): boolean Returns: Return TypeDescriptionbooleanThe bullet status of the body. setBullet Type: Function. Description: Set the bullet status of a body. There are two methods to check for body collisions: at their location when the world is updated (default) using continuous collision detection (CCD) The default method is efficient, but a body moving very quickly may sometimes jump over another body without producing a collision. A body that is set as a bullet will use CCD. This is less efficient, but is guaranteed not to jump when moving quickly. Note that static bodies (with zero mass) always use CCD, so your walls will not let a fast moving body pass through even if it is not a bullet. Signature: setBullet: function(self: Body, bullet: boolean) Parameters: ParameterTypeDescriptionbulletbooleanThe bullet status of the body. applyLinearImpulse Type: Function. Description: Applies an impulse to a body. This makes a single, instantaneous addition to the body momentum. An impulse pushes a body in a direction. A body with with a larger mass will react less. The reaction does '''not''' depend on the timestep, and is equivalent to applying a force continuously for 1 second. Impulses are best used to give a single push to a body. For a continuous push to a body it is better to use Body:applyForce. If the position to apply the impulse is not given, it will act on the center of mass of the body. The part of the impulse not directed towards the center of mass will cause the body to spin (and depends on the rotational inertia). Note that the impulse components and position must be given in world coordinates. Signature: applyLinearImpulse: function(self: Body, x_impulse: number, y_impulse: number, point_x?: number, point_y?: number) Parameters: ParameterTypeDescriptionx_impulsenumberThe x component of the impulse.y_impulsenumberThe y component of the impulse.point_xnumberThe x position to apply the impulse.point_ynumberThe y position to apply the impulse. applyAngularImpulse Type: Function. Description: Applies an angular impulse to a body. This makes a single, instantaneous addition to the body momentum. A body with with a larger mass will react less. The reaction does '''not''' depend on the timestep, and is equivalent to applying a force continuously for 1 second. Impulses are best used to give a single push to a body. For a continuous push to a body it is better to use Body:applyForce. Signature: applyAngularImpulse: function(self: Body, impulse: number) Parameters: ParameterTypeDescriptionimpulsenumberThe impulse in kilogram-square meter per second. applyForce Type: Function. Description: Apply force to a Body. A force pushes a body in a direction. A body with with a larger mass will react less. The reaction also depends on how long a force is applied: since the force acts continuously over the entire timestep, a short timestep will only push the body for a short time. Thus forces are best used for many timesteps to give a continuous push to a body (like gravity). For a single push that is independent of timestep, it is better to use Body:applyLinearImpulse. If the position to apply the force is not given, it will act on the center of mass of the body. The part of the force not directed towards the center of mass will cause the body to spin (and depends on the rotational inertia). Note that the force components and position must be given in world coordinates. Signature: applyForce: function(self: Body, x_force: number, y_force: number, point_x?: number, point_y?: number) Parameters: ParameterTypeDescriptionx_forcenumberThe x component of force to apply.y_forcenumberThe y component of force to apply.point_xnumberThe x position to apply the force.point_ynumberThe y position to apply the force. applyTorque Type: Function. Description: Apply torque to a body. Torque is like a force that will change the angular velocity (spin) of a body. The effect will depend on the rotational inertia a body has. Signature: applyTorque: function(self: Body, torque: number) Parameters: ParameterTypeDescriptiontorquenumberThe torque to apply. getType Type: Function. Description: Returns the type of the body. Signature: getType: function(self: Body): string Returns: Return TypeDescriptionstringThe body type. setType Type: Function. Description: Sets a new body type. Signature: setType: function(self: Body, body_type: string) Parameters: ParameterTypeDescriptionbody_typestringThe new type. getWorldPoint Type: Function. Description: Transform a point from local coordinates to world coordinates. Signature: getWorldPoint: function(self: Body, x: number, y: number): number, number Parameters: ParameterTypeDescriptionxnumberThe x position in local coordinates.ynumberThe y position in local coordinates. Returns: Return TypeDescriptionnumberThe x position in world coordinates.numberThe y position in world coordinates. getWorldVector Type: Function. Description: Transform a vector from local coordinates to world coordinates. Signature: getWorldVector: function(self: Body, x: number, y: number): number, number Parameters: ParameterTypeDescriptionxnumberThe vector x component in local coordinates.ynumberThe vector y component in local coordinates. Returns: Return TypeDescriptionnumberThe vector x component in world coordinates.numberThe vector y component in world coordinates. getWorldPoints Type: Function. Description: Transforms multiple points from local coordinates to world coordinates. Signature: getWorldPoints: function(self: Body, x: number, y: number, coordinates: number...): number... Parameters: ParameterTypeDescriptionxnumberThe x position of the first point.ynumberThe y position of the first point.coordinatesnumber...The x position of the second point. Returns: Return TypeDescriptionnumber...The transformed x position of the first point. getLocalPoint Type: Function. Description: Transform a point from world coordinates to local coordinates. Signature: getLocalPoint: function(self: Body, x: number, y: number): number, number Parameters: ParameterTypeDescriptionxnumberThe x position in world coordinates.ynumberThe y position in world coordinates. Returns: Return TypeDescriptionnumberThe x position in local coordinates.numberThe y position in local coordinates. getLocalVector Type: Function. Description: Transform a vector from world coordinates to local coordinates. Signature: getLocalVector: function(self: Body, x: number, y: number): number, number Parameters: ParameterTypeDescriptionxnumberThe vector x component in world coordinates.ynumberThe vector y component in world coordinates. Returns: Return TypeDescriptionnumberThe vector x component in local coordinates.numberThe vector y component in local coordinates. getLocalPoints Type: Function. Description: Transforms multiple points from world coordinates to local coordinates. Signature: getLocalPoints: function(self: Body, x: number, y: number, coordinates: number...): number... Parameters: ParameterTypeDescriptionxnumber(Argument) The x position of the first point.ynumber(Argument) The y position of the first point.coordinatesnumber...(Argument) The x position of the second point. Returns: Return TypeDescriptionnumber...(Result) The transformed x position of the first point. getLinearVelocityFromWorldPoint Type: Function. Description: Get the linear velocity of a point on the body. The linear velocity for a point on the body is the velocity of the body center of mass plus the velocity at that point from the body spinning. The point on the body must given in world coordinates. Use Body:getLinearVelocityFromLocalPoint to specify this with local coordinates. Signature: getLinearVelocityFromWorldPoint: function(self: Body, x: number, y: number): number, number Parameters: ParameterTypeDescriptionxnumberThe x position to measure velocity.ynumberThe y position to measure velocity. Returns: Return TypeDescriptionnumberThe x component of velocity at point (x,y).numberThe y component of velocity at point (x,y). getLinearVelocityFromLocalPoint Type: Function. Description: Get the linear velocity of a point on the body. The linear velocity for a point on the body is the velocity of the body center of mass plus the velocity at that point from the body spinning. The point on the body must given in local coordinates. Use Body:getLinearVelocityFromWorldPoint to specify this with world coordinates. Signature: getLinearVelocityFromLocalPoint: function(self: Body, x: number, y: number): number, number Parameters: ParameterTypeDescriptionxnumberThe x position to measure velocity.ynumberThe y position to measure velocity. Returns: Return TypeDescriptionnumberThe x component of velocity at point (x,y).numberThe y component of velocity at point (x,y).