.. contents:: Table of Contents

.. _box2LiquidFun:
.. _liquidfun:

Module box2d LiquidFun
======================


`LiquidFun <https://github.com/google/liquidfun>`__ is a 2D rigid-body and fluid simulation ``C++`` library for games based upon `Box 2D <http://box2d.org>`__ . 
It provides support for procedural animation of physical bodies to make objects move and interact in realistic ways.

Discuss `LiquidFun <https://github.com/google/liquidfun>`__ with other developers and users on the mailing list of `LiquidFun`.

Report issues on the issues tracker or post your questions to `stackoverflow <https://stackoverflow.com/search?q=liquidfun>`__ tagged with "liquidfun".


Please take a look at `LiquidFun Programmer's Guide <https://google.github.io/liquidfun/Programmers-Guide/html/md__chapter11__particles.html>`__ which is available for C++ but also applies to this wrapper over `LUA <https://www.lua.org>`__ 

Some implementation in this wrapper is slightly different from the original version of ``C++``.
For example, is not available the manipulation of particle buffer directly through ``Lua``.

Next one example of what can be done with this feature:

.. figure:: _static/fluid-showcase.gif
   :align: center
   :figclass: align-center

   Fluid particle showcase


box2d LiquidFun Methods
-----------------------

The box2d liquid fun has same methods as in :ref:`box2d <box2d>` .

.. _createFluid:

LiquidFun createFluid
^^^^^^^^^^^^^^^^^^^^^

The implementation of :ref:`LiquidFun <box2LiquidFun>` is a bit different from others object in this engine.

First, a :ref:`renderizable <renderizable>` is not available for the fluid, therefore, you do not need to create a separated object which represent the fluid.
All you need is to configure a texture plus some parameters and the fluid is created and the engine will take care of render it.

Two tables are the arguments needed for :ref:`creating a fluid <createFluid>` , :guilabel:`initial physical format`, and :guilabel:`options`.

Next is presented the table definition for the :guilabel:`initial physical format` (which could be an array as well):

    +---------------+----------------+----------------------------+
    | | type /      | | sub table    | | values                   |
    | | name        | | information  | | information              |
    +===============+================+============================+
    | ``rectangle`` | | ``center``   | | {``x, y, z``}            |
    |               | | ``width``    | | ``value``                |
    |               | | ``height``   | | ``value``                |
    +---------------+----------------+----------------------------+
    |               | | ``a``        | | {``x, y, z``}            |
    |  ``triangle`` | | ``b``        | | {``x, y, z``}            |
    |               | | ``c``        | | {``x, y, z``}            |
    +---------------+----------------+----------------------------+
    |               | | ``center``   | | {``x, y, z``}            |
    |  ``circle``   | | ``ray``      | | ``value``                |
    +---------------+----------------+----------------------------+

e.g. single table:

.. code-block:: lua

    {
        type    = 'rectangle',
        center  = {x=0,y=0,z=0},
        width   = 600,
        height  = 400,
    }

    {
        type    = 'circle',
        center  = {x=0,y=0,z=0},
        ray     = 200,
    }

e.g. array table:

.. code-block:: lua

    {
        {
            type    = 'rectangle',
            center  = {x=0,y=0,z=0},
            width   = 600,
            height  = 400,
        },

        {
            type    = 'circle',
            center  = {x=0,y=0,z=0},
            ray     = 200,
        }
    }

