add GUI Documentation

README.md

@@ -0,0 +1,187 @@
+<!-- \cond DOXYGEN_SKIP_THIS -->
+# ZAPPY
+
+<!-- Badges -->
+![C](https://img.shields.io/badge/language-C-blue.svg?logo=c&logoColor=white)
+![C++](https://img.shields.io/badge/language-C%2B%2B-purple.svg?logo=c%2B%2B&logoColor=white)
+![Python](https://img.shields.io/badge/language-Python-yellow.svg?logo=python&logoColor=white)
+![Makefile](https://img.shields.io/badge/build-Makefile-brightgreen?logo=gnu&logoColor=white)
+![Linux x86_64](https://img.shields.io/badge/platform-Linux%20x86__64-lightgrey?logo=linux)
+![Nix](https://img.shields.io/badge/env-Nix-5277C3?logo=nixos&logoColor=white)
+[![AI Coverage](https://codecov.io/gh/Sigmapitech/zappy/branch/dev/graph/badge.svg?token=5fssEEelNi&flag=ai)](https://codecov.io/gh/Sigmapitech/zappy?branch=dev)
+[![GUI Coverage](https://codecov.io/gh/Sigmapitech/zappy/branch/dev/graph/badge.svg?token=5fssEEelNi&flag=gui)](https://codecov.io/gh/Sigmapitech/zappy?branch=dev)
+[![Server Coverage](https://codecov.io/gh/Sigmapitech/zappy/branch/dev/graph/badge.svg?token=5fssEEelNi&flag=server)](https://codecov.io/gh/Sigmapitech/zappy?branch=dev)
+![Build](https://img.shields.io/github/actions/workflow/status/Sigmapitech/zappy/ci.yml?branch=main&logo=github)
+![Last Commit](https://img.shields.io/github/last-commit/Sigmapitech/zappy?logo=git)
+![Issues](https://img.shields.io/github/issues/Sigmapitech/zappy?logo=github)
+![Pull Requests](https://img.shields.io/github/issues-pr/Sigmapitech/zappy?logo=github)
+![Code style](https://img.shields.io/badge/code%20style-clangformat-blue?logo=clang)
+
+## Overview
+
+ZAPPY is a network game about managing a world and its inhabitants, where several teams
+confront each other on a tile map containing resources. The winning team is the first one
+where at least 6 players reach the maximum elevation. To do so, a team of player AIs is
+launched on a board representing their planet, communicating –and sabotaging other teams–
+together to achieve victory.
+
+## Features
+
+### AI (Behavior)
+
+- Custom encrypted communication algorithm
+- Fully autonomous agent controlled via commands sent to the server
+- Connects using team name and adapts based on server world size and team slots
+- Parses look, inventory, and broadcast messages for environment awareness
+- Movement, resource collection, reproduction, and elevation
+
+### GUI (Visualization)
+
+- Authenticates with reserved GRAPHIC team
+- Displays a real-time 2D map of the world with OpenGL
+- Receives push-based updates for world state and tile modifications
+- Renders players, resources, and elevation activities
+- Optimized to react to event-driven server messages for minimal redraws
+
+### Server (Game logic, networking)
+  - Manages a toroidal 2D world grid with configurable size
+  - Handles TCP client connections, for multiple clients and teams
+  - Spawns resources across the grid periodically, using fixed densities
+  - Maintains synchronized game state including players, resources, and eggs
+  - Validates elevation rituals and synchronizes level-ups
+  - Manages broadcast propagation with directional awareness
+  - Enforces client communication protocol and command rate limits
+  - Executes and times all player actions
+
+## Requirements
+
+- **gcc**
+- **python3**
+- **make**
+- **Nix** (optional, for reproducible builds via `flake.nix`)
+
+## Project Structure
+
+```sh
+.
+├── ai/
+│   ├── legacy/...
+│   └── ...
+├── gui/
+│   └── ...
+├── server/
+│   └── ...
+├── scripts/
+│   ├── align_columns.py
+│   ├── check_commit_message.py
+│   ├── discard_headers.py
+│   └── insert_headers.py
+├── tests/
+│   ├── ai/...
+│   ├── gui/...
+│   ├── server/...
+├── .clang-format
+├── .clang-tidy
+├── .gitignore
+├── configure-venv.sh
+├── Makefile
+├── flake.nix
+├── flake.lock
+├── pyproject.toml
+├── assignment.pdf
+├── zappy_gui_protocol.pdf
+├── zappy_ref-v3.0.0.tgz
+└── .github/
+    └── workflows/
+        └── ci.yml
+```
+
+## Installation
+
+1. **Clone the repository:**
+
+   ```sh
+   git clone <repository-url>
+   cd <repository-directory>
+   ```
+
+2. **Build the project:**
+
+   ```sh
+   make
+   ```
+
+   - Use `make re` to force a rebuild.
+   - Use `make clean` to remove object files.
+   - Use `make fclean` to remove all build artifacts and binaries.
+
+3. **(Optional) Using Nix:**
+
+   ```sh
+   nix develop
+   make
+   ```
+
+## Usage
+
+### Server
+
+Run the server shell with:
+
+```sh
+./zappy_server -p port -x width -y height -n name1 name2 ... -c clientsNb -f freq
+```
+
+- `-p port`: Port number.
+- `-x width`: Width of the world.
+- `-y height`: Height of the world.
+- `-n name1 name2 ...`: Name(s) of the allowed team(s).
+- `-c clientsNb`: Number of authorized clients per team.
+- `-f freq`: Reciprocal of time unit for execution of actions.
+
+> [!NOTE]
+> The team name `GRAPHIC` is reserved for the GUI to authenticate itself as such to
+the server.
+
+### GUI
+
+Run the server shell with:
+
+```sh
+./zappy_gui -p port -h machine
+```
+
+- `-p port`: Port number.
+- `-h machine`: Hostname of the server.
+
+### AI
+
+Run the server shell with:
+
+```sh
+./zappy_ai -p port -n name -h machine
+```
+
+- `-p port`: Port number.
+- `-n name`: Name of the team.
+- `-h machine`: Name of the machine; localhost by default.
+
+## Testing
+
+- **Coverage:**
+  Run:
+
+  ```sh
+  make cov
+  ```
+
+  *(To be completed: Add test instructions and coverage details.)*
+
+## Contributors
+
+| Yohann B. | Gabriel H. | Julien B. | Valentin R. | Hugo H. |
+|---|---|---|---|---|
+| <img src="https://github.com/Sigmanificient.png" width="300em"/> | <img src="https://github.com/Ciznia.png" width="300em"/> | <img src="https://github.com/Fenriir42.png" width="300em"/> | <img src="https://github.com/Valentin22r.png" width="300em"/> | <img src="https://github.com/hop3calypse.png" width="300em"/> |
+
+For more details, see <a href="assignment.pdf">assignment.pdf</a>.
+<!-- \endcond -->

docs/README.md

@@ -27,7 +27,31 @@ together to achieve victory.
 
 ## Features
 
-- ...
+### AI (Behavior)
+
+- Custom encrypted communication algorithm
+- Fully autonomous agent controlled via commands sent to the server
+- Connects using team name and adapts based on server world size and team slots
+- Parses look, inventory, and broadcast messages for environment awareness
+- Movement, resource collection, reproduction, and elevation
+
+### GUI (Visualization)
+
+- Authenticates with reserved GRAPHIC team
+- Displays a real-time 2D map of the world with OpenGL
+- Receives push-based updates for world state and tile modifications
+- Renders players, resources, and elevation activities
+- Optimized to react to event-driven server messages for minimal redraws
+
+### Server (Game logic, networking)
+  - Manages a toroidal 2D world grid with configurable size
+  - Handles TCP client connections, for multiple clients and teams
+  - Spawns resources across the grid periodically, using fixed densities
+  - Maintains synchronized game state including players, resources, and eggs
+  - Validates elevation rituals and synchronizes level-ups
+  - Manages broadcast propagation with directional awareness
+  - Enforces client communication protocol and command rate limits
+  - Executes and times all player actions
 
 ## Requirements
 
@@ -40,29 +64,36 @@ together to achieve victory.
 
 ```sh
 .
-├── server/
-│   └── ...
 ├── ai/
+│   ├── legacy/...
 │   └── ...
 ├── gui/
 │   └── ...
+├── server/
+│   └── ...
 ├── scripts/
 │   ├── align_columns.py
 │   ├── check_commit_message.py
 │   ├── discard_headers.py
 │   └── insert_headers.py
+├── tests/
+│   ├── ai/...
+│   ├── gui/...
+│   ├── server/...
 ├── .clang-format
 ├── .clang-tidy
 ├── .gitignore
+├── configure-venv.sh
 ├── Makefile
 ├── flake.nix
 ├── flake.lock
+├── pyproject.toml
 ├── assignment.pdf
+├── zappy_gui_protocol.pdf
 ├── zappy_ref-v3.0.0.tgz
-├── .github/
-│   └── workflows/
-│       └── ci.yml
-└── (bonus/)
+└── .github/
+    └── workflows/
+        └── ci.yml
 ```
 
 ## Installation

docs/gui/demeter_V3.rst

@@ -0,0 +1,112 @@
+=======================
+DemeterV3 Documentation
+=======================
+
+Overview
+--------
+DemeterV3 is a C++ entity-based game engine designed for high-performance 2D and 3D applications. It features a custom rendering engine built with SDL2 and OpenGL, supporting the loading and rendering of JPEG/PNG textures and Wavefront `.obj` 3D model files.
+
+Features
+--------
+* **Entity-Based Architecture**: Core logic is built around entities, each inheriting from a common `IEntity` interface.
+* **Rendering Engine**: Utilizes SDL2 for window/context management and OpenGL for rendering. Support includes basic texture mapping and `.obj` mesh rendering.
+* **Asset Loading**: Built-in support for loading image files (`.jpg`, `.png`) and 3D object files (`.obj`).
+* **ImGUI Integration**: Fully integrated support for Dear ImGui, allowing developers to use the library in the standard way for creating in-game or debug UI.
+
+Entity System
+-------------
+All game objects are represented as entities. Each entity must inherit from the `IEntity` interface defined in the `Dem` namespace. The interface ensures consistent update and render behavior across all entities.
+
+.. code-block:: cpp
+
+```
+namespace Dem {
+
+  struct Demeter;
+
+  class IEntity : public std::enable_shared_from_this<IEntity> {
+  public:
+    virtual ~IEntity() = default;
+
+    // Updates the entity with context from the Demeter engine
+    virtual bool Update(Demeter &d) = 0;
+
+    // Draws the entity using the Demeter engine's rendering context
+    virtual bool Draw(Demeter &d) = 0;
+  };
+
+} // namespace Dem
+```
+
+* **Update(Demeter \&d)**: Updates the entity's state using the given Demeter context. Returns `true` on success.
+* **Draw(Demeter \&d)**: Renders the entity using the Demeter context. Returns `true` on success.
+
+Main Loop
+---------
+The engine executes the following steps during each frame of the main loop:
+
+1. Process input events.
+2. Call `Update()` on all registered entities.
+3. Clear the screen.
+4. Call `Draw()` on all registered entities.
+5. Present the rendered frame.
+
+Getting Started
+---------------
+To begin using DemeterV3:
+
+1. Set up an SDL2 + OpenGL development environment.
+2. Include the DemeterV3 engine headers and link against its library.
+3. Create your own entities by implementing the `IEntity` interface.
+4. Register entities with the engine and start the main loop.
+
+Here is an example of a simple entity implementation:
+
+.. code-block:: cpp
+
+```
+class MyEntity : public Dem::IEntity {
+public:
+    bool Update(Dem::Demeter &d) override {
+        // update logic
+        return true;
+    }
+
+    bool Draw(Dem::Demeter &d) override {
+        // draw logic
+        return true;
+    }
+};
+```
+
+Starting a Game
+---------------
+To initialize and start a DemeterV3 game, create an instance of the `Demeter` engine and register your entities as shown:
+
+.. code-block:: cpp
+
+```
+Game::Game(Args &params)
+{
+  std::unique_ptr<SDL2> sdl2 = std::make_unique<SDL2>();
+  demeter = std::make_unique<Dem::Demeter>(std::move(sdl2));
+
+  // Register entities
+  demeter->AddEntity(std::make_shared<E_Default>(params));
+}
+
+void Game::Run()
+{
+  demeter->Run();
+}
+```
+
+This setup initializes SDL2, creates a Demeter engine instance, registers entities, and starts the main loop.
+
+Dependencies
+---------------
+* SDL2
+* OpenGL
+* glew
+* glm
+* Dear ImGui (for GUI development)

docs/gui/gui.rst

@@ -0,0 +1,19 @@
+=================
+GUI Documentation
+=================
+
+This section describes the GUI client implementation and internal design:
+
+- Communication protocol
+- Graphical Engine
+- Entity Manager
+- SubWindow
+
+.. toctree::
+   :maxdepth: 2
+
+    protocole
+    graphical_engine
+    entity_manager
+    sub_window
+    demeter_V3