physics.addBody()

Type Function
Library physics.*
Return value Boolean
Revision Current Public Release (2014.2189)
Keywords bodies, physics, body, shape, outline
See also Physics Bodies
physics.removeBody()

Overview

Allows you to turn almost any Corona display object into a simulated physical object with one line of code, including the assignment of physical properties.

Gotchas

Syntax

Rectangular Body

physics.addBody( object, [bodyType,] { density=d, friction=f, bounce=b [,filter=f] } )

Circular Body

physics.addBody( object, [bodyType,] { density=d, friction=f, bounce=b, radius=r [,filter=f] } )

Polygonal Body

physics.addBody( object, [bodyType,] { density=d, friction=f, bounce=b, shape=s [,filter=f] } )

Multi-Element Body

physics.addBody( object, [bodyType,]
   {density=d1, friction=f1, bounce=b1, shape=s1},
   {density=d2, friction=f2, bounce=b2, shape=s2},
   {density=d3, friction=f3, bounce=b3, shape=s3}
)

Outline Body

physics.addBody( object, [bodyType,] { density=d, friction=f, bounce=b, outline={} [,filter=f] } )
object (required)

DisplayObject. The display object to add a physics body to.

bodyType (optional)

String. The body type may be specified in an optional string parameter before the first body element. The possible types are "static", "dynamic" and "kinematic". The default type is "dynamic" if no value is specified. See object.bodyType for more information.

density (optional)

Number. Multiplied by the area of the body’s shape to determine mass. Based on a standard value of 1.0 for water. Lighter materials (such as wood) have a density below 1.0, and heavier materials (such as stone) have a density greater than 1.0. Default value is 1.0.

friction (optional)

Number. May be any non-negative value; a value of 0.0 means no friction and 1.0 means fairly strong friction. The default value is 0.3.

bounce (optional)

Number. Determines how much of an object's velocity is returned after a collision. The default value is 0.2.

radius (optional)

Number. Radius of the bounding circle.

shape (optional)

Array. Shape array containing the shape's vertices: { x1,y1, x2,y2, ..., xn,yn }. For example pentagonShape = { 0,-37, 37,-10, 23,34, -23,34, -37,-10 }. The coordinates must be defined in clockwise order, and the resulting shape must be convex at all angle points. The physics engine assumes that the 0,0 point is the center of the object. A negative x will be to the left of object's center and a negative y will be top of object's center.

outline (optional)

Array. An outline array generated by graphics.newOutline(). outline has fewer restrictions than shape, for example, an outline can be either convex or concave.

filter (optional)

Table. Filter values. See Collision Detection for more information.

  • categoryBits = cb where cb is the category of object (generally only one bit set). Defaults to 0x0001 if not set.
  • maskBits = mb, where mb is the categories that the shape would accept for collision. Defaults to 0xFFFF
  • groupIndex = gb, where gb specifies that a certain group of objects will never collide (negative) or always collide (positive). Defaults to 0 (disabled). If groupIndex is set to non-zero, it overrides the maskBits setting.

Examples

Rectangular Body
local sky = display.newImage( "bkg_clouds.png" )
sky.x = 160; sky.y = 195

local ground = display.newImage( "ground.png" )
ground.x = 160; ground.y = 445

physics.addBody( ground, "static", { friction=0.5, bounce=0.3 } )

local crate = display.newImage( "crate.png" )
crate.x = 180; crate.y = -50; crate.rotation = 5

physics.addBody( crate, { density=3.0, friction=0.5, bounce=0.3 } )
Circular Body
local ball = display.newImage( "ball.png" )

physics.addBody( ball, { density=1.0, friction=0.3, bounce=0.2, radius=25 } )
Polygonal Body
local pentagon = display.newImage("pentagon.png")

pentagonShape = { 0,-37, 37,-10, 23,34, -23,34, -37,-10 }

physics.addBody( pentagon, { density=3.0, friction=0.8, bounce=0.3, shape=pentagonShape } )
Multi-Element Body
local nebula = display.newImage( "nebula.png" )
nebula.x, nebula.y = display.contentCenterX, display.contentCenterY

local podT = {1,-89, 14,-83, 20,-70, 14,-57, 1,-51, -12,-57, -18,-70, -12,-83}
local podR = {69,-20, 82,-14, 88,-1, 82,12, 69,18, 56,12, 50,-1, 56,-14}
local podB = {1,49, 14,55, 20,68, 14,81, 1,87, -12,81, -18,68, -12,55}
local podL = {-70,-20, -57,-14, -51,-1, -57,12, -70,18, -83,12, -89,-1, -83,-14}

physics.addBody( nebula, "dynamic",
    { shape=podT },
    { shape=podR },
    { shape=podB },
    { shape=podL }
)
Outline Body
--"graphics.newOutline()" is restricted to Pro and Enterprise users

local image_name = "star.png"

local image_outline = graphics.newOutline( 2, image_name )

local image_star = display.newImageRect( image_name )

physics.addBody( image_star, { outline=image_outline } )