And next is presented the definition for the :guilabel:`options` table:

    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | | identifier /        | | Type         | | Default               | | values                                                                         |
    | | name                | | value        | | value                 | | information                                                                    |
    +=======================+================+=========================+==================================================================================+
    |  ``position``         |   ``table``    |   {``x=0,y=0,z=0``}     | | Initial position of the origin of center of particle                           |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    |  ``scale``            |   ``table``    |   {``x=1,y=1``}         | | Initial scale of particle system.                                              |
    |                       |                |                         | | This reflect in the size of shape.                                             |
    |                       |                |                         | | E.g.: shape circle ``ray=5``                                                   |
    |                       |                |                         | | scale ``{x=2,y=2}`` => ``ray=10``                                              |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    |  ``color``            |   ``table``    |   {``r=1,g=1,b=1,a=1``} | | Color to be applied to the fluid shader                                        |
    |                       |                |                         | | If not present the shader will not contain particle on it                      |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``texture``           |   ``string``   |   ``#AAFF00FF``         | | Path to the texture filename                                                   |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    |  ``is2dScreen``       |   ``boolean``  |   ``false``             | | ``true``  The fluid is 2d Screen coordinate                                    |
    |                       |                |                         | | ``false``  The fluid is 2d World coordinate                                    |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    |  ``is3d``             |   ``boolean``  |   ``false``             | | ``true``   The fluid is 3d World coordinate                                    |
    |                       |                |                         | | ``false``  The fluid is 2d World/Screen coordinate                             |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    |  ``segmented``        |   ``boolean``  |   ``false``             | | ``true`` The texture is mapped to the whole physics                            |
    |                       |                |                         | | ``false``  The texture is mapped to a single particle                          |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``radius``            |   ``number``   |   ``0.5``               | | radius of each particle (physics)                                              |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``radiusScale``       |   ``number``   |   ``1.0``               | | ``1.0`` means no scale.                                                        |
    |                       |                |                         | | This scale is only for the particle (not the physics)                          |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``damping``           |   ``number``   |   ``0.5``               | | Reduces velocity along the collision normal                                    |
    |                       |                |                         | | Smaller value reduces less                                                     |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``stride``            |   ``number``   |   ``0``                 | | The interval of particles in the shape.                                        |
    |                       |                |                         | | If ``0``, ``0.75`` * particle diameter is used                                 |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``strength``          |   ``number``   |   ``1.0``               | | The strength of cohesion among the particles                                   |
    |                       |                |                         | | in a group with flag elastic or spring                                         |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``lifetime``          |   ``number``   |   ``0.0``               | | Lifetime of the particle in seconds.                                           |
    |                       |                |                         | | A value <= ``0.0`` indicates an infinite life time.                            |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``angle``             |   ``number``   |   ``0.0``               | | The initial rotational angle of the particle.                                  |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``angularVelocity``   |   ``number``   |   ``0.0``               | | The initial angular velocity of particle                                       |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    |  ``linearVelocity``   |   ``table``    |   {``x=0,y=0``}         | | Initial Linear velocity of particle system                                     |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``blend``             |   ``string``   |   ``one``               | | Blend options. See :ref:`blend state <blend_state>`                            |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``operation``         |   ``string``   |   ``add``               | | Blend options. See :ref:`blend operation <blend_operation>`                    |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``flags``             |   ``string``   |   ``water``             | | Single flag or combined. See :ref:`fluid flags <fluid_flag>`                   |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+
    | ``groupFlags``        |   ``string``   |  ``solidParticleGroup`` | | Single group flag or combined. See :ref:`fluid group flags <fluid_group_flag>` |
    +-----------------------+----------------+-------------------------+----------------------------------------------------------------------------------+

For the next examples, it will be used this texture:

.. figure:: _static/fluid_particle.png
   :align: center
   :width: 100
   :height: 100
   :figclass: align-center

   Texture for fluid particle

:download:`download fluid_particle.png <_static/fluid_particle.png>`.

   *Example:*

.. code-block:: lua
   :emphasize-lines: 21,27

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
        {   type   = 'rectangle',
            center = {x=0,y=0,z=0},
            width  = 200, height = 400,
        },
        {   texture     ='fluid_particle.png',
            color       = {r = 0.0, g = 0.0, b =1.0},
            radiusScale = 2.0,
            flags       = "water",
            groupFlags  = {"solidParticleGroup"},
        })

.. figure:: _static/fluid-1.gif
   :align: center
   :figclass: align-center

   Basic example fluid box2d:LiquidFun

.. Tip::

    | In this example, we are appling the blue color to the particle. 
    | The texture is used as reference to render (shape of particle).
    | The alpha is ignored because there is no alpha in the texture.


*Example 2 no color:*

.. code-block:: lua
   :emphasize-lines: 21

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
        {   type   = 'rectangle',    
            center = {x=0,y=0,z=0},
            width  = 200, height = 400,
        },
        {   texture     ='fluid_particle.png',
            radiusScale = 2.0,
            flags       = "water",
            groupFlags  = {"solidParticleGroup"},
        })

