Gameplay Guide
==============

Objective
---------

Score as many points as possible in **90 seconds** without collapsing the island's
ecosystem. The game ends early if environmental degradation reaches 100 % — a
permanent ecological collapse.

Game States
-----------

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - State
     - Description
   * - Main Menu
     - Language selection → instructions → username and difficulty
   * - Playing
     - Active gameplay; all systems running
   * - Paused
     - All timers and AI frozen
   * - Game Over
     - Win (survived 90 s) or loss (ecosystem collapsed); high-score entry

Difficulty Levels
-----------------

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Difficulty
     - Effect
   * - Easy
     - Slower pig birth rate, faster natural recovery
   * - Medium
     - Balanced default settings
   * - Hard
     - Faster pig birth rate, slower recovery, higher degradation

Controls
--------

.. list-table::
   :widths: 15 85
   :header-rows: 1

   * - Key / Input
     - Action
   * - **E**
     - Pause / unpause the game
   * - **S**
     - Send one pig to another island (+50 points)
   * - **D**
     - Emergency feast — slaughter half the pigs (+25 pts each, 20 s cooldown)
   * - **Mouse click**
     - UI buttons (same actions as keyboard shortcuts)

Scoring
-------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Event
     - Points
   * - Each second survived
     - +10
   * - Pig sent away
     - +50
   * - Pig slaughtered in feast
     - +25 each
   * - Ecosystem health bonus
     - Multiplier applied at game end

Game Systems
------------

Degradation
~~~~~~~~~~~

Every tile on the island has a *degradation level* between 0 (pristine) and 1
(fully degraded). Three forces drive degradation:

- **Pig eating** — pigs degrade tiles in a small radius around them at a rate
  configurable via :data:`game.utils.constants.PIG_DEGRADATION_RATE`.
- **Villager logging** — villagers target forest tiles and degrade them at
  :data:`game.utils.constants.VILLAGER_DEGRADATION_RATE`.
- **Cascading spread** — highly degraded tiles spread degradation to neighbours
  at :data:`game.utils.constants.CASCADE_DEGRADATION_RATE`.

Natural recovery partially counteracts degradation at
:data:`game.utils.constants.NATURAL_RECOVERY_RATE` when a tile is not actively
being damaged.

The :class:`game.environment.degradation.DegradationSystem` aggregates these
effects and exposes an *overall degradation* metric used for win/loss detection.

Villager Happiness
~~~~~~~~~~~~~~~~~~

:class:`game.environment.villager_happiness.VillagerHappinessSystem` tracks
satisfaction along two axes:

- **Food happiness** — rises with more pigs (food source) up to an ideal
  population, then plateaus.
- **Environment happiness** — falls as island degradation increases.

Calling an emergency feast grants a temporary happiness bonus.

Pig Population
~~~~~~~~~~~~~~

Pigs spawn automatically at :data:`game.utils.constants.PIG_BIRTH_RATE` seconds
per new pig. Each pig has a random *size* variation (0.8 – 1.2) affecting its
sprite scale. Pigs prefer to move towards healthier (less degraded) tiles.

Tips
----

- Watch the real-time graph for early warning signs — happiness and health both
  falling together is the danger signal.
- Use the feast action in bursts when the pig count spikes; the 20-second cooldown
  means timing matters.
- Forest tiles recover faster than bare land, so preserve them where possible.
- Sending individual pigs away scores more points per pig than a feast but removes
  fewer pigs overall.