Here is very simple example of box2d engine in Gideros Mobile. This example shows, how to create static and dynamic objects from shape or image and run your world.

First thing will do is to put everything in one scene, so we won't polute global scope and if we ever want to use SceneManager class, it would be simple for us to treat it as single scene.

--include box2d library
require "box2d"

--let's create separate scene and hold everything there
--then it will be easier to reuse it if you want to use SceneManager class
scene = gideros.class(Sprite)

Then let's try creating box2d body. Let's create boundary walls to limit our visible area, so object won't fall out from it. It will be a static object represented by shape object. One thing to note, that you need to draw shape object using (0,0) coordinates as center of object.

-- for creating objects using shape
-- as example - bounding walls
function scene:wall(x, y, width, height)
	local wall =
	--define wall shape
	--we make use (0;0) as center of shape,
	--thus we have half of width and half of height in each direction
	wall:lineTo(width/2, -height/2)
	wall:lineTo(width/2, height/2)
	wall:lineTo(-width/2, height/2)
	--create box2d physical object
	local body ={type = b2.STATIC_BODY}
	body:setPosition(wall:getX(), wall:getY())
	body:setAngle(wall:getRotation() * math.pi/180)
	local poly =
	poly:setAsBox(wall:getWidth()/2, wall:getHeight()/2)
	local fixture = body:createFixture{shape = poly, density = 1.0, 
	friction = 0.1, restitution = 0.2}
	wall.body = body
	wall.body.type = "wall"
	--add to scene
	--return created object
	return wall

Next let's try creating dynamic object. Let's create a ball, that will abide laws of physics.

-- for creating objects using image
-- as example - ball
function scene:ball(x, y)
	--create ball bitmap object from ball graphic
	local ball ="./ball.png"))
	--reference center of the ball for positioning
	--get radius
	local radius = ball:getWidth()/2
	--create box2d physical object
	local body ={type = b2.DYNAMIC_BODY}
	body:setPosition(ball:getX(), ball:getY())
	body:setAngle(ball:getRotation() * math.pi/180)
	local circle =, 0, radius)
	local fixture = body:createFixture{shape = circle, density = 1.0, 
	friction = 0.1, restitution = 0.2}
	ball.body = body
	ball.body.type = "ball"
	--add to scene
	--return created object
	return ball

Now we need to create function to run box2d world and move all sprites (shapes and images) according to their box2d body objects

--running the world
function scene:onEnterFrame() 
	-- edit the step values if required. These are good defaults!, 8, 3)
	--iterate through all child sprites
	for i = 1, self:getNumChildren() do
		--get specific sprite
		local sprite = self:getChildAt(i)
		-- check if sprite HAS a body (ie, physical object reference we added)
		if sprite.body then
			--update position to match box2d world object's position
			--get physical body reference
			local body = sprite.body
			--get body coordinates
			local bodyX, bodyY = body:getPosition()
			--apply coordinates to sprite
			sprite:setPosition(bodyX, bodyY)
			--apply rotation to sprite
			sprite:setRotation(body:getAngle() * 180 / math.pi)

And remember, if you are using SceneManager class, you'll need to remove onenterframe event handler, when exiting scene

--removing event on exiting scene
--just in case you're using SceneManager
function scene:onExitBegin()
  self:removeEventListener(Event.ENTER_FRAME, self.onEnterFrame, self)

Now let's create bounding walls and one dynamic ball on scene initialization. Additionally we need to set up event handlers and debug drawing to see if everything moves just as it was suuposed to.

--on scene initialization
function scene:init()
	--create world instance =, 10, true)
	local screenW = application:getContentWidth()
	local screenH = application:getContentHeight()
	--create bounding walls outside the scene
	--create ball
	self:ball(100, 100)
	--set up debug drawing
	local debugDraw =
	--run world
	self:addEventListener(Event.ENTER_FRAME, self.onEnterFrame, self)
	--remove event on exiting scene
	self:addEventListener("exitBegin", self.onExitBegin, self)

And last, if you are using SceneManager, you should simply include scene upon it's initalization, but if not, you need to create instance of this scene sprite and add it to stage:

--add created scene to stage or sceneManager
local mainScene =

Here is the result:

And you can also download this sample Gideros project.