.. figure:: _static/fluid-2.gif
   :align: center
   :figclass: align-center

   Basic example no color to texture fluid box2d:LiquidFun


.. Note::

    | When no color is applied, there is no effect to color methods :guilabel:`getColor/setColor` anymore.



*Example 3 array of physical shape:*

.. code-block:: lua
   :emphasize-lines: 23,28

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
    {
        {   type   = 'rectangle',
            center = {x=-50,y=0,z=0},
            width  = 50,
            height = 50,
        },
        {   type   = 'circle',
            center = {x=50,y=30,z=0},
            ray    = 50,
        },
    },
    {   texture     ='fluid_particle.png',
        flags       = "powder",
        groupFlags  = {"solidParticleGroup"},
    })


.. figure:: _static/fluid-array-of-shape-1.gif
   :align: center
   :figclass: align-center

   Basic example array of shape


.. _fluid_flag:

LiquidFun flags
^^^^^^^^^^^^^^^

The particle flag can be combined as array.

    +--------------------------+-----------------------------------------------+---------------+
    | | name                   | | information                                 |  Compatible   |
    +==========================+===============================================+===============+
    | ``water``                | | Water particle                              |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``zombie``               | | Removed after next simulation step          |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``wall``                 | | Zero velocity                               |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``spring``               | | With restitution from stretching            |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``elastic``              | | With restitution from deformation           |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``viscous``              | | With viscosity                              |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``powder``               | | Without isotropic pressure                  |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``tensile``              | | With surface tension                        |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``colorMixing``          | | Mix color between contacting particles      |  No           |
    +--------------------------+-----------------------------------------------+---------------+
    | ``destructionListener``  | | Call b2DestructionListener on destruction   |  No           |
    +--------------------------+-----------------------------------------------+---------------+
    | ``barrier``              | | Prevents other particles from leaking       |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``staticPressure``       | | Less compressibility                        |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``reactive``             | | Makes pairs or triads with other particles  |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    | ``repulsive``            | | With high repulsive force                   |  Yes          |
    +--------------------------+-----------------------------------------------+---------------+
    

LiquidFun group flags
^^^^^^^^^^^^^^^^^^^^^

.. _fluid_group_flag:

The particle group flag can be combined as array.

    +-----------------------------------+-----------------------------------------------+---------------+
    | | name                            | | information                                 |  Compatible   |
    +===================================+===============================================+===============+
    | ``solidParticleGroup``            | | Prevents overlapping or leaking             |  Yes          |
    +-----------------------------------+-----------------------------------------------+---------------+
    | ``rigidParticleGroup``            | | Keeps its shape                             |  Yes          |
    +-----------------------------------+-----------------------------------------------+---------------+
    | ``particleGroupCanBeEmpty``       | | Won't be destroyed if it gets empty         |  Yes          |
    +-----------------------------------+-----------------------------------------------+---------------+
    | ``particleGroupWillBeDestroyed``  | | Will be destroyed on next simulation step   |  Yes          |
    +-----------------------------------+-----------------------------------------------+---------------+
    | ``particleGroupNeedsUpdateDepth`` | | Updates depth data on next simulation step  |  No           |
    +-----------------------------------+-----------------------------------------------+---------------+

LiquidFun flags examples
^^^^^^^^^^^^^^^^^^^^^^^^

To exemplify how to differ the flags, see the examples bellow:

For the fluid, we will use this texture:

.. figure:: _static/fluid_particle.png
   :align: center
   :width: 100
   :height: 100
   :figclass: align-center

   Texture for fluid particle


   *Code:*
.. code-block:: lua
   :emphasize-lines: 28

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
        {   type   = 'rectangle',
            center = {x=0,y=0,z=0},
            width  = 200,
            height = 200,
        },
        {   texture     ='fluid_particle.png',
            flags       = "water",
            groupFlags  = {"solidParticleGroup"},
        })

.. figure:: _static/fluid-3.gif
   :align: center
   :figclass: align-center

   Example flags "water"


