Box2D.TestBed

A sample that shows the use of the Box2D third party add-on.

Location

You can find the TestBed sample project at:

• Start | Programs | Embarcadero RAD Studio Athens | Samples and navigate to:
  • Object Pascal\Multi-Device Samples\Physics\TestBed
  • CPP\Multi-Device Samples\Physics\TestBed
• Subversion Repository:
  • You can find Delphi and C++ code samples in GitHub Repositories. Search by name into the samples repositories according to your RAD Studio version.

Description

A sample that shows the use of the Box2D third party add-on.

The application uses the following controls:

• Timer1: A control that implements the TTimer component.
• MainPanel: The main panel of the application.
  • PaintBox: A TPaintBox control where the application draws the graphics.
  • RightPanel: The right panel of the application.
    • RightLayout: A TLayout control that groups the controls on the right side of the application.
      • ButtonsLayout: A TLayout control that groups the buttons.
        • PauseBtn: Fires the PauseBtnClick event handler.
        • QuiBtn: Fires the QuiBtnClick event handler.
        • RestartBtn: Fires the RestartBtnClick event handler.
        • SingleStepBtn: Fires the SingleStepBtnClick event handler.
      • DrawLayout: A TLayout control that groups the check boxes that control the additional functionality of the application.
        • AABsChk: Specifies whether the application displays the bounding boxes of the objects.
        • CenterOfMassesChk: Specifies whether the application displays the center of masses of the objects.
        • ContactImpulsesChk: Specifies whether the application displays the contact impulses. Only works if ContactPointsChk is enabled and ContactNormalsChk is disabled.
        • ContactNormalsChk: Specifies whether the application displays the contact normals. Only works if ContactPointsChk is enabled and ContactImpulsesChk is disabled.
        • ContactPointsChk: Specifies whether the application displays the contact points.
        • FrictionImpulsesChk: Specifies whether the application displays the friction impulses. Only works if ContactPointsChk is enabled.
        • JointsChk: Specifies whether the application displays the joints.
        • ProfilesChk: Specifies whether the application displays profiling information. The application displays 3 values for each information: the current value, the average value, and the maximum value. Some of the tests provide additional profiling and/or statistical information.
          These are the values the profiling information includes:
          • step: The step duration (how long one iteration step needs to execute).
          • collide: The number of collisions.
          • solve: The duration of the solver (how long does it take for the solver to complete).
          • solve init: The duration of the integration solver (how long does it take for the integration solver to complete).
          • solve velocity: The duration of the velocity solver (how long does it take for the velocity solver to complete).
          • solve position: The duration of the position solver (how long does it take for the position solver to complete).
          • solveTOI: The duration of the collision solver (how long does it take for the collision solver to complete).
          • broad-phase: The duration of the broad-phase of the collision processing phase.
        • ShapesChk: Specifies whether the application displays the shapes.
        • StatisticsChk: Specifies whether the application displays statistical information about the current state, such as:
          • The number of bodies, contacts, and joints.
          • The number of proxies, the height, the balance and the quality.
      • EnableLayout: A TLayout component that groups the check boxes that control nothing.
        • Sleep: Specifies whether the bodies are allowed to go sleep. This is a global that specific tests can override. The application changes the color of shapes that go to sleep to grey.
        • SubStepping: Specifies whether sub-stepping is enabled.
        • TimeOfImpact: Specifies whether continuous collision detection (CCD) is enabled.
        • WarmStarting: Specifies whether the application can cache some of the calculations in order to perform faster.
      • Line1: A TLine control for visual separation.
      • TestLabel: The label for the list of tests combo box.
      • TestList: A TComboBox control that holds the list of available tests.
  • RightSplitter: A TSplitter control for visual separation.

How to Use the Sample

1. Navigate to one of the locations given above and open:
   • Delphi: TestBed.dproj.
   • C++: TestBed.cbproj.
2. Press F9 or choose Run > Run.

• You can choose a different test from the list of tests.
• Mark any of the check boxes to enable/disable that functionality.
• Use the buttons to control the flow of the application.

You can perform the following global actions that apply to all tests:

• Move objects: You can move any dynamic object by clicking on it with the mouse and then moving the mouse.
• Bombs: There are two ways to launch a "bomb":
  • Press the SPACE key.
  • Hold shift, press the left mouse button and move the mouse. The distance of the mouse move corresponds to the velocity of the bomb. Release to launch the bomb.
• Camera control: Use the following keys to control he movement of the camera:
  • (SHIFT +) ARROW key: Moves the camera.
  • Home: Resets the position of the camera.

Some tests provide additional actions and control over some options.

The available tests are listed in the following table:

Test Name	Delphi	C++	Description
AddPair			Add Pair stress test.
ApplyForce			Shows a number of objects on a surface that simulates ice.
BasicSliderCrank			Simulates a slider crank. Use the following keys to control some options: F}: Toggle friction. If you turn the motor off, you can see the effect of the friction option. M: Toggle motor on/off.
BodyTypes			Shows the behaviour of bodies with different body types. Use the keys to toggle between the body types: D: dynamic S: static K: kinematic
Breakable			Shows two shapes that are joined together but can be broken into separate shapes.
Bridge			Simulates a bridge that consists of many shapes that are joined with a "revolute" joint.
BulletTest			Shows a collision between two shapes.
Cantilever			Demonstrates the use of the "weld" joint.
Car			Shows the use of a "wheel" joint. Use the keys to control the car: A: Turns the wheel to the left. S: Stops the wheel. D: Turns the wheel to the right. E: Increases the refresh interval (speeds up the execution). Q: Decreases the refresh interval (slows down the execution).
Chain			Simulates a chain-like body.
CharacterCollision			Shows various character collision scenarios. This test is useful for testing smooth collision on edge chains.
CollisionFiltering			Demonstrates the use of collision filtering. These are the filters that this test uses: The 3 small shapes always collide. The 3 large shapes never collide. The boxes do not collide with triangles (except if both are small).
Test Name	Delphi	C++	Description
CollisionProcessing			Demonstrates the use of collision processing and body destruction. These are the rules that this test uses: A bigger body destroys a smaller body. A circle destroys a triangle and a polygon. A triangle destroys a polygon.
CompoundShapes			Demonstrates several compound shapes.
Confined			Demonstrates the behaviour of objects in a confined space. Use the C key to create a new circle. You can see that the circles rearrange themselves to fit as well as possible inside the confined space.
Continuous Test			Simulates a drop test of a stick-shaped object and random speed and rotation angle.
Convex Hull			Test simulates a random convex hull generator. Press g to generate a new convex hull.
ConveyorBelt			A simulation of a conveyor belt.
Distance Test			Calculates and displays the shortest distance between two objects. You can control the position and the orientation of the small rectangle: A: Moves the object to the left. D: Moves the object to the right. S: Moves the object down. W: Moves the object up. Q: Rotates the object counter-clockwise. E: Rotates the object clockwise.
Dominos			Demonstrates a chain reaction that shows how the objects interact with each other.
DumpShell			Holds worlds dumped using b2World::Dump.
Dynamic Tree			Simulates a dynamic tree of bodies. You can control the some functionality of this test: A: Toggles the automatic random movement of the bodies. C: Creates a body. D: Destroys a body. M: Moves a random body.
Edge Shapes			Demonstrates a ray-cast that traverses a surface. To drop various objects to that surface, use the keys 1-5.
Edge Test			Allows you to test the friction and behaviour of a rectangle and a circle on an uneven surface.
Gears			Simulates various types of gears.
Heavy On Light			Shows a large and heavy object on that is placed on a small and light object.
Heavy On Light Two			Shows a small and heavy object on that is placed on a small and light object.
Test Name	Delphi	C++	Description
Mobile			Simulates an unbalanced mobile object.
MobileBalanced			Simulates a balanced mobile object.
MotorJoint			Shows how to use a motor joint. You can use a motor joint to animate a dynamic body.
One-Sided Platform			Demonstrates a one-sided platform. The objects can pass through the platform from below, but not from above.
Pinball			Demonstrates bullet collision and provides an example of a gameplay scenario. It also uses a loop shape.
PolyCollision			Calculates and displays the amount of collision points between two objects. You can control the position and the orientation of the big rectangle: A: Moves the object to the left. D: Moves the object to the right. S: Moves the object down. W: Moves the object up. Q: Rotates the object counter-clockwise. E: Rotates the object clockwise.
Polygon Shapes			Demonstrates stacking. It also shows how to use b2World::Query and b2TestOverlap. The application tests overlap and highlights up to 4 shapes that are inside the blue circle.
Prismatic			Shows a motor joint and allows you to control some aspects of the execution of the test. The following keys map to certain actions: L: Toggles the limits of the movement of the object. M: Toggles the motor on/off. S: Specifies the direction of the motor. This setting has no effect if the motor is turned off.
Pulleys			Simulates a pulley with two objects, one of which is heavier than the other.
Pyramid			A pyramid of rectangles.
Ray-Cast			Demonstrates the use of the ray-cast feature. Use the keys 1 - 6 to drop objects to the stage. The M key toggles the ray-cast mode between: Closest: Finds the closest hit. Any: Finds any hit. This mode is appropriate to use when you do not care about the actual fixture and hit point. Multiple: Finds multiple hits. Note: The fixtures are not necessarily reported in order, so we might not capture the closest fixture first. The objects that are mapped to the 1 key do not obstruct the ray. This demonstrates the use of filtering.
Test Name	Delphi	C++	Description
Revolute			Demonstrates the use of a motor and shows collision behaviour. Use the following keys for additional actions: M: Toggle the motor on/off. L: Stop the revolving object.
RopeJoint			Shows how you can use a rope joint to stabilize a chain of bodies with a heavy payload. The rope joint simply prevents excessive stretching and has no other effect. If you disable the rope joint, you can see that the Box2D solver has trouble supporting heavy bodies with light bodies. This test also shows how you can use contact filtering. Filtering is configured so that the payload does not collide with the chain.
SensorTest			Demonstrates the use of sensor shapes. A sensor is a fixture that detects collision but does not produce a response.
Shape Editing			Shows basic shape behaviour. Use the C key to create a circle that overlaps with the square. Use the D key to destroy that circle.
Slider Crank			Shows a slider crank. This test is useful for understanding constraints.
Sphere Stack			A stack of spheres.
Theo Jansen's Walker			A simulation of a Jansen Walker robot. You can control the movement of the robot: A: Go left. S: Stop. D: Go right. M: Toggle motor on/off.
Tiles			Stress tests the dynamic tree broad-phase. It also shows that tile based collision is not smooth due to Box2D not knowing about adjacency.
TimeOfImpact			Shows time of impact for bodies.
Tumbler			A simulation of a tumbler.
Varying Friction			Demonstrates the behaviour of objects with different friction levels.
Varying Restitution			Shows the use of different restitution values. The restitution values determine how much an object bounces.
Vertical Stack			Simulates a stack of objects and shows how bullet collision affects those objects. Press the , key to fire a bullet.
Web			Demonstrates the behaviour of distance joints in response to body destruction and joint destruction.

