.. _field_animations:

field_animations.lua
--------------------

This script contains some animations to reveal and hide fields seen
by a player. This functions are currently used in the campaigns and scenarios
to tell the prologue to a story.

.. code-block:: lua

   include "scripting/field_animations.lua"


.. function:: reveal_randomly(player, region, time)

   Reveal a given region field by field, where the fields
   are chosen randomly. The region will be hidden before being revealed.
   The animation runs the specified time.

   :arg player: The player who gets sight to the region
   :type player: :class:`wl.game.Player`
   :arg region: The region that has to be revealed. E.g. by using :meth:`wl.map.Field.region`
   :type region: :class:`array` of :class:`fields <wl.map.Field>`
   :arg time: Optional. The time the whole animation will run.
              Defaults to 1000 (1 sec)
   :type time: :class:`integer`
   :arg hide: Optional, if :const:`false` automatic hiding is disabled
   :type hide: :class:`boolean`

.. function:: hide_randomly(player, region, time[, permanent=false])

   Hide a given region field by field, where the fields
   are chosen randomly. The animation runs the specified time regardless
   how big the given region is. So region(6) and region(13) will take
   the same time.

   :arg player: The player whose sight gets hidden
   :type player: :class:`wl.game.Player`
   :arg region: The region that will be hidden. E.g. by using :meth:`wl.map.Field.region`
   :type region: :class:`array` of :class:`fields <wl.map.Field>`
   :arg time: Optional. The time the whole animation will run.
              Defaults to 1000 (1 sec)
   :type time: :class:`integer`
   :arg permanent: Optional. Set to ``true`` to hide the fields permanently (they can't be
                   seen by any unit until revealed again by using
                   :meth: ~wl.game.Player.reveal_fields).
                   Set to ``false`` to make the fields unexplored (they can be rediscovered
                   by buildings and bobs again).
                   Defaults to ``false``.
   :type permanent: :class:`boolean`

.. function:: reveal_concentric(player, center, max_radius, hide, delay)

   Reveal a part of the map in a concentric way beginning from center onto
   max_radius. The region get hidden prior revealing as default.

   :arg player: The player who gets sight to the region
   :type player: :class:`wl.game.Player`
   :arg center: The field from where the animation should start revealing
   :type center: :class:`wl.map.Field`
   :arg max_radius: The last ring to reveal
   :type max_radius: :class:`integer`
   :arg hide: Optional, if :const:`false` automatic hiding is disabled
   :type hide: :class:`boolean`
   :arg delay: Optional, defaults to 100. The delay between revealing each
               ring. If you want to set the delay, you must also set `hide`
   :type delay: :class:`integer`

.. function:: hide_concentric(player, center, max_radius, delay[, permanent=false])

   Hide a part of the map in a concentric way beginning from max_radius onto
   center.

   :arg player: The player whose sight gets hidden
   :type player: :class:`wl.game.Player`
   :arg center: The field where the animation should end hiding
   :type center: :class:`wl.map.Field`
   :arg max_radius: The first ring to hide
   :type max_radius: :class:`integer`
   :arg delay: Optional, defaults to 100. The delay between revealing each
               ring
   :type time: :class:`integer`
   :arg permanent: Optional. Set to ``true`` to hide the fields permanently (they can't be
                   seen by any unit until revealed again by using
                   :meth: ~wl.game.Player.reveal_fields).
                   Set to ``false`` to make the fields unexplored (they can be rediscovered
                   by buildings and bobs again).
                   Defaults to ``false``.
   :type permanent: :class:`boolean`

.. function:: get_sees_fields(player)

   Gather all fields a player can see in the current view. The current view
   is the whole area of the map in the current game window. You can use this
   function to get an unregular (non hexagonal) region and feed e.g.
   :meth:`reveal_randomly` with it.

   :arg player: The player for whom the fields get gathered
   :type player: :class:`wl.game.Player`
   :returns: A table containing all visible fields in the current view