.. code-block:: lua
   :emphasize-lines: 28

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
        {   type   = 'rectangle',
            center = {x=0,y=0,z=0},
            width  = 200,
            height = 200,
        },
        {   texture     ='fluid_particle.png',
            flags       = {"water","staticPressure"},
            groupFlags  = {"solidParticleGroup"},
        })

.. figure:: _static/fluid-4.gif
   :align: center
   :figclass: align-center

   Example flags "water|staticPressure"


.. code-block:: lua
   :emphasize-lines: 28

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
        {   type   = 'rectangle',
            center = {x=0,y=0,z=0},
            width  = 200,
            height = 200,
        },
        {   texture     ='fluid_particle.png',
            flags       = "elastic",
            groupFlags  = {"solidParticleGroup"},
        })

.. figure:: _static/fluid-5.gif
   :align: center
   :figclass: align-center

   Example flags "elastic"


.. code-block:: lua
   :emphasize-lines: 28

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
        {   type   = 'rectangle',
            center = {x=0,y=0,z=0},
            width  = 200,
            height = 200,
        },
        {   texture     ='fluid_particle.png',
            flags       = "viscous",
            groupFlags  = {"solidParticleGroup"},
        })

.. figure:: _static/fluid-6.gif
   :align: center
   :figclass: align-center

   Example flags "viscous"


.. code-block:: lua
   :emphasize-lines: 28

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
        {   type   = 'rectangle',
            center = {x=0,y=0,z=0},
            width  = 200,
            height = 200,
        },
        {   texture     ='fluid_particle.png',
            flags       = "powder",
            groupFlags  = {"solidParticleGroup"},
        })

.. figure:: _static/fluid-7.gif
   :align: center
   :figclass: align-center

   Example flags "powder"


LiquidFun methods
-----------------

LiquidFun add particles
^^^^^^^^^^^^^^^^^^^^^^^

.. data:: add(table shape,table infoPosScale)

   | Add particles given the shape. See :guilabel:`initial physical format`.
   |
   | Info position and scale is defined as:

    +---------------+------------------------+
    | | field       | | Information          |
    +===============+========================+
    | | ``x``       | | Position  ``x``      |
    | | ``y``       | | Position  ``y``      |
    | | ``z``       | | Position  ``z``      |
    | | ``sx``      | | Scale  ``x``         |
    | | ``sy``      | | Scale  ``y``         |
    | | ``sz``      | | Scale  ``z``         |
    +---------------+------------------------+


   :param table: **shape**   physical format.
   :param table: **info position and scale**.
   :return: ``number`` *particles added*.

   *Example:*
.. code-block:: lua
   :emphasize-lines: 47

    require "box2dLiquidFun"
    mbm.setColor(0.6,0.6,0.6)

    tPhysic = box2dLiquidFun:new()

    tShapeGround    = shape:new('2dw',0,-200)
    tShapeLeftWall  = shape:new('2dw',-200,0)
    tShapeRightWall = shape:new('2dw',200,0)
    tShapeUpWall    = shape:new('2dw',0,200)

    tShapeGround:create('rectangle',400,20)
    tShapeRightWall:create('rectangle',20,400)
    tShapeLeftWall:create('rectangle',20,400)
    tShapeUpWall:create('rectangle',400,20)

    tPhysic:addStaticBody(tShapeGround)
    tPhysic:addStaticBody(tShapeRightWall)
    tPhysic:addStaticBody(tShapeLeftWall)
    tPhysic:addStaticBody(tShapeUpWall)

    tFluid = tPhysic:createFluid(
        {   type   = 'rectangle',
            center = {x=0,y=0,z=0},
            width  = 200,
            height = 200,
        },
        {   texture     ='fluid_particle.png',
            flags       = "powder",
            groupFlags  = {"solidParticleGroup"},
        })


    function onTouchDown(key,x,y)
        local x,y = mbm.to2dw(x,y)
        local tCircle = 
        {
            type = 'circle',
            ray  = 20,
        }
        local infoPosScale = 
        {
            x = x,
            y = y,
            sx = 1,
            sy = 1,
        }
        local iTotalParticleAdded = tFluid:add(tCircle,infoPosScale)
        print('Total particle added:',iTotalParticleAdded)

    end

