physics.addBody()

Type Function
Library physics.*
Return value Boolean
Revision Release 2024.3703
Keywords bodies, physics, body, shape, outline
See also Physics Bodies (guide)
physics.removeBody()
graphics.newOutline()

Overview

This function turns almost any Corona display object into a simulated physical object with specific physical properties. It accepts the display object, an optional body type (string), and an optional params table containing key-value pairs that specify the properties for the physics body. Within this params table, the following apply:

Gotchas

Syntax

physics.addBody( object, [bodyType,] [params] )
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.

params (optional)

Table. A table of key-value pairs that specifies the properties of the body — see the next section for details. For multi-element bodies, multiple distinct params tables can be declared in a comma-delimited series (one for each body element).

Parameter Reference

The params table includes the properties for the physics body.

Core Parameters

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.0.

bounce (optional)

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

isSensor (optional)

Boolean. Sets the body as a sensor. A sensor is a fixture that detects collisions but does not produce a physical response.

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.

Circular Body

radius

Number. Radius of the bounding circle.

Polygonal Body

shape

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.

Offset/Angled Rectangular Body

box

Table. A table of key-value pairs including:

  • halfWidth — Half of the body width. This property is required.
  • halfHeight — Half of the body height. This property is required.
  • x — The x offset (±) from the display object's center. If you offset the body along the x axis, you must also specify the y offset, even if no offset should occur along that axis (simply specify y=0).
  • y — The y offset (±) from the display object's center. If you offset the body along the y axis, you must also specify the x offset, even if no offset should occur along that axis (simply specify x=0).
  • angle — The angle (rotation) of the body. This property is optional and defaults to 0.

Edge Shape (Chain) Body

chain

Array. An array of vertices to define the edge shape. Edge shapes are not restricted to convex angles like polygonal bodies.

connectFirstAndLastChainVertex (optional)

Boolean. If set to true, the first and last vertices will be joined by a straight line. If set to false (default), the edge shape will have disconnected ends.

Important

You should not construct an edge shape body with self-intersecting segments — in other words, your definition of vertices should not result in any segments of the chain intersecting with other segments. Doing so many break the expected collision detection of the shape.

Outline Body

outline

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

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")
 
local 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",
    { friction=0.2, bounce=0.4, shape=podT },
    { friction=0.8, bounce=0.0, shape=podR },
    { friction=0.8, bounce=0.0, shape=podB },
    { friction=0.2, bounce=0.4, shape=podL }
)
Offset/Angled Rectangular Body
local body = display.newRect( 100, 200, 40, 40 )

local offsetRectParams = { halfWidth=5, halfHeight=10, x=10, y=0, angle=60 }

physics.addBody( body, "dynamic", { box=offsetRectParams } )
Edge Shape (Chain) Body
local body = display.newRect( 150, 200, 40, 40 )

physics.addBody( body, "static",
    {
        chain={ -120,-140, -100,-90, -80,-60, -40,-20, 0,0, 40,0, 70,-10, 110,-20, 140,-20, 180,-10 },
        connectFirstAndLastChainVertex = true
    }
)
Outline Body
local image_name = "star.png"

local image_outline = graphics.newOutline( 2, image_name )

local image_star = display.newImageRect( image_name, 32, 32 )

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