diff --git a/README.md b/README.md new file mode 100644 index 00000000..c3818009 --- /dev/null +++ b/README.md @@ -0,0 +1,187 @@ + +# ZAPPY + + +![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 + cd + ``` + +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. | +|---|---|---|---|---| +| | | | | | + +For more details, see assignment.pdf. + diff --git a/docs/README.md b/docs/README.md index bcdaaee2..c3818009 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/gui/demeter_V3.rst b/docs/gui/demeter_V3.rst new file mode 100644 index 00000000..919341c8 --- /dev/null +++ b/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 { + 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 ¶ms) +{ + std::unique_ptr sdl2 = std::make_unique(); + demeter = std::make_unique(std::move(sdl2)); + + // Register entities + demeter->AddEntity(std::make_shared(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) diff --git a/docs/gui/gui.rst b/docs/gui/gui.rst new file mode 100644 index 00000000..87e3df55 --- /dev/null +++ b/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 diff --git a/docs/gui/protocole.rst b/docs/gui/protocole.rst new file mode 100644 index 00000000..a71b181c --- /dev/null +++ b/docs/gui/protocole.rst @@ -0,0 +1,122 @@ +GUI Protocol +============ + +This page explains the communication protocol between the GUI client and the server, as defined in the project specification. + +Overview +-------- + +The GUI connects to the server via TCP and exchanges text commands. The server responds in plain text. The basic handshake: + +:: + +<-- WELCOME\n +--> GRAPHIC\n +<-- msz X Y +<-- sgt TIME_UNIT +<-- bct X Y FOOD LINEMATE DERAUMERE SIBUR MENDIANE PHIRAS THYSTAME (* X²) +<-- tna team_name\n (* NB_TEAM) +<-- enw #egg_id #player_number X Y + +Where: + +- `X`, `Y` are the map dimensions. +- `TIME_UNIT` is the time unit for the server. +- `FOOD`, `LINEMATE`, `DERAUMERE`, `SIBUR`, `MENDIANE`, `PHIRAS`, `THYSTAME` are the resources on a tile. +- `team_name` is the name of a team (repeated for each team, `NB_TEAM` times). +- `egg_id` is the egg number, `player_number` is the player number, and `X Y` are the coordinates. + +.. list-table:: Server Command Reference + :header-rows: 1 + :widths: 20 40 40 + +Command/Response Examples +------------------------- + + * - Command + - Description + - Example + * - msz X Y + - Map size + - ``msz 10 10`` + * - bct X Y q0 q1 q2 q3 q4 q5 q6 + - Content of a tile + - ``bct 2 3 1 0 0 0 0 0 0`` + * - mct + - Content of the entire map + - ``mct`` + * - tna N + - Name of a team + - ``tna TeamName`` + * - pnw #n X Y O L N + - New player connection + - ``pnw #5 4 4 1 2 TeamName`` + * - ppo #n X Y O + - Player position + - ``ppo #5 4 4 1`` + * - plv #n L + - Player level + - ``plv #5 3`` + * - pin #n X Y q0 q1 q2 q3 q4 q5 q6 + - Player inventory + - ``pin #5 4 4 1 0 0 0 0 0 0`` + * - pex #n + - Expulsion + - ``pex #5`` + * - pbc #n M + - Broadcast message + - ``pbc #5 Hello team!`` + * - pic X Y L #n ... + - Start of an incantation + - ``pic 2 3 2 #5 #6`` + * - pie X Y R + - End of an incantation + - ``pie 2 3 1`` + * - pfk #n + - Egg laying + - ``pfk #5`` + * - pdr #n i + - Resource dropping + - ``pdr #5 0`` + * - pgt #n i + - Resource collecting + - ``pgt #5 0`` + * - pdi #n + - Player death + - ``pdi #5`` + * - enw #e #n X Y + - Egg laid by a player + - ``enw #10 #5 4 4`` + * - ebo #e + - Player connection for egg + - ``ebo #10`` + * - edi #e + - Death of an egg + - ``edi #10`` + * - sgt T + - Time unit request + - ``sgt 100`` + * - sst T + - Time unit modification + - ``sst 50`` + * - seg N + - End of game + - ``seg TeamName`` + * - smg M + - Message from the server + - ``smg Welcome to Zappy!`` + * - suc + - Unknown command + - ``suc`` + * - sbp + - Command parameter error + - ``sbp`` + +API +=== + +How does it work +---------------- + +The API has a ParseAndManage method that receives a message from the server and parses and stores the data into variables and structures. + diff --git a/docs/gui/sub_window.rst b/docs/gui/sub_window.rst new file mode 100644 index 00000000..eb905de0 --- /dev/null +++ b/docs/gui/sub_window.rst @@ -0,0 +1,38 @@ +GUI SUB_WINDOW +============== + +This page describes the sub-window, its usage, and how it works. + +Goal +-------- + +- To get a better visual and avoid flooding the screen with data. +- To show a lot of data in the cleanest way. + +Usage +-------- + +There are three pages. + +**Menu (the main page)** +- Contains the time the simulation is running (in seconds) +- Contains the number of resources on the whole map +- Displays all events from AI received from the server + +**Teams (the team page)** +- Contains every team; each team contains all of their members. +- Each line of a team contains: + - the id of the member + - the position of the member + - the inventory of the member + - the level of the member + +**Setting (the setting page)** +- Allows changing the color of all text from the whole server. + +How does it work +-------- + +This sub-window is made with ImGui, which simplifies the creation of a sub-window with OpenGL. +The sub-window uses a state system. It allows you to use buttons to change the content of the pages. Each page has its own assigned state. +To change the page, you use a button that changes the state of the sub-window and its content. diff --git a/docs/index.md b/docs/index.md index 52453f27..7a7436dd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,6 +13,7 @@ developer/contribution developer/systems developer/usage_ai developer/runner +gui/gui modules protocol/protocol ``` diff --git a/zappy_gui_protocol.pdf b/zappy_gui_protocol.pdf deleted file mode 100644 index 7e503351..00000000 Binary files a/zappy_gui_protocol.pdf and /dev/null differ