.. figure:: _static/fluid-add-particle-shape.gif
   :align: center
   :figclass: align-center

   Example adding particle

LiquidFun particle count
^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: getParticleCount()

   Get the number of particles.

    :return: ``number`` *particles count*.

   *Example:*
.. code-block:: lua
   :emphasize-lines: 1

    local iTotalParticle = tFluid:getParticleCount()
    print(iTotalParticle)

.. data:: getMaxParticleCount()

   Get the maximum number of particles.

   :return: ``number`` *maximum* number of particles.

   *Example:*
.. code-block:: lua
   :emphasize-lines: 1

    local iMaxParticle = tFluid:getMaxParticleCount()
    print(iMaxParticle)


.. data:: setMaxParticleCount(number max)

   | Set the maximum number of particles.
   | By default, there is no maximum. The particle buffers can continue to
   | grow while b2World's block allocator still has memory.

   :param number: **max** maximum number of particles.

   *Example:*
.. code-block:: lua
   :emphasize-lines: 1

    tFluid:setMaxParticleCount(500)


LiquidFun particle color
^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: getColor()

   | Get the particle's color.
   | It only has effect when created with color option.

   :return: ``number`` *red*, ``number`` *green*, ``number`` *blue*, ``number`` *alpha* - color of fluid.

   *Example:*
.. code-block:: lua

    local r,g,b,a = tFluid:getColor()

.. data:: setColor(number red, number green, number blue, number * alpha)

   | Set the particle's color.
   | It only has effect when created with color option.

   :param number: **red**   color.
   :param number: **green** color.
   :param number: **blue**  color.
   :param number: **alpha** color (optional).

   *Example:*
.. code-block:: lua

    local r,g,b,a = 1.0, 0.4, 0.3, 0.9
    tFluid:setColor(r,g,b,a)

.. data:: setColor(table color)
   :noindex:

   | Set the particle's color.
   | It only has effect when created with color option.

   :param table: **color**   ``{r,g,b,a}``.
   
   *Example:*
.. code-block:: lua

    local tColor = {r=1.0, g=1.0, b=0.4, a=0.3}
    tFluid:setColor(tColor)


LiquidFun particle pause
^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: setPaused(boolean paused)

   | Pause or unpause the particle system. 
   | When paused, b2World::Step() skips over this particle system. 
   | All b2ParticleSystem function calls still work.

   :param boolean: **paused** value.
   
   *Example:*
.. code-block:: lua

    tFluid:setPaused(true)


LiquidFun particle density
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: getDensity()

   | Get the particle density.
   
   :return: ``number`` *density*

   *Example:*
.. code-block:: lua

    local density = tFluid:getDensity()

.. data:: setDensity(number density)

   | Change the particle density.
   | Particle density affects the mass of the particles, which in turn
   | affects how the particles interact with b2Bodies. Note that the density
   | does not affect how the particles interact with each other.

   :param number: **density**
   
   *Example:*
.. code-block:: lua

    local density = tFluid:getDensity()
    tFluid:setDensity(density * 2.0)


LiquidFun particle gravity scale
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: getGravityScale()

   | Get the particle gravity scale.
   
   :return: ``number`` *gravity scale*

   *Example:*
.. code-block:: lua

    local gravity_scale = tFluid:getGravityScale()


.. data:: setGravityScale(number gravity_scale)

   | Change the particle gravity scale. 
   | Adjusts the effect of the global gravity vector on particles.

   :param number: **gravity scale**
   
   *Example:*
.. code-block:: lua

    local gravity_scale = tFluid:getGravityScale()
    tFluid:setGravityScale(gravity_scale * 2.0)


LiquidFun particle damping
^^^^^^^^^^^^^^^^^^^^^^^^^^


.. data:: getDamping()

   | Get damping for particles
   
   :return: ``number`` *damping*

   *Example:*
.. code-block:: lua

    local damping = tFluid:getDamping()

.. data:: setDamping(number damping)

   | Damping is used to reduce the velocity of particles. 
   | The damping parameter can be larger than ``1.0`` but the damping 
   | effect becomes sensitive to the time step when the damping parameter is large.

   :param number: **damping**
   
   *Example:*
