# cocos.actions.basegrid_actions module

Grid Actions

## Grid Actions

There are 2 kinds of grids:

> - Grid3D : A 3D grid with x,y and z coordinates

> - TiledGrid3D A 3D grid with x,y and z coordinates, composed

>     with independent tiles

Hence, there are 2 kinds of grid actions:

> - Grid3DAction

> - TiledGrid3DAction

The Grid3DAction can modify any of vertex of the grid in any direction (x,y or z). The TiledGrid3DAction can modify any tile of the grid without modifying the adjacent tiles.

To understand visually the difference between these 2 kinds of grids, try these examples:

> - run `test/test_shakytiles3d.py` to see a TiledGrid3DAction example

> - run `test/test_shaky3d.py` to see the Grid3DAction counterpart

exception `GridException`

  Bases: `Exception`

class `GridBaseAction`(*args, **kwargs)

  Bases: `cocos.actions.base_actions.IntervalAction`

  GridBaseAction is the base class of all Grid Actions.

  `init`(grid=(4, 4), duration=5)

    Initialize the Grid Action

    Parameters
      grid(int,int)

        Number of horizontal and vertical quads in the grid

      duration int

        Number of seconds that the action will last

  `start`()

    External code sets self.target and then calls this method. Perform here any extra initialization needed.

class `Grid3DAction`(*args, **kwargs)

  Bases: `cocos.actions.basegrid_actions.GridBaseAction`

  Action that does transformations to a 3D grid ( Grid3D )

  `get_grid`()
  `get_original_vertex`(x, y)

    Get the original vertex coordinate. The original vertices are the ones weren’t modified by the current action.

    Parameters
      x int

        x-vertex

      y int

        y-vertex

    Return type

      (float, float, float)

  `get_vertex`(x, y)

    Get the current vertex coordinate

    Parameters
      x int

        x-vertex

      y int

        y-vertex

    Return type

      (float, float, float)

  `set_vertex`(x, y, v)

    Set a vertex point is a certain value

    Parameters
      x int

        x-vertex

      y int

        y-vertex

      v(float, float, float)

        tuple value for the vertex

class `TiledGrid3DAction`(*args, **kwargs)

  Bases: `cocos.actions.basegrid_actions.GridBaseAction`

  Action that does transformations to a grid composed of tiles ( TiledGrid3D ). You can transform each tile individually

  `get_grid`()
  `get_original_tile`(x, y)

    Get the 4-original tile coordinates.

    Coordinates positions:

        3 <-- 2
              ^
              |
        0 --> 1

    Parameters
      x int

        x coordinate of the tile

      y int

        y coordinate of the tile

    Return type

      [ float, float, float, float, float, float, float, float, float, float, float, float ]

    Returns

      The 4 coordinates with the following order: x0, y0, z0, x1, y1, z1,…,x3, y3, z3

  `get_tile`(x, y)

    Get the current tile coordinates.

    Coordinates positions:

        3 <-- 2
              ^
              |
        0 --> 1

    Parameters
      x int

        x coordinate of the tile

      y int

        y coordinate of the tile

    Return type

      [ float, float, float, float, float, float, float, float, float, float, float, float ]

    Returns

      The 4 coordinates with the following order: x0, y0, z0, x1, y1, z1,…,x3, y3, z3

  `set_tile`(x, y, coords)

    Set the 4 tile coordinates

    Coordinates positions:

        3 <-- 2
              ^
              |
        0 --> 1

    Parameters
      x int

        x coodinate of the tile

      y int

        y coordinate of the tile

      coords[ float, float, float, float, float, float, float, float, float, float, float, float ]

        The 4 coordinates in the format (x0, y0, z0, x1, y1, z1,…, x3, y3, z3)

class `AccelAmplitude`(*args, **kwargs)

  Bases: `cocos.actions.base_actions.IntervalAction`

  Increases the waves amplitude from 0 to self.amplitude

  Example:

      # when t=0 the amplitude will be 0
      # when t=1 the amplitude will be 40
      action = AccelAmplitude( Wave3D( waves=4, amplitude=40, duration=6), rate=1.0 )
      scene.do( action )

  `init`(other, rate=1)

    Init method.

    Parameters
      other IntervalAction

        The action that will be affected

      rate float

        The acceleration rate. 1 is linear (default value)

  `start`()

    External code sets self.target and then calls this method. Perform here any extra initialization needed.

  `update`(t)

    Gets called on every frame ‘t’ is the time elapsed normalized to [0, 1] If this action takes 5 seconds to execute, t will be equal to 0 at 0 seconds. t will be 0.5 at 2.5 seconds and t will be 1 at 5sec. This method must not use self._elapsed, which is not guaranted to be updated.

class `DeccelAmplitude`(*args, **kwargs)

  Bases: `cocos.actions.basegrid_actions.AccelAmplitude`

  Decreases the waves amplitude from self.amplitude to 0

  Example:

      # when t=1 the amplitude will be 0
      # when t=0 the amplitude will be 40
      action = DeccelAmplitude( Wave3D( waves=4, amplitude=40, duration=6), rate=1.0 )
      scene.do( action )

  `update`(t)

    Gets called on every frame ‘t’ is the time elapsed normalized to [0, 1] If this action takes 5 seconds to execute, t will be equal to 0 at 0 seconds. t will be 0.5 at 2.5 seconds and t will be 1 at 5sec. This method must not use self._elapsed, which is not guaranted to be updated.

class `AccelDeccelAmplitude`(*args, **kwargs)

  Bases: `cocos.actions.base_actions.IntervalAction`

  Increases and Decreases the amplitude of Wave

  Example:

      # when t=0 and t=1 the amplitude will be 0
      # when t=0.5 (half time), the amplitude will be 40
      action = AccellDeccelAmplitude( Wave3D( waves=4, amplitude=40, duration=6) )
      scene.do( action )

  `init`(other, rate=1.0)

    Init method.

    Parameters
      other IntervalAction

        The action that will be affected

      rate float

        The acceleration rate. 1 is linear (default value)

  `start`()

    External code sets self.target and then calls this method. Perform here any extra initialization needed.

  `update`(t)

    Gets called on every frame ‘t’ is the time elapsed normalized to [0, 1] If this action takes 5 seconds to execute, t will be equal to 0 at 0 seconds. t will be 0.5 at 2.5 seconds and t will be 1 at 5sec. This method must not use self._elapsed, which is not guaranted to be updated.

class `StopGrid`(*args, **kwargs)

  Bases: `cocos.actions.base_actions.InstantAction`

  StopGrid disables the current grid. Every grid action, after finishing, leaves the screen with a certain grid figure. This figure will be displayed until StopGrid or another Grid action is executed.

  Example:

      scene.do( Waves3D( duration=2) + StopGrid() )

  `start`()

    Here we must do out stuff

class `ReuseGrid`(*args, **kwargs)

  Bases: `cocos.actions.base_actions.InstantAction`

  Will reuse the current grid for the next grid action. The next grid action must have these properties:

  > - Be of the same class as the current one ( Grid3D or TiledGrid3D )

  > - Have the same size

  If these condition are met, then the next grid action will receive as the `original vertex` or `original tiles` the current ones.

  Example:

      scene.do( Waves3D( duration=2) + ReuseGrid() + Lens3D(duration=2) )

  `init`(reuse_times=1)
    Parameters
      reuse_times int

        Number of times that the current grid will be reused by Grid actions. Default: 1

  `start`()

    Here we must do out stuff