{"id":25943660,"url":"https://github.com/pecas-dev/s.w.a.g-fsm","last_synced_at":"2025-08-21T20:29:06.515Z","repository":{"id":280321762,"uuid":"941597866","full_name":"Pecas-Dev/S.W.A.G-FSM","owner":"Pecas-Dev","description":"Sheep, Wolf and Grass Ecosystem Simulation: A dynamic ecosystem simulation featuring three entities (Sheep, Wolves and Grass) interacting through Finite State Machines. Built with C++, Raylib \u0026 ImGUI.","archived":false,"fork":false,"pushed_at":"2025-03-02T18:07:37.000Z","size":95023,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-02T18:38:15.042Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pecas-Dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-02T17:05:21.000Z","updated_at":"2025-03-02T18:22:42.000Z","dependencies_parsed_at":"2025-03-02T18:48:31.500Z","dependency_job_id":null,"html_url":"https://github.com/Pecas-Dev/S.W.A.G-FSM","commit_stats":null,"previous_names":["pecas-dev/s.w.a.g-fsm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pecas-Dev%2FS.W.A.G-FSM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pecas-Dev%2FS.W.A.G-FSM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pecas-Dev%2FS.W.A.G-FSM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pecas-Dev%2FS.W.A.G-FSM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pecas-Dev","download_url":"https://codeload.github.com/Pecas-Dev/S.W.A.G-FSM/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241801258,"owners_count":20022401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-04T07:18:11.368Z","updated_at":"2025-03-04T07:18:12.112Z","avatar_url":"https://github.com/Pecas-Dev.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# S.W.A.G-FSM \u003cbr\u003e | Sheep, Wolves and Grass: Finite State Machine Simulation |\n\n\u003cbr\u003e\n\n---\n\n## Overview\n\nThis project implements a dynamic ecosystem simulation featuring three entities (**Sheep, Wolves and Grass**) using **Finite State Machines (FSM)** for behavior modeling. Built in **C++** with [**Raylib**](https://github.com/raysan5/raylib) for graphics rendering and [**ImGui**](https://github.com/ocornut/imgui) for the user interface, the simulation demonstrates complex agent behaviors and interactions within a controlled environment.\n\nThe ecosystem models predator-prey relationships and natural life cycles, with each entity having distinct states and behaviors:\n\n- **Sheep** wander, eat grass, form groups, reproduce, and flee from wolves.\n- **Wolves** hunt sheep, rest in dens, and manage their hunger cycles.\n- **Grass** grows, spreads, and eventually wilts.\n\n### Features\n\n- **Complete FSM Implementation**: Each entity has a dedicated state machine with multiple states and transitions.\n- **Configurable Simulation**: Adjust entity parameters through a user-friendly interface.\n- **Visual Feedback**: Color-coded entities for easy state identification.\n- **Real-time Statistics**: Monitor entity counts and states during simulation.\n- **Sense-Decide-Act Pattern**: Entities use this pattern for realistic decision-making.\n- **Dynamic Ecosystem**: Watch how population balances shift over time.\n- **Group Behaviors**: Sheep exhibit flocking and social behaviors.\n- **Health/Hunger/Stamina Systems**: Entities track vital statistics.\n\n\u003cbr\u003e\n\n---\n\n## Simulation Details\n\n### Sheep States\n\n- **Wandering Alone**: Individual exploration.\n- **Wandering in Group**: Social movement with other sheep.\n- **Eating**: Consuming grass for sustenance.\n- **Defecating**: After reaching fullness.\n- **Running Away**: When wolves are detected.\n- **Reproducing**: Creating new sheep when conditions are right.\n\n### Wolf States\n\n- **Sleeping**: Resting in den.\n- **Roaming**: Searching for prey.\n- **Hunting**: Pursuing targeted sheep.\n- **Eating**: Consuming captured prey.\n- **Returning to Den**: Moving back home after feeding.\n\n### Grass States\n\n- **Seeds Planted**: Initial growth stage.\n- **Fully Grown**: Mature state where seeds can be spread.\n- **Wilting**: Final state before removal.\n\n\u003cbr\u003e\n\n---\n\n## User Interface\n\nThe simulation provides a comprehensive UI that allows users to:\n\n- Configure initial entity counts.\n- Adjust entity-specific parameters:\n  - **Sheep**: Health, hunger, movement speed, perception radius, etc.\n  - **Wolves**: Hunger thresholds, hunting speed, attack damage, etc.\n  - **Grass**: Growth time, spreading chance, lifetime, etc.\n- Monitor entity states in real-time.\n- View console output for significant events.\n- Toggle visualization of detection radii.\n- Adjust display scale to match screen size.\n\n\u003cbr\u003e\n  \n---------------------------------------------\n\n## Architecture\n\nThe project follows a clean, modular architecture with clear separation of concerns:\n\n### Core Components\n\n- **State Machines**: Handle entity behavior transitions.\n- **Entity Base Classes**: Provide common functionality for world entities.\n- **World Class**: Manages entity creation, updates, and interactions.\n- **Simulation Class**: Controls the overall flow and UI rendering.\n\n### Design Patterns\n\n- **State Pattern**: For FSM implementation.\n- **Sense-Decide-Act**: Entities perceive the environment, evaluate options, then act.\n- **Component-Based Design**: Entities have distinct components for different aspects of behavior.\n\n### Code Organization\n\n- Consistent naming conventions (camelCase for variables, PascalCase for functions).\n- Clear separation between header (.h) and implementation (.cpp) files.\n- Well-documented code with focused explanatory comments.\n- Proper memory management with RAII principles.\n\n\u003cbr\u003e\n\n---\n\n## Installation \u0026 Running\n\n\u003cbr\u003e\n\n**Clone the repository:**\n\n```bash\ngit clone https://github.com/Pecas-Dev/S.W.A.G-FSM.git\n```\n\n### Pre-compiled Executables\n\nThe easiest way to run the simulation is using the pre-compiled executables:\n\n1. Navigate to the `Release` folder.\n2. Choose the appropriate version for your system (`x64` or `86`).\n3. Run the `S.W.A.G x64.bat` or `S.W.A.G x86.bat`or file.\n\n### Building from Source\n\nTo build the project from source:\n\n1. Open `S.W.A.G-FSM.sln` in Visual Studio.\n2. Choose your configuration (Debug/Release) and platform (x64/x86).\n3. Build the solution.\n4. Run the program.\n\n### System Requirements\n\n- Windows operating system.\n- Visual Studio 2022 (to build from source).\n- After Testing: Display resolution of at least 1366x768 for optimal viewing.\n\n\u003cbr\u003e\n\n---\n\n\u003cbr\u003e\n\n## Project Structure\n\n```\nProject Root\n├── S.W.A.G-FSM.sln                        // Visual Studio solution file\n├── .gitignore\n├── bin                                    // Binary files\n├── Release                                // Pre-compiled executables\n│   ├── S.W.A.G x64.bat                    // Run x64 S.W.A.G\n│   ├── S.W.A.G x86.bat                    // Run x86 S.W.A.G\n│   └── Platforms\n│       ├── x64                            // 64-bit builds\n│       └── Win32                          // 32-bit builds\n│\n├── Dependencies                           // External dependencies\n│   └── raylib                             // Raylib graphics library files\n│\n├── S.W.A.G-FSM                            // Source files and project configurations\n│   ├── Assets                             // Simulation assets\n│   │   ├── Wolf                           // Wolf entity sprites\n│   │   │   └── Wolf.png\n│   │   │\n│   │   ├── Sheep                          // Sheep entity sprites\n│   │   │   └── Sheep.png\n│   │   │\n│   │   └── Grass                          // Grass entity sprites in various states\n│   │       ├── FullyGrown\n│   │       │   └── Grass7.png\n│   │       │\n│   │       ├── Wilting\n│   │       │   └── Grass8.png\n│   │       │\n│   │       └── Growing                    // Growth animation frames\n│   │           ├── Grass1.png\n│   │           ├── Grass2.png\n│   │           ├── Grass3.png\n│   │           ├── Grass4.png\n│   │           ├── Grass5.png\n│   │           └── Grass6.png\n│   │\n│   ├── S.W.A.G                            // Source code of the project\n│   │   ├── include                        // Header files\n│   │   │   ├── Entities                   // Entity definitions\n│   │   │   │    ├── Grass                 // Grass entity and states\n│   │   │   │    ├── Sheep                 // Sheep entity and states\n│   │   │   │    └── Wolf                  // Wolf entity and states\n│   │   │   │\n│   │   │   ├── Simulation                 // Simulation control and UI\n│   │   │   ├── Utility                    // Helper classes and functions\n│   │   │   ├── vendor                     // Third-party libraries\n│   │   │   └── World                      // World management\n│   │   │\n│   │   ├── source                         // Implementation files\n│   │   │   ├── Entities                   // Entity implementations\n│   │   │   │    ├── Grass                 // Grass behaviors\n│   │   │   │    ├── Sheep                 // Sheep behaviors\n│   │   │   │    └── Wolf                  // Wolf behaviors\n│   │   │   │\n│   │   │   ├── Simulation                 // Simulation logic\n│   │   │   ├── Utility                    // Helper implementations\n│   │   │   ├── vendor                     // Third-party code\n│   │   │   └── World                      // World class implementation\n│   │   │\n│   │   └── main.cpp                       // Entry point\n│   │\n│   └── Project Files                      // Visual Studio project configuration files\n└── README.md                              // This documentation file\n```\n\n\u003cbr\u003e\n\n---\n\n## Controls and Interaction\n\nOnce the simulation is running:\n\n- **Press R**: Toggle detection radius visualization.\n- Use the UI panels to monitor entity states.\n- Watch the ecosystem evolve over time.\n- Check the console tab for detailed event logs.\n\n---\n\n## Development\n\nThis project was developed as an exploration of agent-based modeling and finite state machines. The implementation focused on creating a visually engaging simulation that demonstrates complex entity interactions while maintaining clean architecture principles. The project showcases my interest in game AI, interactive simulations, and **UI/UX design**, combining **technical programming skills** with **creative system design**.\n\n---\n\n## Acknowledgments\n\n- [**Raylib**](https://github.com/raysan5/raylib) library for rendering.\n- [**Dear ImGui**](https://github.com/ocornut/imgui) for the user interface components.\n\n---\n\n## Credits\n\nThis project was created by **_PecasDev_**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpecas-dev%2Fs.w.a.g-fsm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpecas-dev%2Fs.w.a.g-fsm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpecas-dev%2Fs.w.a.g-fsm/lists"}