viktorljung
275 lines
10 KiB
Markdown
275 lines
10 KiB
Markdown
# Introduction
|
|
|
|
<img src="liquidfun-logo-square-small.png" alt="LiquidFun logo" style="float:right;"/>
|
|
|
|
[About](#about)<br/>
|
|
[Prerequisites](#pre)<br/>
|
|
[About this manual](#atm)<br/>
|
|
[Feedback and reporting bugs](#frb)<br/>
|
|
[Core concepts](#cc)<br/>
|
|
[Modules](#mo)<br/>
|
|
[Units](#un)<br/>
|
|
[Factories and definitions](#fd)<br/>
|
|
|
|
|
|
<a name="About"></a><br/>
|
|
|
|
## About
|
|
|
|
LiquidFun is based on Erin Catto's [Box2D library](http://www.box2d.org), which
|
|
provides 2D, rigid-body simulation in games. LiquidFun extends Box2D to provide
|
|
[particle physics and fluid dynamics](md__chapter11__particles.html).
|
|
|
|
Programmers can use LiquidFun in their games to make objects move in realistic
|
|
ways and make the game world more interactive. From the game engine's point of
|
|
view, a physics engine is just a system for procedural animation.
|
|
|
|
LiquidFun is written in portable C++. Most of the types defined in the engine
|
|
begin with the b2 prefix. Hopefully this is sufficient to avoid name clashing
|
|
with your game engine.
|
|
|
|
<a name="pre"></a><br/>
|
|
## Prerequisites
|
|
|
|
In this manual I'll assume you are familiar with basic physics concepts, such
|
|
as mass, force, torque, and impulses. If not, please first consult Google
|
|
search and Wikipedia.
|
|
|
|
LiquidFun is based on the Box2D library, which was created as part of a
|
|
physics tutorial at the Game Developer Conference. You can get these tutorials
|
|
from the download section of Box2D.org.
|
|
|
|
Since LiquidFun is written in C++, you are expected to be experienced in C++
|
|
programming. LiquidFun should not be your first C++ programming project! You
|
|
should be comfortable with compiling, linking, and debugging.
|
|
|
|
Caution
|
|
|
|
LiquidFun should not be your first C++ project. Please learn C++
|
|
programming, compiling, linking, and debugging before working with LiquidFun.
|
|
There are many resources for this on the net.
|
|
|
|
<a name="atm"></a><br/>
|
|
|
|
## About this manual
|
|
|
|
This manual covers the majority of the LiquidFun API. However, not every
|
|
aspect is covered. You are encouraged to look at the testbed included with
|
|
LiquidFun to learn more. Also, the LiquidFun code base has comments formatted
|
|
for Doxygen, so it is easy to create a hyper-linked API document.
|
|
|
|
This manual is only updated with new releases. The version in source control
|
|
is likely to be out of date.
|
|
|
|
<a name="frb"></a><br/>
|
|
## Feedback and Reporting Bugs
|
|
|
|
If you have a question or feedback about LiquidFun, please leave a comment in
|
|
the forum. This is also a great place for community discussion.
|
|
|
|
LiquidFun issues are tracked using a Google code project. This is a great way
|
|
to track issues and ensures that your issue will not be lost in the depths of
|
|
the forums.
|
|
|
|
Please file bugs and feature requests here:
|
|
[http://github.com/google/liquidfun/issues](http://github.com/google/liquidfun/issues)
|
|
|
|
You can help to ensure your issue gets fixed if you provide sufficient
|
|
detail. A testbed example that reproduces the problem is ideal. You can read
|
|
about the testbed later in this document.
|
|
|
|
<a name="cc"></a><br/>
|
|
## Core Concepts
|
|
|
|
LiquidFun works with several fundamental concepts and objects. We briefly
|
|
define these objects here and more details are given later in this
|
|
document.<br/>
|
|
<br/>
|
|
### shape
|
|
A shape is 2D geometrical object, such as a circle or polygon.<br/>
|
|
|
|
### rigid body
|
|
A chunk of matter that is so strong that the distance between any two bits of
|
|
matter on the chunk is constant. They are hard like a diamond. In the
|
|
following discussion we use body interchangeably with rigid body.<br/>
|
|
|
|
### fixture
|
|
A fixture binds a shape to a body and adds material properties such as
|
|
density, friction, and restitution. A fixture puts a shape into the collision
|
|
system (broad-phase) so that it can collide with other shapes.<br/>
|
|
|
|
### constraint
|
|
A constraint is a physical connection that removes degrees of freedom from
|
|
bodies. A 2D body has 3 degrees of freedom (two translation coordinates and
|
|
one rotation coordinate). If we take a body and pin it to the wall (like a
|
|
pendulum) we have constrained the body to the wall. At this point the body can
|
|
only rotate about the pin, so the constraint has removed 2 degrees of
|
|
freedom.<br/>
|
|
|
|
### contact constraint
|
|
A special constraint designed to prevent penetration of rigid bodies and to
|
|
simulate friction and restitution. You do not create contact constraints; they
|
|
are created automatically by LiquidFun.<br/>
|
|
|
|
### joint
|
|
This is a constraint used to hold two or more bodies together. LiquidFun
|
|
supports several joint types: revolute, prismatic, distance, and more. Some
|
|
joints may have limits and motors.<br/>
|
|
|
|
### joint limit
|
|
A joint limit restricts the range of motion of a joint. For example, the human
|
|
elbow only allows a certain range of angles.<br/>
|
|
|
|
### joint motor
|
|
A joint motor drives the motion of the connected bodies according to the
|
|
joint's degrees of freedom. For example, you can use a motor to drive the
|
|
rotation of an elbow.<br/>
|
|
|
|
### world
|
|
|
|
A physics world is a collection of bodies, fixtures, and constraints that
|
|
interact together. LiquidFun supports the creation of multiple worlds, but
|
|
this is usually not necessary or desirable.<br/>
|
|
|
|
### solver
|
|
The physics world has a solver that is used to advance time and to resolve
|
|
contact and joint constraints. The LiquidFun solver is a high performance
|
|
iterative solver that operates in order N time, where N is the number of
|
|
constraints.<br/>
|
|
|
|
### continuous collision
|
|
The solver advances bodies in time using discrete time steps. Without
|
|
intervention this can lead to tunneling.<br/>
|
|
<br/>
|
|
|
|
<img align="center" src="image_0.png" alt="Tunneling" height="293"
|
|
width="275"><br/>
|
|
|
|
LiquidFun contains specialized algorithms to deal with tunneling. First, the
|
|
collision algorithms can interpolate the motion of two bodies to find the
|
|
first time of impact (TOI). Second, there is a sub-stepping solver that moves
|
|
bodies to their first time of impact and then resolves the collision.
|
|
|
|
<a name="mo"></a><br/>
|
|
## Modules
|
|
|
|
LiquidFun is composed of three modules: Common, Collision, and Dynamics. The
|
|
Common module has code for allocation, math, and settings. The Collision
|
|
module defines shapes, a broad-phase, and collision functions/queries. Finally
|
|
the Dynamics module provides the simulation world, bodies, fixtures, and
|
|
joints.<br/>
|
|
<br/>
|
|
|
|
<img align="center" src="image_1.png" alt="Modules" height="229" width="217">
|
|
<a name="un"></a><br/>
|
|
## Units
|
|
|
|
LiquidFun works with floating point numbers and tolerances have to be used to
|
|
make LiquidFun perform well. These tolerances have been tuned to work well
|
|
with meters-kilogram-second (MKS) units. In particular, LiquidFun has been
|
|
tuned to work well with moving shapes between 0.1 and 10 meters. So this means
|
|
objects between soup cans and buses in size should work well. Static shapes
|
|
may be up to 50 meters long without trouble.
|
|
|
|
Being a 2D physics engine, it is tempting to use pixels as your units.
|
|
Unfortunately this will lead to a poor simulation and possibly weird behavior.
|
|
An object of length 200 pixels would be seen by LiquidFun as the size of a 45
|
|
story building.
|
|
|
|
Caution
|
|
|
|
LiquidFun is tuned for MKS units. Keep the size of moving objects
|
|
roughly between 0.1 and 10 meters. You'll need to use some scaling system when
|
|
you render your environment and actors. The LiquidFun testbed does this by
|
|
using an OpenGL viewport transform. DO NOT USE PIXELS.
|
|
|
|
|
|
|
|
It is best to think of LiquidFun bodies as moving billboards upon which you
|
|
attach your artwork. The billboard may move in a unit system of meters, but
|
|
you can convert that to pixel coordinates with a simple scaling factor. You
|
|
can then use those pixel coordinates to place your sprites, etc. You can also
|
|
account for flipped coordinate axes.
|
|
|
|
LiquidFun uses radians for angles. The body rotation is stored in radians and
|
|
may grow unbounded. Consider normalizing the angle of your bodies if the
|
|
magnitude of the angle becomes too large (use b2Body::SetAngle).
|
|
|
|
Caution
|
|
|
|
LiquidFun uses radians, not degrees.
|
|
|
|
<a name="fd"></a><br/>
|
|
## Factories and Definitions
|
|
|
|
Fast memory management plays a central role in the design of the LiquidFun
|
|
API. So when you create a b2Body or a b2Joint, you need to call the factory
|
|
functions on b2World. You should never try to allocate these types in another
|
|
manner.
|
|
|
|
There are creation functions:
|
|
|
|
`b2Body* b2World::CreateBody(const b2BodyDef* def)`<br/>
|
|
`b2Joint* b2World::CreateJoint(const b2JointDef* def)`<br/>
|
|
`And there are corresponding destruction functions:`<br/>
|
|
`void b2World::DestroyBody(b2Body* body)`<br/>
|
|
`void b2World::DestroyJoint(b2Joint* joint)`<br/>
|
|
|
|
When you create a body or joint, you need to provide a definition. These
|
|
definitions contain all the information needed to build the body or joint. By
|
|
using this approach we can prevent construction errors, keep the number of
|
|
function parameters small, provide sensible defaults, and reduce the number of
|
|
accessors.
|
|
|
|
Since fixtures (shapes) must be parented to a body, they are created and
|
|
destroyed using a factory method on b2Body:
|
|
|
|
`b2Fixture* b2Body::CreateFixture(const b2FixtureDef*
|
|
def)`<br/>
|
|
`void b2Body::DestroyFixture(b2Fixture* fixture)`<br/>
|
|
|
|
There is also shortcut to create a fixture directly from the shape and density.
|
|
|
|
`b2Fixture* b2Body::CreateFixture(const b2Shape* shape,
|
|
float32 density)`<br/>
|
|
|
|
Factories do not retain references to the definitions. So you can create
|
|
definitions on the stack and keep them in temporary resources.
|
|
|
|
*This content is licensed under
|
|
[Creative Commons Attribution 4.0](http://creativecommons.org/licenses/by/4.0/legalcode).
|
|
For details and restrictions, please see the
|
|
[Content License](md__content_license.html).*
|
|
|
|
|
|
[ ][Chapter02]
|
|
[ ][Chapter03]
|
|
[ ][Chapter04]
|
|
[ ][Chapter05]
|
|
[ ][Chapter06]
|
|
[ ][Chapter07]
|
|
[ ][Chapter08]
|
|
[ ][Chapter09]
|
|
[ ][Chapter10]
|
|
[ ][Chapter11]
|
|
[ ][Chapter12]
|
|
[ ][Chapter13]
|
|
[ ][Chapter14]
|
|
[ ][Chapter15]
|
|
|
|
[Chapter02]: md__chapter02__hello__box2_d.html
|
|
[Chapter03]: md__chapter03__common.html
|
|
[Chapter04]: md__chapter04__collision__module.html
|
|
[Chapter05]: md__chapter05__dynamics__module.html
|
|
[Chapter06]: md__chapter06__bodies.html
|
|
[Chapter07]: md__chapter07__fixtures.html
|
|
[Chapter08]: md__chapter08__joints.html
|
|
[Chapter09]: md__chapter09__contacts.html
|
|
[Chapter10]: md__chapter10__world.html
|
|
[Chapter11]: md__chapter11__particles.html
|
|
[Chapter12]: md__chapter12__loose__ends.html
|
|
[Chapter13]: md__chapter13__debug__drawing.html
|
|
[Chapter14]: md__chapter14__limitations.html
|
|
[Chapter15]: md__chapter15__references.html
|
|
|