Merge the new documentation

.gitignore

@@ -45,3 +45,4 @@ docs/source/api
 # Logs
 logs
 *.log
+docs/code/*

Doxyfile

@@ -1,5 +1,5 @@
 PROJECT_NAME = Zappy
-INPUT = server gui
+INPUT = server gui ai
 
 FILE_PATTERNS = *.c *.cpp *.h *.hpp
 RECURSIVE = YES

docs/.gitignore

@@ -1 +1 @@
-api
+code/*

docs/ai/ai.rst

@@ -0,0 +1,20 @@
+=================
+AI Documentation
+=================
+
+This section describes the AI client implementation and internal design:
+
+- Communication protocol
+- Triangulation strategies
+- Message ciphering
+- Job system
+- Overall AI strategies
+
+.. toctree::
+   :maxdepth: 2
+
+   protocol
+   triangulation
+   message_cipher
+   jobs
+   strategies

docs/ai/jobs.rst

@@ -0,0 +1,141 @@
+AI Job System
+==============
+
+This page explains the *Legacy AI Behavior* we experimented with for the project.
+
+Our unfinished AI design used well-defined behavioral roles called **Jobs**.
+Each job had its own file in `ai/behavior/`, implementing the abstract `JobTemplate` class.
+This class provided a shared structure for all specialized behaviors.
+
+Overview
+--------
+
+- **Newcomer**
+  - Default job for any freshly spawned player.
+  - Waits to be assigned a role by the existing *Elder*.
+  - If no Elder broadcast is heard for 50 ticks, promotes itself to Elder.
+
+- **Elder**
+  - A single Elder exists per civilization.
+  - Acts as the central coordinator:
+    - Chooses a "home tile" near civilization center.
+    - Receives stones, food, and players for incantations.
+    - Assigns jobs to newcomers.
+    - Tracks the roles and locations of all known players.
+  - Garblers are a partial exception: they are not tracked as precisely, and assignment is rarer to avoid confusion.
+
+- **Basic**
+  - Default worker role.
+  - Randomly paths around the map, collecting any stones in its way.
+  - Broadcasts when it has enough resources to evolve.
+
+- **Collector**
+  - Focuses on gathering specific stones.
+  - Delivers resources to the Elder's designated home tile.
+
+- **Garbler**
+  - Leaves the civilization to embed itself in an enemy team.
+  - Goal is to disrupt enemy communication.
+  - For every message it sends, it cycles modes:
+    - **50%** Raven: emits nonsense (including invalid encodings like `\feff`).
+    - **40%** Mimicry: repeats verbatim any intercepted enemy message.
+    - **10%** Parrot: repeats messages with heavy modification.
+
+Job Assignment System
+----------------------
+
+The Elder assigns jobs dynamically, using our team's broadcast protocol.
+Each player listens for instructions and responds appropriately.
+
+Communication Protocol
+-----------------------
+
+All inter-player instructions passed through team broadcasts during the game are defined below:
+
+.. list-table:: Job Protocol
+   :header-rows: 1
+   :widths: 10 25 25 25 15
+
+   * - Job
+     - Instruction (Recv)
+     - Instruction (Send)
+     - Effect
+     - Args / Type
+   * - Basic
+     - ``assign_job <id> <job>``
+     - ``evolution_ready <level>``
+     - Elder-directed reassignment; immediate job transition
+     - id: ``int``, job: ``str``
+   * -
+     - ``evolution_call <count>``
+     - ``evolution_response <id>``
+     - Respond to group evolution call
+     - id: ``int``
+   * -
+     - ``status_report_request``
+     - ``basic_status level:<L> needs:<N> food:<F>``
+     - Periodic status update to elder
+     - level: ``int``, needs: ``int``, food: ``int``
+   * -
+     - ``resource_request <res> <amt>``
+     - ``resource_available <res>``
+     - Respond if excess resource is held
+     - resource: ``str``, amt: ``int``
+   * - Elder
+     - ``newcomer_seeking_assignment``
+     - ``assign_job <id> <job>``
+     - Assigns newcomer to job
+     - id: ``int``, job: ``str``
+   * -
+     - ``resource_delivery <res> <amt>``
+     - ``status_report_request``
+     - Update depot stock from collector; ask for reports
+     - resource: ``str``, amt: ``int``
+   * -
+     -
+     - ``elder_location <x> <y>``
+     - Updates elder position for everyone
+     - x: ``int``, y: ``int``
+   * - Newcomer
+     - ``elder_announce <id>``
+     - ``newcomer_seeking_assignment <level>``
+     - Announces presence and level; awaits elder reply
+     - id: ``int``, level: ``int``
+   * -
+     - ``assign_job <id> <job>``
+     - ``newcomer_joined``
+     - Elder assigns role; confirms join
+     - id: ``int``, job: ``str``
+   * - Collector
+     -
+     - ``resource_delivery <res> <amt>``
+     - Dispose of the collected stones on the Elder's tile
+     - resource: ``str``, amt: ``int``
+   * - Garbler
+     -
+     - *variable garbage*
+     - Disruption: random unreadable text
+     - ``str``
+   * -
+     -
+     - *intercepted_message (mimicry/parrot)*
+     - Disruption: repeated or modified enemy message
+     - ``str``
+   * -
+     - *any enemy message*
+     -
+     - Stores for mimicry or parrot use
+     - ``str``
+
+Behavior Philosophy
+--------------------
+
+This system was designed to:
+
+- Decentralize coordination via broadcast-based communication.
+- Have a single Elder coordinate overall strategy.
+- Allow role reassignment and adaptability during play.
+- Disrupt enemy teams by embedding Garblers who mimic or garble enemy messages.
+
+Although unfinished, this "Job System" represents an ambitious attempt to create
+complex AI behaviors resembling a true in-game society.