The Corona Physics API

Corona makes it very easy to add physics to your games, even if you've never worked with a physics engine before. While the underlying engine is built around the well-known Box2D, we've taken a radically different design approach that eliminates most of the coding that is traditionally required.

In addition, we've tied physics seamlessly into mobile development: for example, using our new "gameUI" library, any physics object can now be made multitouch-draggable with one additional line of code.

To work with the Corona physics engine, you begin with familiar Corona objects. Corona treats physical body properties as an extension of its graphics objects: any standard display object, including images, vector drawings, or animated sprites, can be “made physical”, and will automatically begin to interact with other objects in the simulation.

Our design goal is to allow users to think primarily in terms of visible game elements wherever possible, as opposed to constructing an invisible physical world and then attaching visible sprites afterwards.

Also, Corona automatically translates between its familiar onscreen units and the internal metric units of the physical simulation. All position values are exposed in pixels, which are converted internally to meters at a default ratio of 30 pixels per meter (this ratio is user-settable with physics.setScale).

For consistency with the rest of the Corona SDK, all angular values are exposed in degrees, rather than radians, and position (0,0) remains at the upper left-hand corner of the screen, with the y-axis pointing downwards. Shape definitions should declare their points in clockwise order.

Physics world setup

This line makes the physics engine features available under the “physics” namespace:

local physics = require "physics"

Starting, pausing, and stopping the physics world

The following functions start, pause, and stop the physics simulation.

physics.start() either instantiates or resumes the world. IMPORTANT: it must be called before any of the other functions in this section.

physics.stop() is treated as a request to destroy the world, so if you merely want to pause the physics engine, you should use physics.pause().

physics.start()   -- must do this before any other physics call!
 
physics.pause()
physics.stop()

By default, Box2D bodies not involved in a collision will "sleep" after a couple of seconds. This reduces overhead, but in some cases you may not want this behavior. For example, the "ShapeTumbler" sample code will not work well if bodies are allowed to sleep, since sleeping bodies do not respond to changes in the direction of gravity.

You can override this behavior on a given body with body.isSleepingAllowed = false, but you can also override this globally for all bodies in the world by using an optional boolean parameter in start:

physics.start( true ) -- prevent all bodies from sleeping
 
physics.start( false ) -- default behavior; bodies may sleep

physics.setGravity

Sets the x,y components of the global gravity vector, in units of m/s². The default is ( 0, 9.8 ) to simulate standard Earth gravity, pointing downwards on the y-axis.

physics.setGravity( 0, 10 )

physics.getGravity

Returns the x,y components of the global gravity vector, in units of m/s². This takes advantage of the fact that Lua functions can return multiple values.

gx, gy = physics.getGravity()

Tilt-based gravity

Using the above setter, and the existing Corona accelerometer API, it is very easy to implement tilt-based dynamic gravity (note that the y-component returned by the accelerometer hardware must be inverted to conform to Corona coordinates):

local function onTilt( event )
        physics.setGravity( 10 * event.xGravity, -10 * event.yGravity )
end
 
Runtime:addEventListener( "accelerometer", onTilt )

See the “ShapeTumbler” sample project for an example of this feature (the accelerometer is not present in the Corona Simulator, so create a device build to see the effect).

physics.setScale

Sets the internal pixels-per-meter ratio that is used in converting between onscreen Corona coordinates and simulated physics coordinates. This should be done only once, before any physical objects are instantiated.

Changing this value has no visual consequences, and simply affects the accuracy of the physical model. The Box2D engine is tuned for simulating medium-sized objects between 0.1m and 10m in size, so it works best when the objects in your game are mapped to physical properties that fall roughly within this range.

The default scaling value is 30, which means that the optimal 0.1m to 10m range corresponds to visible sprites between 3 and 300 pixels in size, which should cover most typical iPhone content. For higher-resolution devices like iPad, Android, or iPhone 4, you may wish to increase this value to 60 or more.

physics.setScale( 60 )

You may also want to increase this value if the objects you are simulating are relatively small. As a rough guide, take the width of a sprite in pixels and divide it by its real-world width, if any. For example, a basketball is about 0.25 meters across, so a 20-pixel basketball sprite suggests a physics scaling factor of roughly (20 / 0.25) = 80. However, the resulting effect also depends on how much your chosen density (mass) values approximate the "real world". Therefore, you should ultimately set this scaling factor to whatever feels right within the context of your game: if objects seem too sluggish, and fall too slowly, then they are too big and heavy for your purposes -- try raising the scaling value and/or reducing their densities.

