{"id":24319354,"url":"https://github.com/rluders/rts-framework","last_synced_at":"2025-07-20T14:32:10.287Z","repository":{"id":272801280,"uuid":"917795595","full_name":"rluders/rts-framework","owner":"rluders","description":"Modular and extensible architecture designed for creating Real-Time Strategy (RTS) games in Godot 4","archived":false,"fork":false,"pushed_at":"2025-05-13T13:47:51.000Z","size":123,"stargazers_count":45,"open_issues_count":18,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-03T12:17:03.552Z","etag":null,"topics":["godot","godot-addon","godot-plugin","godotengine","rts-game"],"latest_commit_sha":null,"homepage":"","language":"GDScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rluders.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null},"funding":{"github":"rluders","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-01-16T16:57:37.000Z","updated_at":"2025-06-28T21:16:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"06352ef0-41eb-4d1f-846d-59420c045157","html_url":"https://github.com/rluders/rts-framework","commit_stats":null,"previous_names":["rluders/rts-framework"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rluders/rts-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rluders%2Frts-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rluders%2Frts-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rluders%2Frts-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rluders%2Frts-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rluders","download_url":"https://codeload.github.com/rluders/rts-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rluders%2Frts-framework/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266139595,"owners_count":23882501,"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":["godot","godot-addon","godot-plugin","godotengine","rts-game"],"created_at":"2025-01-17T15:19:52.065Z","updated_at":"2025-07-20T14:32:10.260Z","avatar_url":"https://github.com/rluders.png","language":"GDScript","funding_links":["https://github.com/sponsors/rluders"],"categories":[],"sub_categories":[],"readme":"# RTS Game Framework\n\n\u003e [!CAUTION]  \n\u003e This project is a **Work in Progress (WIP)** and is not intended for production use.  \n\u003e Features may be incomplete, and unexpected bugs or performance issues are likely to occur.  \n\u003e Before diving in, we strongly recommend checking the **Issues** tab to understand the current state of development and known limitations.  \n\u003e Use this framework for experimentation, learning, and fun, but please don’t expect a fully polished or optimized experience.\n\n## Introduction\n\n**RTS Game Framework** is a modular and extensible architecture designed for creating Real-Time Strategy (RTS) games in Godot 4. This framework is built with flexibility in mind, leveraging reusable components, a robust state system, and clean separation of responsibilities to facilitate efficient game development.\n\n## Overview\n\nThis framework is organized into several key systems and modules, each designed to handle a specific aspect of RTS game functionality. The main systems include:\n\n### Core Systems\n\nCore systems provide the foundational logic and structure for the game. These systems interact with each other to coordinate high-level gameplay.\n\n[Read more](./docs/core/README.md)\n\n### Entities\n\nEntities are the primary building blocks of the game world. They represent units, buildings, resources, and other in-game objects. Each entity can be enhanced by attaching modular components.\n\n[Read more](./docs/entities/README.md)\n\n### Components\n\nComponents are modular pieces of functionality that can be attached to entities. They allow for extending entity behavior without creating tightly coupled, monolithic systems.\n\n[Read more](./docs/components/README.md)\n\n### State System\n\nThe State System provides a flexible and reusable way to manage entity behavior. It uses a `StateMachine` to coordinate transitions between individual `State` instances.\n\n[Read more](./docs/states/README.md)\n\n### Managers\n\nManagers are specialized systems that handle specific gameplay mechanics. They are responsible for coordinating interactions, such as unit selection and command issuance.\n\n[Read more](./docs/managers/README.md)\n\n## Key Features\n\n1. **Modular Architecture**: Systems and components are designed to be independent and reusable.\n2. **Entity-Component Design**: Entities are extended through attachable components, avoiding monolithic logic.\n3. **Flexible State System**: Behavior-driven states allow dynamic entity functionality.\n4. **Event-Driven Communication**: Systems interact using signals, reducing tight coupling and enhancing scalability.\n5. **Customizable Gameplay**: The framework supports Command \u0026 Conquer or Age of Empires-style gameplay, with options for queue-driven or worker-driven construction.\n\n## The Principles of the Framework\n\nThe RTS Framework is built on two foundational principles: **decoupling** and **signal-driven architecture**. These principles ensure the framework remains modular, maintainable, and extensible, allowing developers to build complex systems with minimal friction.\n\nBy combining decoupling with signal-driven architecture, the RTS Framework achieves:\n\n- **Independent Systems**: Each manager or component handles its logic without assuming the internals of others.\n- **Event-Driven Logic**: Signals ensure clean and non-intrusive communication between systems.\n- **Customizability**: Developers can add, replace, or extend features without disrupting the framework.\n\n### Decoupling\n\nDecoupling refers to the practice of designing systems so that components and modules are independent and only interact through well-defined interfaces or abstractions.\n\n**Why Decoupling Matters in RTS Games:**\n\n1. **Modularity:**\n    - Each subsystem (e.g., selection, commands, state management) is designed to function independently. This modularity allows for easy replacement, enhancement, or debugging of individual components without affecting the rest of the system.\n    - Example: The `SelectionManager` focuses solely on handling unit selection, while the `CommandManager` handles issuing commands. They don’t directly depend on each other.\n2. **Reusability:**\n    - Decoupled systems are inherently reusable. For instance, components like `SelectableComponent` or `DamageableComponent` can be used across different types of entities (`UnitEntity`, `BuildingEntity`, etc.) without modification.\n3. **Scalability:**\n    - As RTS games grow in complexity, decoupled systems make it easier to add new features without introducing breaking changes. New components or managers can integrate seamlessly into the existing architecture.\n4. **Ease of Maintenance:**\n    - Bugs or changes in one subsystem don’t propagate to others. This isolation makes debugging and testing more efficient.\n\n### Signal-Driven Architecture\n\nSignals are event-based mechanisms in Godot that allow nodes to communicate with each other without direct references. A node emits a signal, and any other node can connect to and respond to it.\n\n**Why Signals are Key to RTS Frameworks:**\n\n1. **Loose Coupling:**\n    - Signals eliminate the need for nodes to know about each other’s existence. This keeps the system loosely coupled and ensures that changes in one part don’t ripple through the entire framework.\n    - Example: The `RTSController` emits `focus_on_position` when units are selected, and the `CameraController` listens for this event to move the camera. Neither needs a direct reference to the other.\n2. **Flexibility:**\n    - Signals make it easy to plug in or remove functionality dynamically. For instance, a building could emit a `construction_completed` signal, and multiple systems (e.g., resource tracking, UI updates) could listen to it without modifying the building’s logic.\n3. **Scalability:**\n    - Signals simplify managing many interconnected systems. Instead of hardcoding interactions, you can connect nodes dynamically or configure them in the editor.\n4. **Clarity:**\n    - By using signals, event-driven flows are explicit and centralized, making the system easier to understand and debug.\n\n**Examples in the RTS Framework:**\n\n- **Unit Selection:**\n\n    The `SelectionManager` emits `units_selected`, which the `RTSController` uses to trigger further actions like issuing commands or focusing the camera.\n\n- **State Transitions:**\n\n    The `StateMachine` emits `state_changed`, allowing other systems (e.g., animation controllers) to react without direct dependency on the state machine.\n\n## System Interaction\n\nThe framework leverages clean communication between its systems to streamline gameplay logic. For example:\n\n- The **RTSController** processes player input and delegates selection tasks to the **SelectionManager**.\n- Once units are selected, commands issued through the **CommandManager** propagate to the appropriate entities, triggering state changes like moving or attacking.\n- The **CameraController** works independently but listens for focus requests from the **RTSController** to align player navigation with game events.\n\n## Sample Workflows\n\nHere some examples how you can use the system together.\n\n### Building Construction\n\nThis diagram details how a building construction process flows between the **ConstructionManager**, worker units, and the **QueueComponent** of the building.\n\n```mermaid\nsequenceDiagram\n    participant Player\n    participant RTSController\n    participant ConstructionManager\n    participant Worker\n    participant BuildingEntity\n    participant QueueComponent\n\n    Player-\u003e\u003eRTSController: Build Command\n    RTSController-\u003e\u003eConstructionManager: start_construction(building_scene, position, worker)\n    ConstructionManager-\u003e\u003eWorker: Transition to BuildState\n    Worker-\u003e\u003eConstructionManager: Construction Complete\n    ConstructionManager-\u003e\u003eBuildingEntity: Instantiate Building\n    BuildingEntity-\u003e\u003eQueueComponent: Initialize Queue\n\n```\n\n### Unit Command\n\nThis diagram explains how a command flows from the **RTSController** to the **CommandManager** and then to selected units.\n\n```mermaid\nsequenceDiagram\n    participant Player\n    participant RTSController\n    participant SelectionManager\n    participant CommandManager\n    participant UnitEntity\n    participant StateMachine\n\n    Player-\u003e\u003eRTSController: Issue Command\n    RTSController-\u003e\u003eSelectionManager: Get Selected Units\n    SelectionManager-\u003e\u003eCommandManager: Selected Units List\n    CommandManager-\u003e\u003eUnitEntity: Execute Command\n    UnitEntity-\u003e\u003eStateMachine: Transition to Relevant State\n    StateMachine-\u003e\u003eUnitEntity: Perform Behavior\n\n```\n\n## One step back before you start\n\nTo dive into the framework:\n\n1. Review the **Core Systems** section to understand the overarching structure.\n2. Explore the **Entities** and **Components** sections to learn how game objects are built and extended.\n3. Check the **State System** section to see how behaviors are implemented and managed.\n4. Refer to **Managers** for details on handling gameplay-specific tasks like selection and commands.\n\n## Installation\n\nFollow these steps to install and integrate the RTS Framework into your Godot 4 project.\n\n### Download the framework\n\n#### Option 1: Using the Godot Asset Library\n\n1. Open your Godot project.\n2. Go to the **Asset Library** tab in the editor.\n3. Search for **RTS Framework**.\n4. Download and install the asset directly into your project.\n\n#### Option 2: Using GitHub\n\n1. Clone the repository or download the ZIP file:\n\n    ```bash\n    git clone https://github.com/rluders/rts-framework.git\n    ```\n\n2. Copy the `addons/rts_framework` folder into your Godot project directory.\n\n### Enable the Plugin\n\n- Open your Godot project.\n- Go to **Project Settings \u003e Plugins**.\n- Locate the **RTS Framework** in the list.\n- Enable the plugin by clicking **Activate**.\n\n### Add RTS Framework Nodes to Your Scene\n\n#### Step 1: Add the RTSController\n\n1. Create a new scene or open an existing one.\n2. Add the `RTSController` node to the scene (available in the **Create New Node** dialog under `Node -\u003e RTSController`).\n\n#### Step 2: Configure RTSController Subcomponents\n\n1. Add child nodes for `SelectionManager`, `CommandManager`, and any other required managers.\n2. Connect the necessary components, such as the `Raycaster` and `CameraController`, to the `RTSController`.\n\n### Setup Environment\n\n#### Step 1: Add a Ground Plane\n\n1. Add a `PlaneMesh` or a terrain scene to act as the ground.\n2. Ensure it has the correct collision layers for raycasting.\n\n#### Step 2: Add Lighting and Camera\n\n1. Add a `DirectionalLight3D` for global lighting.\n2. Add a `Camera3D` and position it for a top-down RTS view.\n\n### Test the Framework\n\n1. Add example scenes from the `addons/rts_framework/resources` folder:\n    - Example units (`Worker.tscn`, `Soldier.tscn`).\n    - Example buildings (`Barracks.tscn`, `Factory.tscn`).\n2. Play the scene to test unit selection, movement, and basic interactions.\n\n### Customize and Extend\n\n- Modify or extend the framework components to suit your game’s needs.\n- Review the provided documentation for detailed explanations of each system and how to integrate additional features.\n\n## Tutorials\n\n- [Selecting Units and Issuing Commands](./docs/tutorials/selecting_units_and_issuing_commands.md)\n- [Constructing a Building](./docs/tutorials/constructing_a_building_system.md)\n\n## Contribution\n\nWe welcome contributions to the RTS Framework! Whether you’re fixing bugs, adding new features, or improving the documentation, your input is highly appreciated. Follow these steps to contribute:\n\n### How to Contribute\n\n1. **Fork the Repository**:\n    - Start by forking the repository to your GitHub account.\n2. **Clone Your Fork**:\n\n    ```bash\n    git clone https://github.com/\u003cyour-username\u003e/rts-framework.git\n    cd rts-framework\n    ```\n\n3. **Create a New Branch**:\n    - Use a descriptive name for your branch:\n\n        ```bash\n        git checkout -b feature/my-new-feature\n        ```\n\n4. **Make Changes**:\n    - Implement your feature or fix, ensuring the code adheres to the project’s coding standards.\n5. **Test Your Changes**:\n    - Test thoroughly to ensure compatibility and stability.\n6. **Submit a Pull Request (PR)**:\n    - Push your changes to your fork:\n\n        ```bash\n        git push origin feature/my-new-feature\n        ```\n\n    - Open a pull request to the main repository. Provide a clear description of your changes, including the motivation and relevant details.\n\n### **Ways to Contribute**\n\n- **Report Bugs**: Use the GitHub Issues tab to report bugs or unexpected behavior.\n- **Suggest Features**: Share ideas for new features or improvements.\n- **Fix Issues**: Check the open issues for tasks you can help resolve.\n- **Improve Documentation**: Help make the documentation clearer and more comprehensive.\n\n## **Code of Conduct**\n\nPlease adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md) to ensure a welcoming and inclusive environment for all contributors.\n\n## **License**\n\nThis project is licensed under the MIT License. By contributing to this repository, you agree that your contributions will be licensed under the same MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frluders%2Frts-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frluders%2Frts-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frluders%2Frts-framework/lists"}