.. code-block:: lua

    tFluid:setDamping(0.5)


LiquidFun particle static pressure
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    | Change the number of iterations when calculating the static pressure of
    | particles. By default, ``8`` iterations. You can reduce the number of
    | iterations down to ``1`` in some situations, but this may cause
    | instabilities when many particles come together. If you see particles
    | popping away from each other like popcorn, you may have to increase the
    | number of iterations.
    | For a description of static pressure, see
    | `Static pressure in fluid dynamics <http://en.wikipedia.org/wiki/Static_pressure#Static_pressure_in_fluid_dynamics>`__ 

.. data:: getStaticPressureIterations()

   | Get the number of iterations for static pressure of particles.
   
   :return: ``number`` *iterations for static pressure of particles*

   *Example:*
.. code-block:: lua

    local iterations = tFluid:getStaticPressureIterations()

.. data:: setStaticPressureIterations(number iterations)

   :param number: **iterations**
   
   *Example:*
.. code-block:: lua

    tFluid:setStaticPressureIterations(3)


LiquidFun particle radius
^^^^^^^^^^^^^^^^^^^^^^^^^

 | The radius is defined in the moment of creation of fluid.

.. data:: getRadius()

   | Get the particle radius.
   
   :return: ``number`` *particle radius*

   *Example:*
.. code-block:: lua

    local radius = tFluid:getRadius()


LiquidFun particle life time
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   | All particules are created with ``0.0`` lifetime (infinite lifetime).
   | A value > ``0.0`` is returned if the particle is scheduled to be
   | destroyed in the future, values <= ``0.0`` indicate the particle has an
   | infinite lifetime.

.. data:: getParticleLifetime(number index)

   | Get the lifetime (in seconds) of a particle relative to the current time.
   
   :param number: **index** of particle (1 based).
   :return: ``number`` *lifetime*

   *Example:*
.. code-block:: lua

    local index = 1 -- first particle in the system
    local lifetime = tFluid:getParticleLifetime(index)


.. data:: setParticleLifetime(number index, number lifetime)

    | Set the lifetime (in seconds) of a particle relative to the current time.
    | A lifetime of less than or equal to 0.0f results in the particle
    | living forever until it's manually destroyed by the application.

   :param number: **index** of particle (1 based).
   :param number: **lifetime** of particle in seconds.
   
   *Example:*
.. code-block:: lua

    local index = 1 -- first particle in the system
    local lifetime = 2.0
    tFluid:setParticleLifetime(index,lifetime)


LiquidFun destroy particles
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: destroyParticle(number index)

    | Destroy a particle.
    | The particle is removed after the next simulation step (see b2World::Step()).

   :param number: **index** of particle (1 based).
   
   *Example:*
.. code-block:: lua

    local index = 1 -- first particle in the system
    tFluid:destroyParticle(index)


.. data:: destroyParticlesInShape(table shape)

    | Destroy particles inside a shape without enabling the destruction callback for destroyed particles. 
    | This function is locked during callbacks. 
    | For more information see DestroyParticleInShape(const b2Shape&, const b2Transform&,bool).

   :param table: **shape**  which encloses particles that should be destroyed.
   
   *Example:*
.. code-block:: lua
   :emphasize-lines: 5,10,17

    local tShapeRect     = {type   = 'rectangle', 
                            width  = 100, 
                            height = 100, 
                            x = 0, y =0, angle = 0}
    tFluid:destroyParticlesInShape(tShapeRect)

    local tShapeCircle   = {type = 'circle', 
                            ray  = 30, 
                            x = 0, y =0, angle = 0}
    tFluid:destroyParticlesInShape(tShapeCircle)

    local tShapeTriangle = {type = 'triangle', 
                            a = {x = -20, y = -20},
                            b = {x =  20, y = -20}, 
                            c = {x =  20, y =  20},   
                            x = 0, y =0, angle = 0}
    tFluid:destroyParticlesInShape(tShapeTriangle)



.. Note:: The position ``x``, ``y`` and the ``angle`` are available for any type of shape.