Implementation

Main Form

The MainForm unit uses the Test and the DebugDraw units.

The MainForm unit implements the following event handlers:

• FormShow: Calls ResetView, DrawLayoutChanged, and TestChanged.
• FormCreate: Creates an instance of the test settings and calls LoadTests.
• FormDestroy: Disables the timer control and frees the TTest class instance.
• FormKeyDown: Processes the action according to the key that you press. This is the list of global actions that you can trigger:

  Key	Action
  (SHIFT +) LEFT	Moves the test stage to the left.
  (SHIFT +) RIGHT	Moves the test stage to the right.
  (SHIFT +) UP	Moves the test stage up.
  (SHIFT +) DOWN	Moves the test stage down.
  HOME	Resets the test stage position.
  SPACE	Fires a "bomb" into the test object.
  P	Pauses the test.
  R	Resets and restarts the test.
  ESC	Exits the application.

• FormKeyUp: Calls the KeyboardUp method of the TTest class.
• FormResize: Calls ResetView.
• Timer1Timer: Periodically refreshes the application.
• PaintBoxPaint: Fills the background of the canvas and displays the title of the test. If the options are enabled, it also displays the statistics and the profiling data.
• TestListChange: Occurs when you select a test from the list of tests. Calls TestChanged.
• PaintBoxMouseDown: Occurs when you press a mouse button in the PaintBox area. If you press Shift + left mouse button, this method calls the ShiftMouseDown method of the TTest class; otherwise, it calls the MouseDown method of the TTest class.
• PaintBoxMouseUp: Occurs when you release the mouse button in the calls the PaintBox area. This method calls the MouseUp method of the TTest class.
• PaintBoxMouseMove: Occurs when you release the mouse button in the calls the PaintBox area. This method calls the MouseUp method of the TTest class.
• DrawLayoutChanged: Occurs when you move the mouse inside the PaintBox area. This method calls the MouseMove method of the TTest class.
• PauseBtnClick: Pauses the test.
• QuiBtnClick: Exits the application.
• RestartBtnClick: Resets and restarts the test.
• SingleStepBtnClick: Advances the test execution by one step. Only works when the test is paused.

