0.a. Detailed Project Architecture

Detailed Project Architecture

This page provides an in-depth look at the architecture of our Tactical RPG framework, explaining how Models and Modules work together to create a robust and scalable system.

Overview

We use a modular architecture that separates:

• Nodes and their respective script (Modules)
• Data containers and specialized logic services (Models)

This architecture enforces separation of concerns ("what is this script responsible for handling?"), better maintainability, scalability, and reusability of our (and soon your!) code.

Diagram

Models

Models are located in the /data/models/ directory.

They house:

• Data containers and interfaces (Resource Scripts)

  • Resources are interfaces leveraged by the Godot nodes.
    • They contain our object-state's single-source-of-truth and easy access to decoupled areas of the code.
    • They fire signals that connect decoupled areas of the code.

• Logic structures (Service scripts)

  • Services are reusable specialized utilities leveraged on-demand by Godot nodes.
    • service.gd is our master service. Its parent folder informs you of its purpose (e.g. /camera/tactics/service/service.gd handles only the TacticsCamera logic).
      • When the service is basic, all of our logic might happen inside the master Service script. No need for extreme fragmentation of our code!
      • When the service is complex, our master Service script is used as a router that directs the engine towards our smaller sub-services. In this case, it organises our logic and dispatches requests to the appropriate sub-service.

/models/ manifest as standalone, single-responsibility entities that can be leveraged by our Modules.

For instance:

• Global configurations
• Player Stats definition & handling
• Reusable utility services etc.

Key Components

• Resource Scripts (.gd files): Define the structure and behavior of resources
• Resources (.tres files): Define data and configurations for various game elements
• Service Scripts (.gd files): Logic and behaviour definition and handling. Contains code that shouldn't live directly inside its Node Module.

Structure

• config/: Global configuration & debug files
• view/camera/: Camera behaviour logic
• view/control/: Input and game control logic
• world/combat: Combat logic, from Arena to Participant handling
• world/stats: Stats definition and handling for our game actors
• world/utilities/: Utility scripts and helper functions (calculations, etc.)

Modules

Modules are located in the /data/modules/ directory.

They contain the main game logic, scenes, and initiator scripts that bring the Models to life.

Structure

• stats/: Handles game statistics and player stats

  • This is a good example to study if you want to understand how Modules translate in the Godot editor. Take a look at our Level scene under /assets/maps/level/ : test_level.tscn. Once opened, you can see our pawns all have an expertise node:

  

  It was added by drag & dropping our expertise.tscn scene and contains the expertise.gd script.

  

• tactics/: Contains tactical gameplay elements

  • camera/: Camera logic and scene
  • controls/: Input handling and UI controls
  • level/: Level-related logic and scenes

• ui/: User interface elements

Key Components

• Scene Scripts (.gd files): Contain the main logic for each module
• Scene Files (.tscn): Define the structure and Godot components of each module

Wrapping Up

How Models and Modules Work Together

1. Module Scene (module.tscn)

   • The Godot scene file that defines the structure of the module
   • Located alongside the module script, under its /data/modules/[category]/[module] subfolders

2. Module Scene Script (module.gd)

   • The main script for the module's scene
   • Interacts with the Resource Model and Master Service
   • Located in /data/modules/[category]/[module]

3. Resource Model (module_res.gd)

   • Contains signals and data for the parent module
   • Handles interfacing with the rest of the codebase on a per-request basis
   • Located in /data/models/[category]/[model]
   • Sometimes has a default instance saved as a Resource file in /data/models/[category]/[model]/model.tres

4. Master Service (service.gd)

   • Contains methods for the parent module's inner logic
   • Organizes all requests and dispatches responsibilities across specialized sub-services as needed
   • Located in res://data/models/[category]/[model]/service/

5. Sub Services (subservice_name.gd)

   • Hold specialized logic that cover specific aspects of the parent module's responsibilities
   • Located alongside the master service

Interaction Flow

1. The Module Scene Script instantiates the Resource Model and Master Service.
2. User input or game events trigger methods in the Module Scene Script.
3. The Module Scene Script calls appropriate methods on the Master Service.
4. The Master Service processes the request, using Subservices as needed.
5. The Master Service updates the Resource Model with any changes.
6. The Resource Model emits signals to notify the Module Scene Script of changes.
7. The Module Scene Script updates the scene based on the changes in the Resource Model.

---

Example: Camera System

Let's look at how the camera system is implemented using this architecture:

1. Resource Model: res://data/models/view/camera/tactics/t_cam_res.gd

   • Defines camera attributes like movement speed, zoom levels, and rotation angles
   • Contains signals for camera actions (move, rotate, zoom)

2. Master Service: res://data/models/view/camera/tactics/service/service.gd

   • Manages overall camera behavior
   • Dispatches specific tasks to sub-services

3. Sub Services:

   • movement.gd: Handles camera movement
   • rotation.gd: Manages camera rotation
   • zoom.gd: Controls camera zooming
   • panning.gd: Handles edge panning

4. Module Scene Script: res://data/modules/tactics/camera/camera.gd

   • Initializes the camera resource and service
   • Processes input and updates camera state
   • Calls service methods in response to game events

5. Module Scene: res://data/modules/tactics/camera/camera.tscn

   • Defines the structure of the camera object in the game world

This architecture allows for easy extension and modification of the camera system. For example, adding a new camera feature would involve creating a new sub-service and integrating it into the master service, without needing to modify the core camera logic.