.. data:: destroyParticlesInShape(renderizable body)
   :noindex:

    | Destroy particles inside a shape without enabling the destruction callback for destroyed particles. 
    | This function is locked during callbacks. 
    | For more information see DestroyParticleInShape(const b2Shape&, const b2Transform&,bool).

   :param renderizable: :ref:`body <renderizable>`  which encloses particles that should be destroyed.
   
   *Example:*
.. code-block:: lua

    local tObj -- previously loaded
    tFluid:destroyParticlesInShape(tObj)


LiquidFun particles impulse
^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. data:: particleApplyLinearImpulse([table | array] tImpulse)

    | Apply an impulse to one particle. This immediately modifies the velocity. Similar to b2Body::applyLinearImpulse.

   :param table: ``{x,y,index}`` the impulse info for each particle (or array).
   
   *Example:*
.. code-block:: lua

    local tImpulse = {x = 100, y = 25, index = 1}
    tFluid:particleApplyLinearImpulse(tImpulse)

    local tArraysImpulse = {{x = 100, y = 25, index = 1},{x = 100, y = 25, index = 2},{x = 100, y = 25, index = 3}}
    tFluid:particleApplyLinearImpulse(tArraysImpulse)


.. data:: applyLinearImpulse(number firstIndex, number lastIndex, number x, number y)

    | Apply an impulse to all particles between 'firstIndex' and 'lastIndex'.
    | This immediately modifies the velocity. 
    | Note that the impulse is applied to the total mass of all particles. So, 
    | calling particleApplyLinearImpulse(0, impulse) and particleApplyLinearImpulse(1, impulse) 
    | will impart twice as much velocity as calling just applyLinearImpulse(0, 1, impulse).

   :param number: ``firstIndex``  (1 based)
   :param number: ``lastIndex``  (1 based)
   :param number: ``x`` impulse
   :param number: ``y`` impulse
   
   *Example:*
.. code-block:: lua

    local firstIndex = 1
    local lastIndex  = 250
    local x,y = 100, 25
    tFluid:applyLinearImpulse(firstIndex,lastIndex,x,y)


LiquidFun particles force
^^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: particleApplyForce([table | array] tForce)

    | Apply a force to the center of a particle.
    | The world force vector is usually in Newtons (N).

   :param table: ``{x,y,index}`` the force info for each particle (or array).
   
   *Example:*
.. code-block:: lua

    local tForce = {x = 50, y = 33, index = 1}
    tFluid:particleApplyForce(tForce)

    local tArrayForce = {{x = 50, y = 33, index = 1},{x = 50, y = 33, index = 2},{x = 50, y = 33, index = 3}}
    tFluid:particleApplyForce(tArrayForce)

.. data:: applyForce(number firstIndex, number lastIndex, number x, number y)

    | Distribute a force across several particles.
    | The particles must not be wall particles.
    | Note that the force is distributed across all the particles, so calling
    | this function for indices 0..N is not the same as
    | calling particleApplyForce(i, force) for i in 0..N.

   :param number: ``firstIndex``  (1 based)
   :param number: ``lastIndex``  (1 based)
   :param number: ``x`` force
   :param number: ``y`` force
   
   *Example:*
.. code-block:: lua

    local firstIndex = 1
    local lastIndex  = 300
    local fx,fy = 50, 33
    tFluid:applyForce(firstIndex,lastIndex,fx,fy)


LiquidFun particles colision
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: queryAABB(number lowerBound_x,number lowerBound_y,number upperBound_x,number upperBound_y,function onQueryAABBB)

   Perform a AABB algorithm collision for all objects given the bound.

   It considers :ref:`box2d <box2d>` :ref:`scale <box2d_Scale>`.

   The callback is called in case of collision.

   It has to have the following signature:

.. code-block:: lua

    function onQueryAABBB(tFluid, indexParticle)

    end

*Example:*

.. code-block:: lua

    -- TODO



.. data:: queryShapeAABB(table shape,function onQueryShapeAABB)

   Perform a AABB algorithm collision for all objects given the shape.

   It considers :ref:`box2d <box2d>` :ref:`scale <box2d_Scale>`.

   The callback is called in case of collision.

   It has to have the following signature:

.. code-block:: lua

    function onQueryShapeAABB(tFluid, indexParticle)

    end


 
The shape is defined as:

    +---------------+----------------+----------------------------+
    | | type /      | | field        | | values                   |
    | | name        | | name         | | information              |
    +===============+================+============================+
    | ``rectangle`` | | ``width``    | | ``value``                |
    |               | | ``height``   | | ``value``                |
    |               | | ``x``        | | ``x position``           |
    |               | | ``y``        | | ``y position``           |
    |               | | ``angle``    | | ``radian``               |
    +---------------+----------------+----------------------------+
    |  ``triangle`` | | ``a``        | | {``x, y``}               |
    |               | | ``b``        | | {``x, y``}               |
    |               | | ``c``        | | {``x, y``}               |
    |               | | ``x``        | | ``x position``           |
    |               | | ``y``        | | ``y position``           |
    |               | | ``angle``    | | ``radian``               |
    +---------------+----------------+----------------------------+
    |  ``circle``   | | ``ray``      | | ``value``                |
    |               | | ``x``        | | ``x position``           |
    |               | | ``y``        | | ``y position``           |
    |               | | ``angle``    | | ``radian``               |
    +---------------+----------------+----------------------------+

*Example:*

.. code-block:: lua

    -- TODO



.. data:: queryShapeAABB(table renderizable,function onQueryShapeAABB)
   :noindex:

   Perform a AABB algorithm collision for all objects given the :ref:`renderizable <renderizable>`.

   It considers :ref:`box2d <box2d>` :ref:`scale <box2d_Scale>`.

   The callback is called in case of collision.

   It has to have the following signature:

.. code-block:: lua

    function onQueryShapeAABB(tFluid, indexParticle)

    end

*Example:*

.. code-block:: lua

    -- TODO


LiquidFun particles compute bounds
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: computeAABB(number lowerBound_x,number lowerBound_y,number upperBound_x,number upperBound_y)

   | Compute the axis-aligned bounding box for all particles contained within this particle system.
   | Returns the axis-aligned bounding box of the system.
   
   :param number: **lowerBound_x**
   :param number: **lowerBound_y**
   :param number: **upperBound_x**
   :param number: **upperBound_y**
   :return: ``table`` ``{lowerBound = {x,y},upperBound = {x,y}}``

   *Example:*
.. code-block:: lua

    local lowerBound_x = 0
    local lowerBound_y = 0
    local upperBound_x = 100
    local upperBound_y = 100
    local tBound = tFluid:computeAABB(lowerBound_x,lowerBound_y,upperBound_x,upperBound_y)
    print(tBound.lowerBound.x)
    print(tBound.lowerBound.y)
    print(tBound.upperBound.x)
    print(tBound.upperBound.y)



LiquidFun particles ray cast
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. data:: rayCast(number x_start,number y_start, number x_end,number y_end,function onRayCastCallBack)


   :param number: **x** start point of the ray-cast.
   :param number: **y** start point of the ray-cast.
   :param number: **x** end point of the ray-cast.
   :param number: **y** end point of the ray-cast.
   :param function: **call back** function ray-cast.

It considers :ref:`box2d <box2d>` :ref:`scale <box2d_Scale>`.


.. code-block:: lua

    --Ray cast callback
    function onRayCast(index,x,y,nx,ny,fraction)

        message = string.format('Particle: %d, at x:%g y:%g   normal nx:%g ny:%g    fraction:%g',index,x,y,nx,ny,fraction)
        print(message)
        return fraction --if you return 0 it means end of ray-cast
    end

LiquidFun getVersion
^^^^^^^^^^^^^^^^^^^^

.. data:: getVersion()

   Get the current version of :ref:`box2d <box2d>` + :ref:`LiquidFun <LiquidFun>`.

   *Example:*
.. code-block:: lua
   :emphasize-lines: 2

    require "box2dLiquidFun"
    version = box2d:getVersion()
    print(version)

The output will be "x.x.x" for the :ref:`box2d <box2d>` version followed by :ref:`LiquidFun <box2LiquidFun>` x.x.x version.

e.g.: ``2.3.0 LiquidFun 1.1.0``