Tutorial 11 - Physics 101

   Webcomic Courtesy of Ethanol & Entropy

11.1 Dropping Things

We are constantly amazed by the capability of Codea. An example of this is the integration of the Box2D physics engine. The talented folks at Two Lives Left have made incorporating physics into your App absurdly easy.

The included Physics Lab example project provides a good overview of the techniques available. However, if you are starting out, sometimes it isn't obvious how you can integrate similar functionality into your program. This tutorial will show you which bits you need to include in your project and how you can attach a sprite to a physics object.

11.2 The Setup

In our Minesweeper game we wanted to add a bit of bling to the Menu screen. To this end we thought about dropping some mines from the top of the screen. Initially we had them bouncing off the ground but this didn't seem like a sensible thing to do with a mine so we removed the ground. We have left the code for the ground in the example below in case you need it. In your Main class, we start off by reading the sprite image into the img variable. You want to do this in setup() to ensure you only read the sprite into memory once, doing it in draw() can cause your App to crash due to running out of memory.
  
The next step is to create an instance of the PhysicsDebugDraw() class which we copied from the Physics Lab example project (and modified a bit). We will cover this class in section 11.4 below.
  
We then assign the sprite image we read to the associated spriteImage parameter in PhysicsDebugDraw() and set staticVisible to false. The only static physics object we create is the ground so setting this to false means that the ground will be invisible (but there nonetheless).
  
Finally we create the physics objects, the ground (createGround), a box (createBox), a circle (createCircle) and a random sized polygon (createRandPoly). The interesting one is the circle which we will attach our sprite to. Note that the radius of the circle is the same size (32 pixels) as half the width of the sprite (64 pixels). To make this more general you could use img.width/2 in place of the 32 (assuming your sprite looks roughly circular).

	supportedOrientations(ANY)
	function setup()
	-- Physics Demo Metadata
	version = 1.0
	saveProjectInfo("Description", "Physics v"..version)
	saveProjectInfo("Author", "Reefwing Software")
	saveProjectInfo("Date", "30th July 2012")
	saveProjectInfo("Version", version)
	print("Physics Demo v"..version.."\n")
	-- Load the sprite you want to attach to your physics object
	-- you want the sprite and the object to be roughly the same
	-- size and shape.
	img = readImage("Dropbox:Mine_64x64")
	-- Create an instance of PhysicsDebugDraw(). You will need to copy
	-- this tab from the Physics Lab project or duplicate the project
	-- and make it a dependency to your project. We have modified the
	-- code to allow you to make the ground invisible and attach a
	-- sprite. A copy of the modified class is provided below.
	physicsDraw = PhysicsDebugDraw()
	physicsDraw.spriteImage = img
	physicsDraw.staticVisible = false
	-- These functions are from the Physics Lab example which we have
	-- extracted and provided in the Physics file below. As our sprite
	-- is circular we attach it to the circle sprite.
	createGround()
	createBox(WIDTH/2, 100, 30, 30)
	createCircle(WIDTH/2 + 50, HEIGHT, 32)
	createRandPoly(WIDTH/2 + 150, 120)
	end
	function draw()
	-- This sets the background color to black
	background(blackColor)
	-- Draw Demo Physics objects
	physicsDraw:draw()
	end
	function collide(contact)
	-- Leave this function out if you don't want to show the red dots
	-- which indicate the collision points.
	physicsDraw:collide(contact)
	end
	function touched(touch)
	-- Use this method to demonstrate the pointInRect() collision detection function
	if touch.state == ENDED then
	-- Create a random polygon wherever you tap the screen.
	createRandPoly(touch.x, touch.y, 25, 25)
	end
	end

view raw Main.lua hosted with ❤ by GitHub

11.3 Physics Functions

We have also extracted the following physic object creation functions from the Physics Lab example project:

• createCircle(x,y,r)
• createBox(x,y,w,h)
• createGround() - note you could change the dimensions of this by altering the physics.body polygon.
• createRandPoly(x,y) - creates a random polygon at screen co-ordinates (x,y) with between 3 and 10 sides
• cleanup() - will delete all of the physic objects that you added to the PhysicsDebugDraw rendering class. In Minesweeper we call this after creating 50 objects to ensure that we don't run out of memory. Remember that if you call this you will need to re-create any physics objects that you want to model.

	--# Physics
	--
	-- Functions from the Physics Lab example project
	-- courtesy of Two Lives Left
	function createCircle(x,y,r)
	local circle = physics.body(CIRCLE, r)
	-- enable smooth motion
	circle.interpolate = true
	circle.x = x
	circle.y = y
	circle.restitution = 0.25
	circle.sleepingAllowed = false
	physicsDraw:addBody(circle)
	return circle
	end
	function createBox(x,y,w,h)
	-- polygons are defined by a series of points in counter-clockwise order
	local box = physics.body(POLYGON, vec2(-w/2,h/2), vec2(-w/2,-h/2), vec2(w/2,-h/2), vec2(w/2,h/2))
	box.interpolate = true
	box.x = x
	box.y = y
	box.restitutions = 0.25
	box.sleepingAllowed = false
	physicsDraw:addBody(box)
	return box
	end
	function createGround()
	local ground = physics.body(POLYGON, vec2(0,20), vec2(0,0), vec2(WIDTH,0), vec2(WIDTH,20))
	ground.type = STATIC
	physicsDraw:addBody(ground)
	return ground
	end
	function createRandPoly(x,y)
	local count = math.random(3,10)
	local r = math.random(25,75)
	local a = 0
	local d = 2 * math.pi / count
	local points = {}
	for i = 1,count do
	local v = vec2(r,0):rotate(a) + vec2(math.random(-10,10), math.random(-10,10))
	a = a + d
	table.insert(points, v)
	end
	local poly = physics.body(POLYGON, unpack(points))
	poly.x = x
	poly.y = y
	poly.sleepingAllowed = false
	poly.restitution = 0.25
	physicsDraw:addBody(poly)
	return poly
	end
	function cleanup()
	clearOutput()
	physicsDraw:clear()
	end