Note that this pixels-per-meter factor is relative to your original content dimensions, if you use the Corona content scaling features to deploy the same code across different screen resolutions (such as iPhone and Android). See the Corona API Reference for more information on autoscaling content for multiple screens.

Also, since onscreen objects are not resized when this value is changed, the visible simulation may behave strangely if it is changed while physical objects are already onscreen. In other words, this setting is not the correct way to visibly scale the world. To do that, you should add all the game objects to a common Corona display group, which will cause the simulation to operate according to the group’s internal coordinates rather than the global stage coordinates, and then scale or pan that group. See the “EggBreaker” sample code for a demonstration of this technique.

physics.setDrawMode

Selects one of three possible rendering modes for the physics engine. This mode may be changed at any time -- see the "DebugDraw" sample project for an example of how to toggle it on the fly.

physics.setDrawMode( "debug" ) -- shows collision engine outlines only
physics.setDrawMode( "hybrid" ) -- overlays collision outlines on normal Corona objects
physics.setDrawMode( "normal" ) -- the default Corona renderer, with no collision outlines

While this feature will also run on devices, it will probably be most useful in the Corona Simulator, when debugging unexpected physics engine behavior.

When working with Corona display groups and Box2D, it is important to keep in mind that Box2D expects all physics objects to share a global coordinate system. This means that a set of ungrouped Corona objects will work well, and a set of objects that are all added to the same display group should also work, since they will share the internal coordinates of that group -- this is demonstrated in the "EggBreaker" sample code, which uses a single moving display group to create a "moving camera" effect.

However, unexpected results may occur if physical objects are added to different display groups, especially if the groups are then moved in different directions. The "hybrid" draw mode makes these issues much easier to diagnose, since it lets you overlay the physics engine's collision boxes and shapes on top of the Corona renderer.

The physics data is displayed using color-coded vector graphics, which reflect different object types and attributes:

• Orange: dynamic physics bodies (the default body type)
• Dark blue: kinematic physics bodies
• Green: static physics bodies, such as the ground or walls
• Gray: a body that is "sleeping" due to lack of activity
• Light blue: joints

NOTE: While the physics debug draw renderer should correctly account for physics objects in nested display groups, it will display misleading results if display groups are rotated or scaled. This will be addressed in a future release.

physics.setPositionIterations

Sets the accuracy of the engine's position calculations.

physics.setPositionIterations( 16 )

The default value is 8, which means that the engine will iterate through eight position approximations per frame for each object. Increasing this number will cause fewer momentary innacuracies (overlapping objects. etc.) but will increase computational overhead. The default value should be good for most general cases.

physics.setVelocityIterations

Sets the accuracy of the engine's velocity calculations.

physics.setVelocityIterations( 6 )

The default value is 3, which means that the engine will iterate through three velocity approximations per frame for each object. Increasing this number will cause fewer momentary innacuracies (overlapping objects. etc.) but will increase computational overhead. The default value should be good for most general cases.

A note for current Box2D users

Corona incorporates version v2.1.2 of the Box2D physics engine written by Erin Catto of Blizzard Entertainment.

Porting Box2D applications from other platforms should be fairly easy. The Corona API includes most of the core features of Box2D, including:

• Automatic world setup, scaling, and synchronization with visible Corona objects
• Basic collision geometry (boxes, circles and arbitrary polygons)
• Complex collision geometry (multi-element bodies)
• Attributes for primary body and fixture properties
• Collision events via Corona event listeners, including collision forces
• Primary collision event phases: began and ended
• Additional collision event types: preCollision and postCollision, which correspond to Box2D "preSolve" and "postSolve" collision features
• Draggable object handling within the simulation
• Eight types of joints: distance, pivot, piston, friction, weld, wheel, pulley and touch (some of these are renamed from their Box2D counterparts; see “Joints” section below)
• Touch joints (based on Box2D "mouse joints") can be used with multitouch, for simultaneous dragging of 5-10 physics objects; see "DebugDraw" sample project
• Joint motors and limits
• Applied forces and impulses, both linear and angular
• Dynamic gravity, including accelerometer-driven gravity
• Sensors and bullets
• Collision categories, masking and groups
• “DebugDraw” mode, including an exclusive "hybrid" mode showing the debug view as an overlay
• Joint and body destructors

Features not yet supported include:

• Gear joints
• Ray casting, region queries, etc.
• Automatic resizing of physics objects when Corona display objects are resized with xScale/yScale attributes (avoid using xScale/yScale on an already-existing physical object in the meantime).