game.environment.villager_happiness
===================================

.. py:module:: game.environment.villager_happiness

.. autoapi-nested-parse::

   Manages the happiness level of the villagers.



Classes
-------

.. autoapisummary::

   game.environment.villager_happiness.VillagerHappinessSystem


Module Contents
---------------

.. py:class:: VillagerHappinessSystem(isometric_map, entity_manager, degradation_system)

   Calculates and tracks the average happiness of island villagers.

   Happiness is composed of three parts:

   * **Food happiness** — rises with pig count up to an ideal range, then
     falls off as the population grows too large.
   * **Environment happiness** — average of ecosystem health (inverse of
     overall degradation) and current forest coverage.
   * **Feast bonus** — a temporary boost granted when an emergency feast
     reduces an over-populated pig herd; decays smoothly over time.

   The two base components are recalculated once per second to avoid
   per-frame overhead.  The feast bonus is updated every frame for smooth
   visual decay.


   .. py:attribute:: isometric_map


   .. py:attribute:: entity_manager


   .. py:attribute:: degradation_system


   .. py:attribute:: food_happiness
      :value: 0.75



   .. py:attribute:: environment_happiness
      :value: 0.75



   .. py:attribute:: feast_happiness_bonus
      :value: 0.0



   .. py:attribute:: feast_bonus_decay_rate
      :value: 0.1



   .. py:method:: register_feast(pigs_slaughtered)

      Register that an emergency feast has taken place.

      If the pig count *before* the feast exceeded ``HAPPINESS_IDEAL_PIG_MAX``
      (i.e. the feast actually relieved overpopulation pressure), a one-off
      :attr:`feast_happiness_bonus` of **0.5** is granted.  The bonus then
      decays each frame via :meth:`update`.

      :param pigs_slaughtered: Number of pigs removed by the feast.
                               Added back to the current count to reconstruct the pre-feast
                               population for the threshold check.
      :type pigs_slaughtered: int



   .. py:method:: update(dt)

      Periodically recalculates base happiness and decays any active bonus.



   .. py:method:: get_average_happiness()

      Calculates and returns the current average happiness level (0.0 to 1.0).
      This is calculated on-demand to ensure the value is always current.