view raw Physics.lua hosted with ❤ by GitHub

11.4 The Engine Room - PhysicsDebugDraw Class

This class renders the physics objects that you have added to it. We have made two minor modifications to the class. We added the staticVisible flag to allow you to choose whether your static objects were visible or not. Note that static bodies don't collide with other static bodies and are immovable, so they are usually used to represent the ground. 

The other thing we added was the spriteImage parameter. If this is not nil then we draw the sprite image instead of a circle. And that's all there is to it. In future tutorials we will examine some of the other capabilities enabled by the physics engine.


.  

	--# PhysicsDebugDraw
	--
	-- Class extracted from the Physics Lab project.
	-- courtesy of Two Lives Left
	--
	-- Modified by Reefwing Software
	-- Version 1.0
	PhysicsDebugDraw = class()
	function PhysicsDebugDraw:init()
	self.bodies = {}
	self.joints = {}
	self.touchMap = {}
	self.contacts = {}
	self.spriteImage = nil -- spriteImage parameter added
	self.staticVisible = true -- used to make ground invisible if required.
	end
	function PhysicsDebugDraw:addBody(body)
	table.insert(self.bodies,body)
	end
	function PhysicsDebugDraw:addJoint(joint)
	table.insert(self.joints,joint)
	end
	function PhysicsDebugDraw:clear()
	-- deactivate all bodies
	for i,body in ipairs(self.bodies) do
	body:destroy()
	end
	for i,joint in ipairs(self.joints) do
	joint:destroy()
	end
	self.bodies = {}
	self.joints = {}
	self.contacts = {}
	self.touchMap = {}
	end
	function PhysicsDebugDraw:draw()
	pushStyle()
	smooth()
	strokeWidth(5)
	stroke(128,0,128)
	local gain = 2.0
	local damp = 0.5
	for k,v in pairs(self.touchMap) do
	local worldAnchor = v.body:getWorldPoint(v.anchor)
	local touchPoint = v.tp
	local diff = touchPoint - worldAnchor
	local vel = v.body:getLinearVelocityFromWorldPoint(worldAnchor)
	v.body:applyForce( (1/1) * diff * gain - vel * damp, worldAnchor)
	line(touchPoint.x, touchPoint.y, worldAnchor.x, worldAnchor.y)
	end
	stroke(0,255,0,255)
	strokeWidth(5)
	for k,joint in pairs(self.joints) do
	local a = joint.anchorA
	local b = joint.anchorB
	line(a.x,a.y,b.x,b.y)
	end
	stroke(255,255,255,255)
	noFill()
	for i,body in ipairs(self.bodies) do
	pushMatrix()
	translate(body.x, body.y)
	rotate(body.angle)
	if body.type == STATIC then
	if self.staticVisible then
	stroke(255,255,255,255)
	else
	stroke(0,0,0,0)
	end
	elseif body.type == DYNAMIC then
	stroke(150,255,150,255)
	elseif body.type == KINEMATIC then
	stroke(150,150,255,255)
	end
	if body.shapeType == POLYGON then
	strokeWidth(5.0)
	local points = body.points
	for j = 1,#points do
	a = points[j]
	b = points[(j % #points)+1]
	line(a.x, a.y, b.x, b.y)
	end
	elseif body.shapeType == CHAIN or body.shapeType == EDGE then
	strokeWidth(5.0)
	local points = body.points
	for j = 1,#points-1 do
	a = points[j]
	b = points[j+1]
	line(a.x, a.y, b.x, b.y)
	end
	elseif body.shapeType == CIRCLE then
	if self.spriteImage == nil then
	strokeWidth(5.0)
	line(0,0,body.radius-3,0)
	strokeWidth(2.5)
	ellipse(0,0,body.radius*2)
	else
	sprite(self.spriteImage, 0, 0, body.radius*2)
	end
	end
	popMatrix()
	end
	stroke(255, 0, 0, 255)
	fill(255, 0, 0, 255)
	for k,v in pairs(self.contacts) do
	for m,n in ipairs(v.points) do
	ellipse(n.x, n.y, 10, 10)
	end
	end
	popStyle()
	end
	function PhysicsDebugDraw:touched(touch)
	local touchPoint = vec2(touch.x, touch.y)
	if touch.state == BEGAN then
	for i,body in ipairs(self.bodies) do
	if body.type == DYNAMIC and body:testPoint(touchPoint) then
	self.touchMap[touch.id] = {tp = touchPoint, body = body, anchor = body:getLocalPoint(touchPoint)}
	return true
	end
	end
	elseif touch.state == MOVING and self.touchMap[touch.id] then
	self.touchMap[touch.id].tp = touchPoint
	return true
	elseif touch.state == ENDED and self.touchMap[touch.id] then
	self.touchMap[touch.id] = nil
	return true;
	end
	return false
	end
	function PhysicsDebugDraw:collide(contact)
	if contact.state == BEGAN then
	self.contacts[contact.id] = contact
	sound(SOUND_HIT, 2643)
	elseif contact.state == MOVING then
	self.contacts[contact.id] = contact
	elseif contact.state == ENDED then
	self.contacts[contact.id] = nil
	end
	end

view raw PhysicsDebugDraw.lua hosted with ❤ by GitHub