Class PhysicsWorld

java.lang.Object
com.codename1.gaming.physics.PhysicsWorld
public class PhysicsWorld extends Object

A 2D rigid body physics world, wrapping a shaded Box2D (JBox2D) simulation in an idiomatic Codename One API.

The world works in pixels on the outside and meters internally (Box2D is tuned for objects a few meters in size, so feeding it pixels directly produces a sluggish, unstable simulation). The conversion is governed by #setPixelsPerMeter(float) (default 30). The screen y axis points down while Box2D's points up; the wrapper flips y so application code stays in screen coordinates -- so a positive gravity y value pulls bodies down the screen.

Drive the simulation from a com.codename1.gaming.GameView update loop:

PhysicsWorld world = new PhysicsWorld(0, 600); // gravity 600 px/s^2 downward
PhysicsBody ground = world.createBox(0, 460, 320, 40, BodyType.STATIC);
PhysicsBody crate = world.createBox(160, 0, 32, 32, BodyType.DYNAMIC);
crate.setLinkedSprite(crateSprite);
// in update(dt):
world.step((float) dt);   // integrates and syncs linked sprites

  • Constructor Summary

    Constructors
    Constructor
    Description
    PhysicsWorld(float gravityXPx, float gravityYPx)
    Creates a world with the given gravity in pixels per second squared.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addContactListener(ContactListener listener)
    Registers a contact listener notified when bodies start and stop touching.
    PhysicsBody
    createBox(float xPx, float yPx, float widthPx, float heightPx, BodyType type)
    Creates a rectangular body centered at the given pixel position.
    PhysicsBody
    createCircle(float xPx, float yPx, float radiusPx, BodyType type)
    Creates a circular body centered at the given pixel position.
    PhysicsJoint
    createDistanceJoint(PhysicsBody a, PhysicsBody b, float anchorAXPx, float anchorAYPx, float anchorBXPx, float anchorBYPx, float frequencyHz, float dampingRatio)
    A spring/rod joint that keeps the two pixel anchor points a fixed distance apart.
    PhysicsJoint
    createMouseJoint(PhysicsBody ground, PhysicsBody target, float targetXPx, float targetYPx, float maxForce)
    A mouse joint that pulls target toward a moving pixel point with a capped force -- the basis for dragging a body with a finger.
    PhysicsBody
    createPolygon(float xPx, float yPx, float[] verticesPx, BodyType type)
    Creates a convex polygon body.
    PhysicsJoint
    createPrismaticJoint(PhysicsBody a, PhysicsBody b, float anchorXPx, float anchorYPx, float axisX, float axisY)
    A prismatic (slider) joint: body b may only translate along the given pixel axis relative to body a (e.g. a piston or an elevator).
    PhysicsJoint
    createRevoluteJoint(PhysicsBody a, PhysicsBody b, float anchorXPx, float anchorYPx)
    A pin/hinge joint: the two bodies rotate freely around the shared pixel anchor (e.g. a wheel on an axle, a ragdoll elbow).
    PhysicsBody
    createShape(float xPx, float yPx, Shape shape, BodyType type)
    Creates a body whose collision outline is a Codename One com.codename1.ui.geom.Shape -- typically a com.codename1.ui.geom.GeneralPath -- so you can describe a hit-shape with the same geometry API you draw with.
    PhysicsJoint
    createWeldJoint(PhysicsBody a, PhysicsBody b, float anchorXPx, float anchorYPx)
    A weld joint: the two bodies are locked rigidly together at the pixel anchor (as if glued).
    void
    debugDraw(Graphics g)
    Renders the world's collision shapes, joints and (optionally) bounding boxes onto the given com.codename1.ui.Graphics, for debugging.
    void
    destroyJoint(PhysicsJoint joint)
    Removes a joint from the world.
    World
    getNativeWorld()
    Returns the underlying shaded Box2D world for advanced use.
    float
    getPixelsPerMeter()
     
    void
    removeBody(PhysicsBody body)
    Removes a body from the world.
    void
    removeContactListener(ContactListener listener)
     
    void
    setDebugDrawFlags(boolean shapes, boolean joints, boolean boundingBoxes)
    Selects what #debugDraw(com.codename1.ui.Graphics) renders.
    void
    setDebugFillAlpha(int alpha)
    Sets the alpha (0..255) used to fill solid shapes in #debugDraw(com.codename1.ui.Graphics); shape outlines stay opaque.
    void
    setGravity(float gxPx, float gyPx)
    Sets gravity in pixels per second squared (positive y is downward).
    void
    setPixelsPerMeter(float ppm)
    The pixels-per-meter scale used to convert between screen and simulation units.
    void
    setPositionIterations(int positionIterations)
     
    void
    setVelocityIterations(int velocityIterations)
     
    void
    step(float deltaSeconds)
    Advances the simulation by the given time step (seconds) and then syncs every body's transform into its linked PhysicsLinkable (typically a com.codename1.gaming.Sprite).
    void
    syncSprites()
    Pushes each body's current transform into its linked object, converting meters to pixels and flipping the y axis.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • PhysicsWorld

      public PhysicsWorld(float gravityXPx, float gravityYPx)
      Creates a world with the given gravity in pixels per second squared. A positive y pulls bodies down the screen.

  • Method Details

    • setPixelsPerMeter

      public void setPixelsPerMeter(float ppm)
      The pixels-per-meter scale used to convert between screen and simulation units. Set this once before creating bodies.

    • getPixelsPerMeter

      public float getPixelsPerMeter()

    • setVelocityIterations

      public void setVelocityIterations(int velocityIterations)

    • setPositionIterations

      public void setPositionIterations(int positionIterations)

    • setGravity

      public void setGravity(float gxPx, float gyPx)
      Sets gravity in pixels per second squared (positive y is downward).

    • step

      public void step(float deltaSeconds)
      Advances the simulation by the given time step (seconds) and then syncs every body's transform into its linked PhysicsLinkable (typically a com.codename1.gaming.Sprite). Call once per frame from the game loop.

    • syncSprites

      public void syncSprites()
      Pushes each body's current transform into its linked object, converting meters to pixels and flipping the y axis. Called automatically by #step(float).

    • createBox

      public PhysicsBody createBox(float xPx, float yPx, float widthPx, float heightPx, BodyType type)
      Creates a rectangular body centered at the given pixel position.

    • createCircle

      public PhysicsBody createCircle(float xPx, float yPx, float radiusPx, BodyType type)
      Creates a circular body centered at the given pixel position.

    • createPolygon

      public PhysicsBody createPolygon(float xPx, float yPx, float[] verticesPx, BodyType type)
      Creates a convex polygon body. The vertices are pixel offsets relative to the body center, as alternating x,y pairs (so verticesPx.length must be even).

    • createShape

      public PhysicsBody createShape(float xPx, float yPx, Shape shape, BodyType type)

      Creates a body whose collision outline is a Codename One com.codename1.ui.geom.Shape -- typically a com.codename1.ui.geom.GeneralPath -- so you can describe a hit-shape with the same geometry API you draw with. The shape's coordinates are pixel offsets relative to the body center (xPx, yPx); Bezier curves are flattened to line segments.

      Each subpath becomes one fixture on the body (so a figure with several disconnected outlines yields a compound body). A subpath is converted as follows:

      • A closed, convex subpath of at most Settings.maxPolygonVertices (8) points becomes a solid PolygonShape -- usable by bodies of any BodyType.

      • Any other subpath (concave, more than 8 points, or left open) becomes a ChainShape -- an exact but one-sided edge outline. Chains are ideal for BodyType#STATIC terrain; a dynamic body needs convex pieces to behave as a solid, so split a concave dynamic shape into convex subpaths.

      For a single, simple convex hull #createPolygon(float, float, float[], BodyType) is a lighter-weight alternative.

    • removeBody

      public void removeBody(PhysicsBody body)
      Removes a body from the world.

    • addContactListener

      public void addContactListener(ContactListener listener)
      Registers a contact listener notified when bodies start and stop touching.

    • removeContactListener

      public void removeContactListener(ContactListener listener)

    • getNativeWorld

      public World getNativeWorld()
      Returns the underlying shaded Box2D world for advanced use. Coordinates on the native world are in meters with y pointing up.

    • createRevoluteJoint

      public PhysicsJoint createRevoluteJoint(PhysicsBody a, PhysicsBody b, float anchorXPx, float anchorYPx)
      A pin/hinge joint: the two bodies rotate freely around the shared pixel anchor (e.g. a wheel on an axle, a ragdoll elbow).

    • createDistanceJoint

      public PhysicsJoint createDistanceJoint(PhysicsBody a, PhysicsBody b, float anchorAXPx, float anchorAYPx, float anchorBXPx, float anchorBYPx, float frequencyHz, float dampingRatio)
      A spring/rod joint that keeps the two pixel anchor points a fixed distance apart. frequencyHz 0 makes it a rigid rod; a positive value makes it a softer spring (with dampingRatio 0..1).

    • createWeldJoint

      public PhysicsJoint createWeldJoint(PhysicsBody a, PhysicsBody b, float anchorXPx, float anchorYPx)
      A weld joint: the two bodies are locked rigidly together at the pixel anchor (as if glued).

    • createPrismaticJoint

      public PhysicsJoint createPrismaticJoint(PhysicsBody a, PhysicsBody b, float anchorXPx, float anchorYPx, float axisX, float axisY)
      A prismatic (slider) joint: body b may only translate along the given pixel axis relative to body a (e.g. a piston or an elevator).

    • createMouseJoint

      public PhysicsJoint createMouseJoint(PhysicsBody ground, PhysicsBody target, float targetXPx, float targetYPx, float maxForce)
      A mouse joint that pulls target toward a moving pixel point with a capped force -- the basis for dragging a body with a finger. ground is any body (typically a static one); update the point each frame with PhysicsJoint#setTarget(float, float).

    • destroyJoint

      public void destroyJoint(PhysicsJoint joint)
      Removes a joint from the world.

    • setDebugDrawFlags

      public void setDebugDrawFlags(boolean shapes, boolean joints, boolean boundingBoxes)
      Selects what #debugDraw(com.codename1.ui.Graphics) renders. By default it draws collision shapes and joints; bounding boxes are off.

    • debugDraw

      public void debugDraw(Graphics g)
      Renders the world's collision shapes, joints and (optionally) bounding boxes onto the given com.codename1.ui.Graphics, for debugging. Coordinates use the same pixel scale and y-flip as the bodies, so the overlay lines up with the sprites they drive. Call it from a component's paint, onto an off-screen com.codename1.ui.Image, or any other 2D drawing surface. See #setDebugDrawFlags(boolean, boolean, boolean) to choose what is drawn.

    • setDebugFillAlpha

      public void setDebugFillAlpha(int alpha)
      Sets the alpha (0..255) used to fill solid shapes in #debugDraw(com.codename1.ui.Graphics); shape outlines stay opaque. The default (90) is a light translucent fill.