The MainForm unit also implements the following methods:

• LoadTests: Populates the list of tests with the available tests and selects the first test on the list.
• TestChanged: Frees the current test and creates a new test based on your selection.
• ResetView: Centers the camera view according to the form.

Test

The Test unit acts as a base class for all the tests. It defines the following records:

• Settings: The test settings. You can control some of the settings at run time using the check boxes.
• TestEntry: A record that the main unit uses to populate the list of tests.
• ContactPoint: Contains all information that the application uses to calculate contact points, contact normals and contact impulses between bodies.

The Test unit also defines the following classes:

• DestructionListener: The class that frees the references to joints and fixtures after they are destroyed.
• TTest: A class that handles contact information. All the tests inherit this class. This class implements the following methods:
  • Create: Creates the world and assigns the necessary listeners (destruction listener, contact listener).
  • Create: Creates the world and assigns the necessary listeners (destruction listener, contact listener).
  • Destroy: Destroys the world and frees the listeners that the constructor assigns.
  • DrawTitle: Draws the provided title text string.
  • Step: Advances the test execution. Handles the objects according to the test settings (draws shapes, joints, centers of masses, bounding boxes, statistics information).
  • Keyboard: A virtual method that the descendant classes use to handle keyboard input.
  • KeyboardUp: A virtual method that the descendant classes use to handle keyboard input.
  • ShiftMouseDown: Calls SpawnBomb.
  • MouseDown: Creates a small box shape at the location of the mouse pointer, if that location is inside of any body on the stage. Creates a joint that connects the created shape to your mouse pointer.
  • MouseUp: If a joint exists that connects the mouse pointer to a shape, this method destroys that joint. If a bomb is spawning (see SpawnBomb), this method calls CompleteBombSpawn.
  • MouseMove: If a joint exists that connects the mouse pointer to a shape (see MouseDown), this method extends that joint. Because this is a joint that acts as a spring, you can pull object on the stage by clicking on them with the mouse and moving the mouse.
  • LaunchBomb: Creates a circle shape that acts like a bullet and sets the velocity of that shape.
  • SpawnBomb: Sets the spawn point of the bomb and raises the flag that marks that a bomb spawn is in progress.
  • CompleteBombSpawn: Calculates the bomb speed and calls LaunchBomb.
  • JointDestroyed: A virtual method that the descendant classes use to handle the destruction of joints.
  • BeginContact: Occurs when two fixtures begin to touch.
  • EndContact: Occurs when two fixtures stop touching.
  • PreSolve: Occurs after a contact is updated. This allows you to inspect a contact before it goes to the solver.
  • PostSolve: Lets you inspect a contact after the solver is finished. This is useful for inspecting impulses.
  • ShiftOrigin: Changes the origin point for this world.

Debug Draw

A unit that implements the TDebugDraw class that provides methods for drawing and for debugging.

Uses

• FMX.Graphics.TCanvas

• System.Math.Vectors

See Also

• Box2D
• Using Box2D in Delphi Applications
• Using Box2D in C++Builder Applications

• Box2D User Manual